channel: Add multi-tenant identifier.

This patch introduces a new identifier for channels: tenantid. It's
a stringfield on the channel that can be used for general purposes. It
will be inherited by other channels the same way that linkedid is.

You can set tenantid in a few ways. The first is to set it in the
dialplan with the Set and CHANNEL functions:

exten => example,1,Set(CHANNEL(tenantid)=My tenant ID)

It can also be accessed via CHANNEL:

exten => example,2,NoOp(CHANNEL(tenantid))

Another method is to use the new tenantid option for pjsip endpoints in
pjsip.conf:

[my_endpoint]
type=endpoint
tenantid=My tenant ID

This is considered the best approach since you will be able to see the
tenant ID as early as the Newchannel event.

It can also be set using set_var in pjsip.conf on the endpoint like
setting other channel variable:

set_var=CHANNEL(tenantid)=My tenant ID

Note that set_var will not show tenant ID on the Newchannel event,
however.

Tenant ID has also been added to CDR. It's read-only and can be accessed
via CDR(tenantid). You can also get the tenant ID of the last channel
communicated with via CDR(peertenantid).

Tenant ID will also show up in CEL records if it has been set, and the
version number has been bumped accordingly.

Fixes: #740

UserNote: tenantid has been added to channels. It can be read in
dialplan via CHANNEL(tenantid), and it can be set using
Set(CHANNEL(tenantid)=My tenant ID). In pjsip.conf, it is recommended to
use the new tenantid option for pjsip endpoints (e.g., tenantid=My
tenant ID) so that it will show up in Newchannel events. You can set it
like any other channel variable using set_var in pjsip.conf as well, but
note that this will NOT show up in Newchannel events. Tenant ID is also
available in CDR and can be accessed with CDR(tenantid). The peer tenant
ID can also be accessed with CDR(peertenantid). CEL includes tenant ID
as well if it has been set.

UpgradeNote: A new versioned struct (ast_channel_initializers) has been
added that gets passed to __ast_channel_alloc_ap. The new function
ast_channel_alloc_with_initializers should be used when creating
channels that require the use of this struct. Currently the only value
in the struct is for tenantid, but now more fields can be added to the
struct as necessary rather than the __ast_channel_alloc_ap function. A
new option (tenantid) has been added to endpoints in pjsip.conf as well.
CEL has had its version bumped to include tenant ID.

include/asterisk/cdr.h

@@ -317,6 +317,10 @@ struct ast_cdr {
 	char uniqueid[AST_MAX_UNIQUEID];
 	/*! Linked group Identifier */
 	char linkedid[AST_MAX_UNIQUEID];
+	/*! Channel tenant Identifier */
+	char tenantid[AST_MAX_TENANT_ID];
+	/*! Channel tenant Identifier of the last person we talked to */
+	char peertenantid[AST_MAX_TENANT_ID];
 	/*! User field */
 	char userfield[AST_MAX_USER_FIELD];
 	/*! Sequence field */

include/asterisk/cel.h

@@ -140,7 +140,7 @@ struct ast_cel_event_record {
 	 * \brief struct ABI version
 	 * \note This \b must be incremented when the struct changes.
 	 */
-	#define AST_CEL_EVENT_RECORD_VERSION 2
+	#define AST_CEL_EVENT_RECORD_VERSION 3
 	/*!
 	 * \brief struct ABI version
 	 * \note This \b must stay as the first member.
@@ -164,6 +164,7 @@ struct ast_cel_event_record {
 	const char *peer_account;
 	const char *unique_id;
 	const char *linked_id;
+	const char *tenant_id;
 	uint amaflag;
 	const char *user_field;
 	const char *peer;

include/asterisk/channel.h

@@ -146,6 +146,8 @@ extern "C" {
  */
 #define AST_MAX_PUBLIC_UNIQUEID 149
 
+#define AST_MAX_TENANT_ID 64 /*!< Max length of a channel tenant_id */
+
 /*!
  * The number of buckets to store channels or channel information
  */
@@ -606,6 +608,24 @@ struct ast_assigned_ids {
 	const char *uniqueid2;
 };
 
+/*!
+ * \brief Helper struct for initializing additional channel information on channel creation.
+ * \since 18.25.0
+ */
+struct ast_channel_initializers {
+	/*!
+	 * \brief struct ABI version
+	 * \note This \b must be incremented when the struct changes.
+	 */
+	#define AST_CHANNEL_INITIALIZERS_VERSION 1
+	/*!
+	 * \brief struct ABI version
+	 * \note This \b must stay as the first member.
+	 */
+	uint32_t version;
+	const char *tenantid;
+};
+
 /*!
  * \brief Forward declaration
  */
@@ -1244,6 +1264,27 @@ struct ast_channel * __attribute__((format(printf, 15, 16)))
 		const char *file, int line, const char *function,
 		const char *name_fmt, ...);
 
+/*!
+ * \brief Create a channel structure
+ * \since 18.25.0
+ *
+ * \retval NULL failure
+ * \retval non-NULL successfully allocated channel
+ *
+ * \note Absolutely _NO_ channel locks should be held before calling this function.
+ * \note By default, new channels are set to the "s" extension
+ *       and "default" context.
+ * \note Same as __ast_channel_alloc but with ast_channel_initializers struct.
+ */
+struct ast_channel * __attribute__((format(printf, 16, 17)))
+	__ast_channel_alloc_with_initializers(int needqueue, int state, const char *cid_num,
+		const char *cid_name, const char *acctcode,
+		const char *exten, const char *context, const struct ast_assigned_ids *assignedids,
+		const struct ast_channel *requestor, enum ama_flags amaflag,
+		struct ast_endpoint *endpoint, struct ast_channel_initializers *initializers,
+		const char *file, int line, const char *function,
+		const char *name_fmt, ...);
+
 /*!
  * \brief Create a channel structure
  *
@@ -1263,6 +1304,11 @@ struct ast_channel * __attribute__((format(printf, 15, 16)))
 	__ast_channel_alloc((needqueue), (state), (cid_num), (cid_name), (acctcode), (exten), (context), (assignedids), (requestor), (amaflag), (endpoint), \
 		__FILE__, __LINE__, __FUNCTION__, __VA_ARGS__)
 
+#define ast_channel_alloc_with_initializers(needqueue, state, cid_num, cid_name, acctcode, exten, context, assignedids, requestor, amaflag, endpoint, initializers, ...) \
+	__ast_channel_alloc_with_initializers((needqueue), (state), (cid_num), (cid_name), (acctcode), (exten), (context), (assignedids), (requestor), (amaflag), (endpoint), \
+		(initializers), __FILE__, __LINE__, __FUNCTION__, __VA_ARGS__)
+
+
 /*!
  * \brief Create a fake channel structure
  *
@@ -4151,6 +4197,8 @@ const char *ast_channel_userfield(const struct ast_channel *chan);
 const char *ast_channel_call_forward(const struct ast_channel *chan);
 const char *ast_channel_uniqueid(const struct ast_channel *chan);
 const char *ast_channel_linkedid(const struct ast_channel *chan);
+const char *ast_channel_tenantid(const struct ast_channel *chan);
+void ast_channel_tenantid_set(struct ast_channel *chan, const char *value);
 const char *ast_channel_parkinglot(const struct ast_channel *chan);
 const char *ast_channel_hangupsource(const struct ast_channel *chan);
 const char *ast_channel_dialcontext(const struct ast_channel *chan);

include/asterisk/channel_internal.h

@@ -23,6 +23,8 @@
 
 #define ast_channel_internal_alloc(destructor, assignedid, requestor) __ast_channel_internal_alloc(destructor, assignedid, requestor, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 struct ast_channel *__ast_channel_internal_alloc(void (*destructor)(void *obj), const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *file, int line, const char *function);
+struct ast_channel *__ast_channel_internal_alloc_with_initializers(void (*destructor)(void *obj), const struct ast_assigned_ids *assignedids,
+	const struct ast_channel *requestor, const struct ast_channel_initializers *initializers, const char *file, int line, const char *function);
 void ast_channel_internal_finalize(struct ast_channel *chan);
 int ast_channel_internal_is_finalized(struct ast_channel *chan);
 void ast_channel_internal_cleanup(struct ast_channel *chan);

include/asterisk/event_defs.h

@@ -311,8 +311,15 @@ enum ast_event_ie_type {
 	 * Payload type: UINT
 	 */
 	AST_EVENT_IE_NODE_ID             = 0x003e,
+
+	/*!
+	 * \brief Channel Event TenantID
+	 * Used by: AST_EVENT_CEL
+	 * Payload type: STR
+	 */
+	AST_EVENT_IE_CEL_TENANTID	= 0x003f,
 	/*! \brief Must be the last IE value +1 */
-	AST_EVENT_IE_TOTAL               = 0x003f,
+	AST_EVENT_IE_TOTAL               = 0x0040,
 };
 
 /*!

include/asterisk/res_pjsip.h

@@ -987,6 +987,8 @@ struct ast_sip_endpoint {
 		AST_STRING_FIELD(incoming_mwi_mailbox);
 		/*! STIR/SHAKEN profile to use */
 		AST_STRING_FIELD(stir_shaken_profile);
+		/*! Tenant ID for the endpoint */
+		AST_STRING_FIELD(tenantid);
 	);
 	/*! Configuration for extensions */
 	struct ast_sip_endpoint_extensions extensions;

include/asterisk/stasis_channels.h

@@ -109,6 +109,7 @@ struct ast_channel_snapshot_base {
 		AST_STRING_FIELD(userfield);   /*!< Userfield for CEL billing */
 		AST_STRING_FIELD(language);    /*!< The default spoken language for the channel */
 		AST_STRING_FIELD(type);        /*!< Type of channel technology */
+		AST_STRING_FIELD(tenantid);    /*!< Channel tenant identifier */
 	);
 	struct timeval creationtime; /*!< The time of channel creation */
 	int tech_properties;         /*!< Properties of the channel's technology */