uniqueid: channel linkedid, ami, ari object creation with id's

Much needed was a way to assign id to objects on creation, and
much change was necessary to accomplish it.  Channel uniqueids
and linkedids are split into separate string and creation time
components without breaking linkedid propgation.  This allowed
the uniqueid to be specified by the user interface - and those
values are now carried through to channel creation, adding the
assignedids value to every function in the chain including the
channel drivers. For local channels, the second channel can be
specified or left to default to a ;2 suffix of first.  In ARI,
bridge, playback, and snoop objects can also be created with a
specified uniqueid.

Along the way, the args order to allocating channels was fixed
in chan_mgcp and chan_gtalk, and linkedid is no longer lost as
masquerade occurs.

(closes issue ASTERISK-23120)
Review: https://reviewboard.asterisk.org/r/3191/
........

Merged revisions 410157 from http://svn.asterisk.org/svn/asterisk/branches/12


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@410158 65c4cc65-6c06-0410-ace0-fbb531ad65f3

10 files changed, 85 insertions, 22 deletions

diff --git a/include/asterisk/bridge.h b/include/asterisk/bridge.h
index 0706b3aed..d8c27f4f2 100644
--- a/include/asterisk/bridge.h
+++ b/include/asterisk/bridge.h
@@ -333,6 +333,7 @@ extern struct ast_bridge_methods ast_bridge_base_v_table;
  * \param flags Flags that will alter the behavior of the bridge
  * \param creator Entity that created the bridge (optional)
  * \param name Name given to the bridge by its creator (optional, requires named creator)
+ * \param name id Unique ID given to the bridge by its creator (optional)
  *
  * \retval a pointer to a new bridge on success
  * \retval NULL on failure
@@ -347,7 +348,7 @@ extern struct ast_bridge_methods ast_bridge_base_v_table;
  * This creates a no frills two party bridge that will be
  * destroyed once one of the channels hangs up.
  */
-struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name);
+struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
 
 /*!
  * \brief Try locking the bridge.
diff --git a/include/asterisk/bridge_internal.h b/include/asterisk/bridge_internal.h
index e9726a1ab..e50e7f987 100644
--- a/include/asterisk/bridge_internal.h
+++ b/include/asterisk/bridge_internal.h
@@ -89,6 +89,7 @@ struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_
  * \param flags Flags that will alter the behavior of the bridge
  * \param creator Entity that created the bridge (optional)
  * \param name Name given to the bridge by its creator (optional, requires named creator)
+ * \param id Unique ID given to the bridge by its creator (optional)
  *
  * \retval self on success
  * \retval NULL on failure, self is already destroyed
@@ -98,13 +99,13 @@ struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_
  * \code
  * struct ast_bridge *bridge;
  * bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
- * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP, NULL, NULL);
+ * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP, NULL, NULL, NULL);
  * \endcode
  *
  * This creates a no frills two party bridge that will be
  * destroyed once one of the channels hangs up.
  */
-struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags, const char *creator, const char *name);
+struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
 
 /*!
  * \internal
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 106117de1..aa2f8634b 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -562,6 +562,15 @@ typedef struct {
 } ast_chan_write_info_t;
 
 /*!
+ * \brief Structure to pass both assignedid values to channel drivers
+ * \note The second value is used only by core_unreal (LOCAL)
+ */
+struct ast_assigned_ids {
+	const char *uniqueid;
+	const char *uniqueid2;
+};
+
+/*!
  * \brief
  * Structure to describe a channel "technology", ie a channel driver
  * See for examples:
@@ -588,6 +597,7 @@ struct ast_channel_tech {
 	 *
 	 * \param type type of channel to request
 	 * \param cap Format capabilities for requested channel
+	 * \param assignedid Unique ID string to assign to channel
 	 * \param requestor channel asking for data
 	 * \param addr destination of the call
 	 * \param cause Cause of failure
@@ -599,7 +609,7 @@ struct ast_channel_tech {
 	 * \retval NULL failure
 	 * \retval non-NULL channel on success
 	 */
-	struct ast_channel *(* const requester)(const char *type, struct ast_format_cap *cap, const struct ast_channel *requestor, const char *addr, int *cause);
+	struct ast_channel *(* const requester)(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause);
 
 	int (* const devicestate)(const char *device_number);	/*!< Devicestate call back */
 
@@ -1129,11 +1139,11 @@ struct ast_datastore *ast_channel_datastore_find(struct ast_channel *chan, const
  *       and "default" context.
  * \note Since 12.0.0 this function returns with the newly created channel locked.
  */
-struct ast_channel * attribute_malloc __attribute__((format(printf, 13, 14)))
+struct ast_channel * attribute_malloc __attribute__((format(printf, 14, 15)))
 	__ast_channel_alloc(int needqueue, int state, const char *cid_num,
 		const char *cid_name, const char *acctcode,
-		const char *exten, const char *context,
-		const char *linkedid, enum ama_flags amaflag,
+		const char *exten, const char *context, const struct ast_assigned_ids *assignedids,
+		const struct ast_channel *requestor, enum ama_flags amaflag,
 		const char *file, int line, const char *function,
 		const char *name_fmt, ...);
 
@@ -1148,8 +1158,8 @@ struct ast_channel * attribute_malloc __attribute__((format(printf, 13, 14)))
  *       and "default" context.
  * \note Since 12.0.0 this function returns with the newly created channel locked.
  */
-#define ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, linkedid, amaflag, ...) \
-	__ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, linkedid, amaflag, \
+#define ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, assignedids, requestor, amaflag, ...) \
+	__ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, assignedids, requestor, amaflag, \
 		__FILE__, __LINE__, __FUNCTION__, __VA_ARGS__)
 
 #if defined(REF_DEBUG) || defined(__AST_DEBUG_MALLOC)
@@ -1338,6 +1348,7 @@ struct ast_channel *ast_channel_release(struct ast_channel *chan);
  *
  * \param type type of channel to request
  * \param request_cap Format capabilities for requested channel
+ * \param assignedids Unique ID to create channel with
  * \param requestor channel asking for data
  * \param addr destination of the call
  * \param cause Cause of failure
@@ -1349,7 +1360,7 @@ struct ast_channel *ast_channel_release(struct ast_channel *chan);
  * \retval NULL failure
  * \retval non-NULL channel on success
  */
-struct ast_channel *ast_request(const char *type, struct ast_format_cap *request_cap, const struct ast_channel *requestor, const char *addr, int *cause);
+struct ast_channel *ast_request(const char *type, struct ast_format_cap *request_cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause);
 
 /*!
  * \brief Request a channel of a given type, with data as optional information used
@@ -1357,6 +1368,7 @@ struct ast_channel *ast_request(const char *type, struct ast_format_cap *request
  *
  * \param type type of channel to request
  * \param cap format capabilities for requested channel
+ * \param assignedids Unique Id to assign to channel
  * \param requestor channel asking for data
  * \param addr destination of the call
  * \param timeout maximum amount of time to wait for an answer
@@ -1367,7 +1379,7 @@ struct ast_channel *ast_request(const char *type, struct ast_format_cap *request
  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
  * to know if the call was answered or not.
  */
-struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap *cap, const struct ast_channel *requestor, const char *addr,
+struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr,
 	int timeout, int *reason, const char *cid_num, const char *cid_name);
 
 /*!
@@ -1375,6 +1387,7 @@ struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap
  * by the low level module and attempt to place a call on it
  * \param type type of channel to request
  * \param cap format capabilities for requested channel
+ * \param assignedids Unique Id to assign to channel
  * \param requestor channel requesting data
  * \param addr destination of the call
  * \param timeout maximum amount of time to wait for an answer
@@ -1385,7 +1398,7 @@ struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap
  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
  * to know if the call was answered or not.
  */
-struct ast_channel *__ast_request_and_dial(const char *type, struct ast_format_cap *cap, const struct ast_channel *requestor, const char *addr,
+struct ast_channel *__ast_request_and_dial(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr,
 	int timeout, int *reason, const char *cid_num, const char *cid_name, struct outgoing_helper *oh);
 
 /*!
@@ -2365,6 +2378,46 @@ void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_sil
  */
 int ast_internal_timing_enabled(struct ast_channel *chan);
 
+/*!
+ * \brief Determine which channel has an older linkedid
+ * \param a First channel
+ * \param b Second channel
+ * \return Returns an ast_channel structure that has oldest linkedid
+ */
+struct ast_channel *ast_channel_internal_oldest_linkedid(struct ast_channel *a, struct ast_channel *b);
+
+/*!
+ * \brief Copy the full linkedid channel id structure from one channel to another
+ * \param dest Destination to copy linkedid to
+ * \param source Source channel to copy linkedid from
+ * \return void
+ */
+void ast_channel_internal_copy_linkedid(struct ast_channel *dest, struct ast_channel *source);
+
+/*!
+ * \brief Swap uniqueid and linkedid beteween two channels
+ * \param a First channel
+ * \param b Second channel
+ * \return void
+ *
+ * \note
+ * This is used in masquerade to exchange identities
+ */
+void ast_channel_internal_swap_uniqueid_and_linkedid(struct ast_channel *a, struct ast_channel *b);
+
+/*!
+ * \brief Set uniqueid and linkedid string value only (not time)
+ * \param chan The channel to set the uniqueid to
+ * \param uniqueid The uniqueid to set
+ * \param linkedid The linkedid to set
+ * \return void
+ *
+ * \note
+ * This is used only by ast_cel_fabricate_channel_from_event()
+ * to create a temporary fake channel - time values are invalid
+ */
+void ast_channel_internal_set_fake_ids(struct ast_channel *chan, const char *uniqueid, const char *linkedid);
+
 /* Misc. functions below */
 
 /*!
diff --git a/include/asterisk/channel_internal.h b/include/asterisk/channel_internal.h
index c94cc46f7..d1231b400 100644
--- a/include/asterisk/channel_internal.h
+++ b/include/asterisk/channel_internal.h
@@ -18,8 +18,8 @@
  * \brief Internal channel functions for channel.c to use
  */
 
-#define ast_channel_internal_alloc(destructor, linkedid) __ast_channel_internal_alloc(destructor, linkedid, __FILE__, __LINE__, __PRETTY_FUNCTION__)
-struct ast_channel *__ast_channel_internal_alloc(void (*destructor)(void *obj), const char *linkedid, const char *file, int line, const char *function);
+#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);
 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);
diff --git a/include/asterisk/core_unreal.h b/include/asterisk/core_unreal.h
index cd8a2cdf7..e118c74bd 100644
--- a/include/asterisk/core_unreal.h
+++ b/include/asterisk/core_unreal.h
@@ -206,8 +206,8 @@ struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructo
  */
 struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
 	const struct ast_channel_tech *tech, int semi1_state, int semi2_state,
-	const char *exten, const char *context, const struct ast_channel *requestor,
-	struct ast_callid *callid);
+	const char *exten, const char *context, const struct ast_assigned_ids *assignedids, 
+	const struct ast_channel *requestor, struct ast_callid *callid);
 
 /*!
  * \brief Setup unreal owner and chan channels before initiating call.
diff --git a/include/asterisk/dial.h b/include/asterisk/dial.h
index 19b1c8753..b61116f8e 100644
--- a/include/asterisk/dial.h
+++ b/include/asterisk/dial.h
@@ -72,7 +72,7 @@ struct ast_dial *ast_dial_create(void);
  * \note Appends a channel to a dialing structure
  * \return Returns channel reference number on success, -1 on failure
  */
-int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device);
+int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device, const struct ast_assigned_ids *assignedids);
 
 /*! \brief Request all appended channels, but do not dial
  * \param dial Dialing structure
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 77694a54c..784b976cc 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -1122,12 +1122,15 @@ int ast_async_goto_by_name(const char *chan, const char *context, const char *ex
  * \param locked_channel Optional. The outbound channel that was created. This is returned
  *  both locked and reference bumped. If a caller provides a channel parameter, it must
  *  unlock the channel and decrement the reference count.
+ *  \param assignedid Optional. The uniqueid to assign the channel that was created.
+ *  \param assignedid2 Optional. The uniqueid to assign the second local channel.
  * \param early_media If non-zero, allow early-media on the originated channel
  */
 int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr,
     int timeout, const char *context, const char *exten, int priority, int *reason,
     int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars,
-    const char *account, struct ast_channel **locked_channel, int early_media);
+    const char *account, struct ast_channel **locked_channel, int early_media,
+	const struct ast_assigned_ids *assignedids);
 
 /*! \brief Synchronously or asynchronously make an outbound call and execute an
  *  application on the channel.
@@ -1148,13 +1151,16 @@ int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const c
  * \param vars Variables to set on the outbound channel
  * \param account The accountcode for the outbound channel
  * \param locked_channel Optional. The outbound channel that was created. This is returned
+ *  \param assignedid Optional. The uniqueid to assign the channel that was created.
+ *  \param assignedid2 Optional. The uniqueid to assign the second local channel.
  *  both locked and reference bumped. If a caller provides a channel parameter, it must
  *  unlock the channel and decrement the reference count.
  */
 int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr,
     int timeout, const char *app, const char *appdata, int *reason, int sync,
     const char *cid_num, const char *cid_name, struct ast_variable *vars,
-    const char *account, struct ast_channel **locked_channel);
+    const char *account, struct ast_channel **locked_channel,
+	const struct ast_assigned_ids *assignedids);
 
 /*!
  * \brief Evaluate a condition
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index ac5c64893..40ec208d6 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -598,11 +598,12 @@ int stasis_app_control_queue_control(struct stasis_app_control *control,
  *
  * \param type The type of bridge to be created
  * \param name Optional name to give to the bridge
+ * \param id Optional Unique ID to give to the bridge
  *
  * \return New bridge.
  * \return \c NULL on error.
  */
-struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name);
+struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
 
 /*!
  * \brief Returns the bridge with the given id.
diff --git a/include/asterisk/stasis_app_playback.h b/include/asterisk/stasis_app_playback.h
index 3587871a9..b35299581 100644
--- a/include/asterisk/stasis_app_playback.h
+++ b/include/asterisk/stasis_app_playback.h
@@ -90,6 +90,7 @@ enum stasis_app_playback_target_type {
  * \param target_type What the target type is
  * \param skipms Number of milliseconds to skip for forward/reverse operations.
  * \param offsetms Number of milliseconds to skip before playing.
+ * \param id ID to assign the new playback or NULL for default.
  * \return Playback control object.
  * \return \c NULL on error.
  */
@@ -97,7 +98,7 @@ struct stasis_app_playback *stasis_app_control_play_uri(
 	struct stasis_app_control *control, const char *file,
 	const char *language, const char *target_id,
 	enum stasis_app_playback_target_type target_type,
-	int skipms, long offsetms);
+	int skipms, long offsetms, const char *id);
 
 /*!
  * \brief Gets the current state of a playback operation.
diff --git a/include/asterisk/stasis_app_snoop.h b/include/asterisk/stasis_app_snoop.h
index a9c998f03..c261a88b8 100644
--- a/include/asterisk/stasis_app_snoop.h
+++ b/include/asterisk/stasis_app_snoop.h
@@ -55,6 +55,6 @@ enum stasis_app_snoop_direction {
  */
 struct ast_channel *stasis_app_control_snoop(struct ast_channel *chan,
 	enum stasis_app_snoop_direction spy, enum stasis_app_snoop_direction whisper,
-	const char *app, const char *app_args);
+	const char *app, const char *app_args, const char *snoop_id);
 
 #endif /* _ASTERISK_STASIS_APP_SNOOP_H */