kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-19 03:08:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Bridge API comment tweaks.

Browse Source 
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@379703 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Richard Mudgett
2013-01-21 17:55:48 +00:00
parent ff32e094e5
commit 25c9940fc1
4 changed files with 77 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
bridges/bridge_builtin_features.c
View File

@@ -241,7 +241,11 @@ static int feature_attended_transfer(struct ast_bridge *bridge, struct ast_bridg
/*! \brief Internal built in feature for hangup */ /*! \brief Internal built in feature for hangup */
static int feature_hangup(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt) 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); ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
return 0; return 0;
} }

43
include/asterisk/bridging.h
View File

@@ -251,7 +251,8 @@ struct ast_bridge {
AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels; 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 capabilities The capabilities that we require to be used on the bridge
* \param flags Flags that will alter the behavior of 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); __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 * \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); int ast_bridge_check(uint32_t capabilities);
/*! \brief Destroy a bridge /*!
* \brief Destroy a bridge
* *
* \param bridge Bridge to destroy * \param bridge Bridge to destroy
* *
@@ -332,7 +335,8 @@ int ast_bridge_check(uint32_t capabilities);
*/ */
int ast_bridge_destroy(struct ast_bridge *bridge); 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 bridge Bridge to join
* \param chan Channel 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_features *features,
struct ast_bridge_tech_optimizations *tech_args); 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 bridge Bridge to impart on
* \param chan Channel to impart * \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); 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 bridge Bridge to depart from
* \param chan Channel to depart * \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); 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 bridge Bridge that the channel is to be removed from
* \param chan Channel to remove * \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); 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 bridge0 First bridge
* \param bridge1 Second 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); 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 bridge Bridge to suspend the channel from
* \param chan Channel to suspend * \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); 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 bridge Bridge to unsuspend the channel from
* \param chan Channel to unsuspend * \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); 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 bridge_channel Channel to change the state on
* \param new_state The new state to place the channel into * \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); 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 bridge Channel to change the sample rate on.
* \param sample_rate the sample rate to change to. If a * \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); 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 bridge Channel to change the sample rate on.
* \param mixing_interval the sample rate to change to. If 0 is set * \param mixing_interval the sample rate to change to. If 0 is set

47
include/asterisk/bridging_features.h
View File

@@ -36,13 +36,21 @@ enum ast_bridge_feature_flags {
AST_BRIDGE_FLAG_SMART = (1 << 1), AST_BRIDGE_FLAG_SMART = (1 << 1),
}; };
/*! \brief Built in features */ /*! \brief Built in DTMF features */
enum ast_bridge_builtin_feature { enum ast_bridge_builtin_feature {
/*! DTMF Based Blind Transfer */ /*! DTMF based Blind Transfer */
AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, AST_BRIDGE_BUILTIN_BLINDTRANSFER,
/*! DTMF Based Attended Transfer */ /*! DTMF based Attended Transfer */
AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, 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, AST_BRIDGE_BUILTIN_HANGUP,
/*! End terminator for list of built in features. Must remain last. */ /*! End terminator for list of built in features. Must remain last. */
@@ -124,7 +132,7 @@ struct ast_bridge_features {
void *talker_pvt_data; void *talker_pvt_data;
/*! Feature flags that are enabled */ /*! Feature flags that are enabled */
struct ast_flags feature_flags; 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; unsigned int usable:1;
/*! Bit to indicate whether the channel/bridge is muted or not */ /*! Bit to indicate whether the channel/bridge is muted or not */
unsigned int mute:1; unsigned int mute:1;
@@ -155,7 +163,8 @@ struct ast_bridge_features_attended_transfer {
char context[AST_MAX_CONTEXT]; 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 feature The feature that the handler will be responsible for
* \param callback The callback function that will handle it * \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); 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 * \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); 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 features Bridge features structure
* \param dtmf DTMF string to be activated upon * \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, void *hook_pvt,
ast_bridge_features_hook_pvt_destructor destructor); 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 features Bridge features structure
* \param talker_cb Callback function to execute when talking events occur in the bridge core. * \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, ast_bridge_talking_indicate_destructor talker_destructor,
void *pvt_data); 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 features Bridge features structure
* \param feature Feature to enable * \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); 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 features Bridge features structure
* \param flag Flag to enable * \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); 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 * \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); 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 * \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); 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 bridge Bridge to play stream into
* \param dtmf DTMF to play * \param dtmf DTMF to play

18
include/asterisk/bridging_technology.h
View File

@@ -81,7 +81,8 @@ struct ast_bridge_technology {
AST_RWLIST_ENTRY(ast_bridge_technology) entry; 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 technology The bridge technology to register
* \param mod The module that is registering the bridge technology * \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() */ /*! \brief See \ref __ast_bridge_technology_register() */
#define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self) #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 * \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); 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 The bridge that the notification should influence
* \param bridge_channel Bridge channel the notification was received on (if known) * \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); 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 * \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 * 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); 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 * \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); 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 * \param technology The bridge technology to unsuspend
* *