Add channel locking for channel snapshot creation.

This adds channel locks around calls to create channel snapshots as well
as other functions which operate on a channel and then end up
creating a channel snapshot. Functions that expect the channel to be
locked prior to being called have had their documentation updated to
indicate such.
........

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


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

1 files changed, 21 insertions, 0 deletions

diff --git a/include/asterisk/stasis_bridges.h b/include/asterisk/stasis_bridges.h
index 9412bf0b7..78b97d188 100644
--- a/include/asterisk/stasis_bridges.h
+++ b/include/asterisk/stasis_bridges.h
@@ -199,6 +199,9 @@ struct stasis_message_type *ast_channel_left_bridge_type(void);
  * should also be treated as immutable and not modified after it is put into the
  * message.
  *
+ * \pre bridge is locked.
+ * \pre No channels are locked.
+ *
  * \param bridge Channel blob is associated with, or NULL for global/all bridges.
  * \param blob JSON object representing the data.
  * \return \ref ast_bridge_blob message.
@@ -213,6 +216,9 @@ struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
  * \since 12
  * \brief Publish a bridge channel enter event
  *
+ * \pre bridge is locked.
+ * \pre No channels are locked.
+ *
  * \param bridge The bridge a channel entered
  * \param chan The channel that entered the bridge
  * \param swap The channel being swapped out of the bridge
@@ -224,6 +230,9 @@ void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *cha
  * \since 12
  * \brief Publish a bridge channel leave event
  *
+ * \pre bridge is locked.
+ * \pre No channels are locked.
+ *
  * \param bridge The bridge a channel left
  * \param chan The channel that left the bridge
  */
@@ -268,6 +277,8 @@ struct stasis_message_type *ast_blind_transfer_type(void);
 /*!
  * \brief Publish a blind transfer event
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
  * \param result The success or failure of the transfer
  * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
@@ -331,6 +342,8 @@ struct stasis_message_type *ast_attended_transfer_type(void);
  * Publish an \ref ast_attended_transfer_message with the dest_type set to
  * \c AST_ATTENDED_TRANSFER_DEST_FAIL.
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Indicates if the transfer was initiated externally
  * \param result The result of the transfer. Will always be a type of failure.
  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
@@ -352,6 +365,8 @@ void ast_bridge_publish_attended_transfer_fail(int is_external, enum ast_transfe
  *
  * In either case, two bridges enter, one leaves.
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Indicates if the transfer was initiated externally
  * \param result The result of the transfer.
  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
@@ -371,6 +386,8 @@ void ast_bridge_publish_attended_transfer_bridge_merge(int is_external, enum ast
  * this results from merging two bridges together. The difference is that a
  * transferer channel survives the bridge merge
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Indicates if the transfer was initiated externally
  * \param result The result of the transfer.
  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
@@ -392,6 +409,8 @@ void ast_bridge_publish_attended_transfer_threeway(int is_external, enum ast_tra
  * \li A transferee channel leaving a bridge to run an app
  * \li A bridge of transferees running an app (via a local channel)
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Indicates if the transfer was initiated externally
  * \param result The result of the transfer.
  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
@@ -415,6 +434,8 @@ void ast_bridge_publish_attended_transfer_app(int is_external, enum ast_transfer
  * When this type of transfer occurs, the two bridges continue to exist after the
  * transfer and a local channel is used to link the two bridges together.
  *
+ * \pre No channels or bridges are locked
+ *
  * \param is_external Indicates if the transfer was initiated externally
  * \param result The result of the transfer.
  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge