From 25c9940fc175df50636ec0af0feab992b943edf4 Mon Sep 17 00:00:00 2001 From: Richard Mudgett Date: Mon, 21 Jan 2013 17:55:48 +0000 Subject: [PATCH] Bridge API comment tweaks. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@379703 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- bridges/bridge_builtin_features.c | 6 +++- include/asterisk/bridging.h | 43 +++++++++++++++-------- include/asterisk/bridging_features.h | 47 ++++++++++++++++++-------- include/asterisk/bridging_technology.h | 18 ++++++---- 4 files changed, 77 insertions(+), 37 deletions(-) diff --git a/bridges/bridge_builtin_features.c b/bridges/bridge_builtin_features.c index 21af928550..13bf4bb8b6 100644 --- a/bridges/bridge_builtin_features.c +++ b/bridges/bridge_builtin_features.c @@ -241,7 +241,11 @@ static int feature_attended_transfer(struct ast_bridge *bridge, struct ast_bridg /*! \brief Internal built in feature for hangup */ static int feature_hangup(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt) { - /* This is very simple, we basically change the state on the bridge channel to end and the core takes care of the rest */ + /* + * This is very simple, we simply change the state on the + * bridge_channel to force the channel out of the bridge and the + * core takes care of the rest. + */ ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END); return 0; } diff --git a/include/asterisk/bridging.h b/include/asterisk/bridging.h index 2c41f4618a..2d0d74b829 100644 --- a/include/asterisk/bridging.h +++ b/include/asterisk/bridging.h @@ -251,7 +251,8 @@ struct ast_bridge { AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels; }; -/*! \brief Create a new bridge +/*! + * \brief Create a new bridge * * \param capabilities The capabilities that we require to be used on the bridge * \param flags Flags that will alter the behavior of the bridge @@ -297,7 +298,8 @@ static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *fil __ao2_unlock(bridge, file, function, line, var); } -/*! \brief See if it is possible to create a bridge +/*! + * \brief See if it is possible to create a bridge * * \param capabilities The capabilities that the bridge will use * @@ -315,7 +317,8 @@ static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *fil */ int ast_bridge_check(uint32_t capabilities); -/*! \brief Destroy a bridge +/*! + * \brief Destroy a bridge * * \param bridge Bridge to destroy * @@ -332,7 +335,8 @@ int ast_bridge_check(uint32_t capabilities); */ int ast_bridge_destroy(struct ast_bridge *bridge); -/*! \brief Join (blocking) a channel to a bridge +/*! + * \brief Join (blocking) a channel to a bridge * * \param bridge Bridge to join * \param chan Channel to join @@ -365,7 +369,8 @@ enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, struct ast_bridge_features *features, struct ast_bridge_tech_optimizations *tech_args); -/*! \brief Impart (non-blocking) a channel on a bridge +/*! + * \brief Impart (non-blocking) a channel onto a bridge * * \param bridge Bridge to impart on * \param chan Channel to impart @@ -395,7 +400,8 @@ enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, */ int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features, int allow_hangup); -/*! \brief Depart a channel from a bridge +/*! + * \brief Depart a channel from a bridge * * \param bridge Bridge to depart from * \param chan Channel to depart @@ -418,7 +424,8 @@ int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struc */ int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan); -/*! \brief Remove a channel from a bridge +/*! + * \brief Remove a channel from a bridge * * \param bridge Bridge that the channel is to be removed from * \param chan Channel to remove @@ -441,7 +448,8 @@ int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan); */ int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan); -/*! \brief Merge two bridges together +/*! + * \brief Merge two bridges together * * \param bridge0 First bridge * \param bridge1 Second bridge @@ -463,7 +471,8 @@ int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan); */ int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1); -/*! \brief Suspend a channel temporarily from a bridge +/*! + * \brief Suspend a channel temporarily from a bridge * * \param bridge Bridge to suspend the channel from * \param chan Channel to suspend @@ -486,7 +495,8 @@ int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1); */ int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan); -/*! \brief Unsuspend a channel from a bridge +/*! + * \brief Unsuspend a channel from a bridge * * \param bridge Bridge to unsuspend the channel from * \param chan Channel to unsuspend @@ -508,7 +518,8 @@ int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan); */ int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan); -/*! \brief Change the state of a bridged channel +/*! + * \brief Change the state of a bridged channel * * \param bridge_channel Channel to change the state on * \param new_state The new state to place the channel into @@ -527,8 +538,9 @@ int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan); */ void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state); -/*! \brief Adjust the internal mixing sample rate of a bridge used during - * multimix mode. +/*! + * \brief Adjust the internal mixing sample rate of a bridge + * used during multimix mode. * * \param bridge Channel to change the sample rate on. * \param sample_rate the sample rate to change to. If a @@ -538,8 +550,9 @@ void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast */ void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate); -/*! \brief Adjust the internal mixing interval of a bridge used during - * multimix mode. +/*! + * \brief Adjust the internal mixing interval of a bridge used + * during multimix mode. * * \param bridge Channel to change the sample rate on. * \param mixing_interval the sample rate to change to. If 0 is set diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h index 2984684d47..a9e5875050 100644 --- a/include/asterisk/bridging_features.h +++ b/include/asterisk/bridging_features.h @@ -36,13 +36,21 @@ enum ast_bridge_feature_flags { AST_BRIDGE_FLAG_SMART = (1 << 1), }; -/*! \brief Built in features */ +/*! \brief Built in DTMF features */ enum ast_bridge_builtin_feature { - /*! DTMF Based Blind Transfer */ - AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, - /*! DTMF Based Attended Transfer */ + /*! DTMF based Blind Transfer */ + AST_BRIDGE_BUILTIN_BLINDTRANSFER, + /*! DTMF based Attended Transfer */ AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, - /*! DTMF Based Hangup Feature */ + /*! + * DTMF based depart bridge feature + * + * \note Imparted channels are optionally hangup depending upon + * how it was imparted. + * + * \note Joined channels exit the bridge with + * AST_BRIDGE_CHANNEL_STATE_END. + */ AST_BRIDGE_BUILTIN_HANGUP, /*! End terminator for list of built in features. Must remain last. */ @@ -124,7 +132,7 @@ struct ast_bridge_features { void *talker_pvt_data; /*! Feature flags that are enabled */ struct ast_flags feature_flags; - /*! Bit to indicate that the hook list is useful and should be considered when looking for DTMF features */ + /*! Bit to indicate that the feature_flags and hook list is setup */ unsigned int usable:1; /*! Bit to indicate whether the channel/bridge is muted or not */ unsigned int mute:1; @@ -155,7 +163,8 @@ struct ast_bridge_features_attended_transfer { char context[AST_MAX_CONTEXT]; }; -/*! \brief Register a handler for a built in feature +/*! + * \brief Register a handler for a built in feature * * \param feature The feature that the handler will be responsible for * \param callback The callback function that will handle it @@ -175,7 +184,8 @@ struct ast_bridge_features_attended_transfer { */ int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf); -/*! \brief Unregister a handler for a built in feature +/*! + * \brief Unregister a handler for a built in feature * * \param feature The feature to unregister * @@ -192,7 +202,8 @@ int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_br */ int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature); -/*! \brief Attach a custom hook to a bridge features structure +/*! + * \brief Attach a custom hook to a bridge features structure * * \param features Bridge features structure * \param dtmf DTMF string to be activated upon @@ -224,7 +235,8 @@ int ast_bridge_features_hook(struct ast_bridge_features *features, void *hook_pvt, ast_bridge_features_hook_pvt_destructor destructor); -/*! \brief Set a callback on the features structure to receive talking notifications on. +/*! + * \brief Set a callback on the features structure to receive talking notifications on. * * \param features Bridge features structure * \param talker_cb Callback function to execute when talking events occur in the bridge core. @@ -239,7 +251,8 @@ int ast_bridge_features_set_talk_detector(struct ast_bridge_features *features, ast_bridge_talking_indicate_destructor talker_destructor, void *pvt_data); -/*! \brief Enable a built in feature on a bridge features structure +/*! + * \brief Enable a built in feature on a bridge features structure * * \param features Bridge features structure * \param feature Feature to enable @@ -263,7 +276,8 @@ int ast_bridge_features_set_talk_detector(struct ast_bridge_features *features, */ int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config); -/*! \brief Set a flag on a bridge features structure +/*! + * \brief Set a flag on a bridge features structure * * \param features Bridge features structure * \param flag Flag to enable @@ -284,7 +298,8 @@ int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_br */ int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag); -/*! \brief Initialize bridge features structure +/*! + * \brief Initialize bridge features structure * * \param features Bridge featues structure * @@ -305,7 +320,8 @@ int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_ */ int ast_bridge_features_init(struct ast_bridge_features *features); -/*! \brief Clean up the contents of a bridge features structure +/*! + * \brief Clean up the contents of a bridge features structure * * \param features Bridge features structure * @@ -327,7 +343,8 @@ int ast_bridge_features_init(struct ast_bridge_features *features); */ int ast_bridge_features_cleanup(struct ast_bridge_features *features); -/*! \brief Play a DTMF stream into a bridge, optionally not to a given channel +/*! + * \brief Play a DTMF stream into a bridge, optionally not to a given channel * * \param bridge Bridge to play stream into * \param dtmf DTMF to play diff --git a/include/asterisk/bridging_technology.h b/include/asterisk/bridging_technology.h index ccc87fb635..d09c4bec45 100644 --- a/include/asterisk/bridging_technology.h +++ b/include/asterisk/bridging_technology.h @@ -81,7 +81,8 @@ struct ast_bridge_technology { AST_RWLIST_ENTRY(ast_bridge_technology) entry; }; -/*! \brief Register a bridge technology for use +/*! + * \brief Register a bridge technology for use * * \param technology The bridge technology to register * \param mod The module that is registering the bridge technology @@ -104,7 +105,8 @@ int __ast_bridge_technology_register(struct ast_bridge_technology *technology, s /*! \brief See \ref __ast_bridge_technology_register() */ #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self) -/*! \brief Unregister a bridge technology from use +/*! + * \brief Unregister a bridge technology from use * * \param technology The bridge technology to unregister * @@ -123,7 +125,8 @@ int __ast_bridge_technology_register(struct ast_bridge_technology *technology, s */ int ast_bridge_technology_unregister(struct ast_bridge_technology *technology); -/*! \brief Feed notification that a frame is waiting on a channel into the bridging core +/*! + * \brief Feed notification that a frame is waiting on a channel into the bridging core * * \param bridge The bridge that the notification should influence * \param bridge_channel Bridge channel the notification was received on (if known) @@ -143,7 +146,8 @@ int ast_bridge_technology_unregister(struct ast_bridge_technology *technology); */ void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd); -/*! \brief Lets the bridging indicate when a bridge channel has stopped or started talking. +/*! + * \brief Lets the bridging indicate when a bridge channel has stopped or started talking. * * \note All DSP functionality on the bridge has been pushed down to the lowest possible * layer, which in this case is the specific bridging technology being used. Since it @@ -158,7 +162,8 @@ void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel */ void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking); -/*! \brief Suspend a bridge technology from consideration +/*! + * \brief Suspend a bridge technology from consideration * * \param technology The bridge technology to suspend * @@ -174,7 +179,8 @@ void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_chan */ void ast_bridge_technology_suspend(struct ast_bridge_technology *technology); -/*! \brief Unsuspend a bridge technology +/*! + * \brief Unsuspend a bridge technology * * \param technology The bridge technology to unsuspend *