diff options
author | Matthew Jordan <mjordan@digium.com> | 2013-07-24 19:24:09 +0000 |
---|---|---|
committer | Matthew Jordan <mjordan@digium.com> | 2013-07-24 19:24:09 +0000 |
commit | 1d1650f5729501d1780870e5d3706ac843ca0570 (patch) | |
tree | f805a4daa815be8bc774e171813f358de8ece05b /include/asterisk | |
parent | 644b0e576a8276992962e1ecce2fd7308bac4a85 (diff) |
Update bridge_channel refactorings; export bridge_ symbol
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@395295 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk')
-rw-r--r-- | include/asterisk/bridging_channel.h | 183 | ||||
-rw-r--r-- | include/asterisk/bridging_channel_internal.h | 150 | ||||
-rw-r--r-- | include/asterisk/bridging_features.h | 2 |
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, /*! |