Update bridge_channel refactorings; export bridge_ symbol

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

3 files changed, 169 insertions, 166 deletions

diff --git a/include/asterisk/bridging_channel.h b/include/asterisk/bridging_channel.h
index 630e6d6f0..cdbb2ec5d 100644
--- a/include/asterisk/bridging_channel.h
+++ b/include/asterisk/bridging_channel.h
@@ -22,7 +22,20 @@
  * \file
  * \brief Bridging Channel API
  *
- * An API that act on a channel in a bridge
+ * An API that act on a channel in a bridge. Note that while the
+ * \ref ast_bridge_channel is owned by a channel, it should only be used
+ * by members of the bridging system. The only places where this API should
+ * be used is:
+ *  - The \ref AstBridging API itself
+ *  - Bridge mixing technologies
+ *  - Bridge sub-classes
+ *
+ * In general, anywhere else it is unsafe to use this API. Care should be
+ * taken when using this API to ensure that the locking order remains
+ * correct. The locking order must be:
+ *  - The \ref ast_bridge
+ *  - The \ref ast_bridge_channel
+ *  - The \ref ast_channel
  *
  * \author Joshua Colp <jcolp@digium.com>
  * \author Richard Mudgett <rmudgett@digium.com>
@@ -48,8 +61,8 @@ enum ast_bridge_channel_state {
 	AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
 	/*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
 	AST_BRIDGE_CHANNEL_STATE_END,
-	/*! Bridged channel was forced out and should be hung up */
-	AST_BRIDGE_CHANNEL_STATE_HANGUP,
+	/*! Bridged channel was forced out. Don't dissolve the bridge regardless */
+	AST_BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE,
 };
 
 enum ast_bridge_channel_thread_state {
@@ -61,43 +74,6 @@ enum ast_bridge_channel_thread_state {
 	AST_BRIDGE_CHANNEL_THREAD_FRAME,
 };
 
-/*! \brief Actions that can be taken on a channel in a bridge */
-enum ast_bridge_action_type {
-	/*! Bridged channel is to detect a feature hook */
-	AST_BRIDGE_ACTION_FEATURE,
-	/*! Bridged channel is to act on an interval hook */
-	AST_BRIDGE_ACTION_INTERVAL,
-	/*! Bridged channel is to send a DTMF stream out */
-	AST_BRIDGE_ACTION_DTMF_STREAM,
-	/*! Bridged channel is to indicate talking start */
-	AST_BRIDGE_ACTION_TALKING_START,
-	/*! Bridged channel is to indicate talking stop */
-	AST_BRIDGE_ACTION_TALKING_STOP,
-	/*! Bridge channel is to play the indicated sound file. */
-	AST_BRIDGE_ACTION_PLAY_FILE,
-	/*! Bridge channel is to run the indicated application. */
-	AST_BRIDGE_ACTION_RUN_APP,
-	/*! Bridge channel is to run the custom callback routine. */
-	AST_BRIDGE_ACTION_CALLBACK,
-	/*! Bridge channel is to get parked. */
-	AST_BRIDGE_ACTION_PARK,
-	/*! Bridge channel is to execute a blind transfer. */
-	AST_BRIDGE_ACTION_BLIND_TRANSFER,
-	/*! Bridge channel is to execute an attended transfer */
-	AST_BRIDGE_ACTION_ATTENDED_TRANSFER,
-
-	/*
-	 * Bridge actions put after this comment must never be put onto
-	 * the bridge_channel wr_queue because they have other resources
-	 * that must be freed.
-	 */
-
-	/*! Bridge reconfiguration deferred technology destruction. */
-	AST_BRIDGE_ACTION_DEFERRED_TECH_DESTROY = 1000,
-	/*! Bridge deferred dissolving. */
-	AST_BRIDGE_ACTION_DEFERRED_DISSOLVING,
-};
-
 struct ast_bridge;
 struct ast_bridge_tech_optimizations;
 
@@ -241,77 +217,52 @@ static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_
 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
 
 /*!
- * \brief Ask the bridged channel to leave the bridge it is currently in
- *
- * \param bridge_channel Channel to leave the bridge
- */
-void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel);
-
-/*!
- * \brief Ask the bridged channel to leave the bridge it is currently in
+ * \brief Set bridge channel state to leave bridge (if not leaving already).
  *
- * \param bridge_channel Channel to leave the bridge
+ * \param bridge_channel Channel to change the state on
+ * \param new_state The new state to place the channel into
  *
- * \note This function assumes the bridge_channel is locked.
- */
-void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel);
-
-/*!
- * \brief Write a frame to the specified bridge_channel.
- * \since 12.0.0
- *
- * \param bridge_channel Channel to queue the frame.
- * \param fr Frame to write.
+ * Example usage:
  *
- * \retval 0 on success.
- * \retval -1 on error.
+ * \code
+ * ast_bridge_channel_leave_bridge(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
+ * \endcode
  *
- * \note This API call is meant for internal bridging operations.
- * \note BUGBUG This may get moved.
+ * This places the channel pointed to by bridge_channel into the
+ * state AST_BRIDGE_CHANNEL_STATE_END if it was
+ * AST_BRIDGE_CHANNEL_STATE_WAIT before.
  */
-int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
+void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
 
 /*!
- * \brief Used to queue an action frame onto a bridge channel and write an action frame into a bridge.
- * \since 12.0.0
+ * \brief Set bridge channel state to leave bridge (if not leaving already).
  *
- * \param bridge_channel Which channel work with.
- * \param action Type of bridge action frame.
- * \param data Frame payload data to pass.
- * \param datalen Frame payload data length to pass.
+ * \param bridge_channel Channel to change the state on
+ * \param new_state The new state to place the channel into
  *
- * \retval 0 on success.
- * \retval -1 on error.
- */
-typedef int (*ast_bridge_channel_post_action_data)(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
-
-/*!
- * \brief Queue an action frame onto the bridge channel with data.
- * \since 12.0.0
+ * Example usage:
  *
- * \param bridge_channel Which channel to queue the frame onto.
- * \param action Type of bridge action frame.
- * \param data Frame payload data to pass.
- * \param datalen Frame payload data length to pass.
+ * \code
+ * ast_bridge_channel_leave_bridge(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
+ * \endcode
  *
- * \retval 0 on success.
- * \retval -1 on error.
+ * This places the channel pointed to by bridge_channel into the
+ * state AST_BRIDGE_CHANNEL_STATE_END if it was
+ * AST_BRIDGE_CHANNEL_STATE_WAIT before.
  */
-int ast_bridge_channel_queue_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
+void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
 
 /*!
- * \brief Write an action frame into the bridge with data.
+ * \brief Write a frame to the specified bridge_channel.
  * \since 12.0.0
  *
- * \param bridge_channel Which channel is putting the frame into the bridge.
- * \param action Type of bridge action frame.
- * \param data Frame payload data to pass.
- * \param datalen Frame payload data length to pass.
+ * \param bridge_channel Channel to queue the frame.
+ * \param fr Frame to write.
  *
  * \retval 0 on success.
  * \retval -1 on error.
  */
-int ast_bridge_channel_write_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
+int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
 
 /*!
  * \brief Queue a control frame onto the bridge channel with data.
@@ -569,6 +520,56 @@ void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channe
  */
 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
 
+struct blind_transfer_data {
+	char exten[AST_MAX_EXTENSION];
+	char context[AST_MAX_CONTEXT];
+};
+
+/*!
+ * \brief Adjust the bridge_channel's bridge merge inhibit request count.
+ * \since 12.0.0
+ *
+ * \param bridge_channel What to operate on.
+ * \param request Inhibit request increment.
+ *     (Positive to add requests.  Negative to remove requests.)
+ *
+ * \note This API call is meant for internal bridging operations.
+ *
+ * \retval bridge adjusted merge inhibit with reference count.
+ */
+struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
+
+/*!
+ * \internal
+ * \brief Update the linkedids for all channels in a bridge
+ * \since 12.0.0
+ *
+ * \param bridge_channel The channel joining the bridge
+ * \param swap The channel being swapped out of the bridge. May be NULL.
+ *
+ * \note The bridge must be locked prior to calling this function. This should be called
+ * during a \ref bridge_channel_push operation, typically by a sub-class of a bridge
+ */
+void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
+
+/*!
+ * \internal
+ * \brief Update the accountcodes for a channel entering a bridge
+ * \since 12.0.0
+ *
+ * This function updates the accountcode and peeraccount on channels in two-party
+ * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
+ * however accountcode propagation will still occur if the channel joining has an
+ * accountcode.
+ *
+ * \param bridge_channel The channel joining the bridge
+ * \param swap The channel being swapped out of the bridge. May be NULL.
+ *
+ * \note The bridge must be locked prior to calling this function. This should be called
+ * during a \ref bridge_channel_push operation, typically by a sub-class of a bridge
+ */
+void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif
diff --git a/include/asterisk/bridging_channel_internal.h b/include/asterisk/bridging_channel_internal.h
index b22b8d69e..9bc9b11f9 100644
--- a/include/asterisk/bridging_channel_internal.h
+++ b/include/asterisk/bridging_channel_internal.h
@@ -33,24 +33,59 @@
 #ifndef _ASTERISK_PRIVATE_BRIDGING_CHANNEL_H
 #define _ASTERISK_PRIVATE_BRIDGING_CHANNEL_H
 
-struct blind_transfer_data {
-	char exten[AST_MAX_EXTENSION];
-	char context[AST_MAX_CONTEXT];
+/*!
+ * \internal
+ * \brief Actions that can be taken on a channel in a bridge
+ */
+enum bridge_channel_action_type {
+	/*! Bridged channel is to detect a feature hook */
+	BRIDGE_CHANNEL_ACTION_FEATURE,
+	/*! Bridged channel is to act on an interval hook */
+	BRIDGE_CHANNEL_ACTION_INTERVAL,
+	/*! Bridged channel is to send a DTMF stream out */
+	BRIDGE_CHANNEL_ACTION_DTMF_STREAM,
+	/*! Bridged channel is to indicate talking start */
+	BRIDGE_CHANNEL_ACTION_TALKING_START,
+	/*! Bridged channel is to indicate talking stop */
+	BRIDGE_CHANNEL_ACTION_TALKING_STOP,
+	/*! Bridge channel is to play the indicated sound file. */
+	BRIDGE_CHANNEL_ACTION_PLAY_FILE,
+	/*! Bridge channel is to run the indicated application. */
+	BRIDGE_CHANNEL_ACTION_RUN_APP,
+	/*! Bridge channel is to run the custom callback routine. */
+	BRIDGE_CHANNEL_ACTION_CALLBACK,
+	/*! Bridge channel is to get parked. */
+	BRIDGE_CHANNEL_ACTION_PARK,
+	/*! Bridge channel is to execute a blind transfer. */
+	BRIDGE_CHANNEL_ACTION_BLIND_TRANSFER,
+	/*! Bridge channel is to execute an attended transfer */
+	BRIDGE_CHANNEL_ACTION_ATTENDED_TRANSFER,
+
+	/*
+	 * Bridge actions put after this comment must never be put onto
+	 * the bridge_channel wr_queue because they have other resources
+	 * that must be freed.
+	 */
+
+	/*! Bridge reconfiguration deferred technology destruction. */
+	BRIDGE_CHANNEL_ACTION_DEFERRED_TECH_DESTROY = 1000,
+	/*! Bridge deferred dissolving. */
+	BRIDGE_CHANNEL_ACTION_DEFERRED_DISSOLVING,
 };
 
 /*!
- * \brief Adjust the bridge_channel's bridge merge inhibit request count.
+ * \internal
+ * \brief Push the bridge channel into its specified bridge.
  * \since 12.0.0
  *
- * \param bridge_channel What to operate on.
- * \param request Inhibit request increment.
- *     (Positive to add requests.  Negative to remove requests.)
+ * \param bridge_channel Channel to push.
  *
- * \note This API call is meant for internal bridging operations.
+ * \note On entry, bridge_channel->bridge is already locked.
  *
- * \retval bridge adjusted merge inhibit with reference count.
+ * \retval 0 on success.
+ * \retval -1 on failure.  The channel did not get pushed.
  */
-struct ast_bridge *bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
+int bridge_channel_push(struct ast_bridge_channel *bridge_channel);
 
 /*!
  * \internal
@@ -67,90 +102,57 @@ void bridge_channel_pull(struct ast_bridge_channel *bridge_channel);
 
 /*!
  * \internal
- * \brief Push the bridge channel into its specified bridge.
- * \since 12.0.0
- *
- * \param bridge_channel Channel to push.
+ * \brief Join the bridge_channel to the bridge
  *
- * \note On entry, bridge_channel->bridge is already locked.
+ * \param bridge_channel The Channel in the bridge
  *
- * \retval 0 on success.
- * \retval -1 on failure.  The channel did not get pushed.
+ * \note This API call starts the bridge_channel's processing of events while
+ * it is in the bridge. It will return when the channel has been instructed to
+ * leave the bridge.
  */
-int bridge_channel_push(struct ast_bridge_channel *bridge_channel);
-
 void bridge_channel_join(struct ast_bridge_channel *bridge_channel);
 
-void bridge_channel_suspend_nolock(struct ast_bridge_channel *bridge_channel);
-
-void bridge_channel_unsuspend_nolock(struct ast_bridge_channel *bridge_channel);
-
 /*!
  * \internal
- * \brief Update the linkedids for all channels in a bridge
- * \since 12.0.0
- *
- * \param bridge_channel The channel joining the bridge
- * \param swap The channel being swapped out of the bridge. May be NULL.
+ * \brief Temporarily suspend a channel from a bridge, handing control over to some
+ * other system
  *
- * \note The bridge must be locked prior to calling this function. This should be called
- * during a \ref bridge_channel_push operation, typically by a sub-class of a bridge
+ * \param bridge_channel The channel in the bridge
+ * \note This function assumes that \ref bridge_channel is already locked
  */
-void bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
+void bridge_channel_suspend_nolock(struct ast_bridge_channel *bridge_channel);
 
 /*!
  * \internal
- * \brief Update the accountcodes for a channel entering a bridge
- * \since 12.0.0
- *
- * This function updates the accountcode and peeraccount on channels in two-party
- * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
- * however accountcode propagation will still occur if the channel joining has an
- * accountcode.
+ * \brief Unsuspend a channel that was previously suspended
  *
- * \param bridge_channel The channel joining the bridge
- * \param swap The channel being swapped out of the bridge. May be NULL.
- *
- * \note The bridge must be locked prior to calling this function. This should be called
- * during a \ref bridge_channel_push operation, typically by a sub-class of a bridge
+ * \param bridge_channel The channel in the bridge
+ * \note This function assumes that \ref bridge_channel is already locked
  */
-void bridge_channel_update_accountcodes(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
-
+void bridge_channel_unsuspend_nolock(struct ast_bridge_channel *bridge_channel);
 
 /*!
- * \brief Set bridge channel state to leave bridge (if not leaving already) with no lock.
+ * \internal
+ * \brief Queue a blind transfer action on a transferee bridge channel
  *
- * \param bridge_channel Channel to change the state on
- * \param new_state The new state to place the channel into
+ * This is only relevant for when a blind transfer is performed on a two-party
+ * bridge. The transferee's bridge channel will have a blind transfer bridge
+ * action queued onto it, resulting in the party being redirected to a new
+ * destination
  *
- * \note This API call is only meant to be used within the
- * bridging module and hook callbacks to request the channel
- * exit the bridge.
+ * \param transferee The channel to have the action queued on
+ * \param exten The destination extension for the transferee
+ * \param context The destination context for the transferee
+ * \param hook Frame hook to attach to transferee
  *
- * \note This function assumes the bridge_channel is locked.
+ * \retval 0 on success.
+ * \retval -1 on error.
  */
-void ast_bridge_change_state_nolock(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
+int bridge_channel_queue_blind_transfer(struct ast_channel *transferee,
+		const char *exten, const char *context,
+		transfer_channel_cb new_channel_cb, void *user_data);
 
-/*!
- * \brief Set bridge channel state to leave bridge (if not leaving already).
- *
- * \param bridge_channel Channel to change the state on
- * \param new_state The new state to place the channel into
- *
- * Example usage:
- *
- * \code
- * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);
- * \endcode
- *
- * This places the channel pointed to by bridge_channel into the
- * state AST_BRIDGE_CHANNEL_STATE_HANGUP if it was
- * AST_BRIDGE_CHANNEL_STATE_WAIT before.
- *
- * \note This API call is only meant to be used within the
- * bridging module and hook callbacks to request the channel
- * exit the bridge.
- */
-void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
+int bridge_channel_queue_attended_transfer(struct ast_channel *transferee,
+		struct ast_channel *unbridged_chan);
 
 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */
diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h
index 736441f6a..7ab46327d 100644
--- a/include/asterisk/bridging_features.h
+++ b/include/asterisk/bridging_features.h
@@ -75,7 +75,7 @@ enum ast_bridge_builtin_feature {
 	 * how it was imparted.
 	 *
 	 * \note Joined channels exit the bridge with
-	 * AST_BRIDGE_CHANNEL_STATE_END.
+	 * AST_BRIDGE_CHANNEL_STATE_END_WITH_DISSOLVE.
 	 */
 	AST_BRIDGE_BUILTIN_HANGUP,
 	/*!