channel locking: Add locking for channel snapshot creation

Original commit message by mmichelson (asterisk 12 r403311):

"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."

The above was initially committed and then reverted at r403398.  The problem
was found to be in core_local.c in the publish_local_bridge_message function.
The ast_unreal_lock_all function locks and adds a reference to the returned
channels and while they were being unlocked they were not being unreffed when
no longer needed.  Fixed by unreffing the channels.

Also in bridge.c a lock was obtained on "other->chan", but then an attempt was
made to unlock "other" and not the previously locked channel.  Fixed by
unlocking "other->chan"

(closes issue ASTERISK-22709)
Reported by: John Bigelow
........

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


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

include/asterisk/stasis_channels.h

@@ -153,6 +153,8 @@ struct stasis_message_type *ast_channel_snapshot_type(void);
  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
  * ao2_cleanup() to deallocate.
  *
+ * \pre chan is locked
+ *
  * \param chan The channel from which to generate a snapshot
  *
  * \retval pointer on success (must be unreffed)
@@ -192,6 +194,8 @@ struct ast_channel_snapshot *ast_channel_snapshot_get_latest_by_name(const char
  * The given \a blob should be treated as immutable and not modified after it is
  * put into the message.
  *
+ * \pre chan is locked
+ *
  * \param chan Channel blob is associated with, or \c NULL for global/all channels.
  * \param type Message type for this blob.
  * \param blob JSON object representing the data, or \c NULL for no data. If
@@ -305,6 +309,8 @@ void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
  * \brief Publish a channel blob message.
  * \since 12.0.0
  *
+ * \pre chan is locked
+ *
  * \param chan Channel publishing the blob.
  * \param type Type of stasis message.
  * \param blob The blob being published. (NULL if no blob)
@@ -318,6 +324,8 @@ void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_ty
  * \since 12
  * \brief Set flag to indicate channel snapshot is being staged.
  *
+ * \pre chan is locked
+ *
  * \param chan Channel being staged.
  */
 void ast_channel_stage_snapshot(struct ast_channel *chan);
@@ -326,6 +334,8 @@ void ast_channel_stage_snapshot(struct ast_channel *chan);
  * \since 12
  * \brief Clear flag to indicate channel snapshot is being staged, and publish snapshot.
  *
+ * \pre chan is locked
+ *
  * \param chan Channel being staged.
  */
 void ast_channel_stage_snapshot_done(struct ast_channel *chan);
@@ -334,6 +344,8 @@ void ast_channel_stage_snapshot_done(struct ast_channel *chan);
  * \since 12
  * \brief Publish a \ref ast_channel_snapshot for a channel.
  *
+ * \pre chan is locked
+ *
  * \param chan Channel to publish.
  */
 void ast_channel_publish_snapshot(struct ast_channel *chan);
@@ -342,6 +354,8 @@ void ast_channel_publish_snapshot(struct ast_channel *chan);
  * \since 12
  * \brief Publish a \ref ast_channel_varset for a channel.
  *
+ * \pre chan is locked
+ *
  * \param chan Channel to publish the event for, or \c NULL for 'none'.
  * \param variable Name of the variable being set
  * \param value Value.
@@ -535,6 +549,8 @@ void ast_channel_publish_dial_forward(struct ast_channel *caller,
  * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
  * message indicating a change in channel state
  *
+ * \pre chan is locked
+ *
  * \param chan The channel whose state has changed
  */
 void ast_publish_channel_state(struct ast_channel *chan);