kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-10-31 02:37:10 +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 */
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;
}

43
include/asterisk/bridging.h
View File

@@ -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

47
include/asterisk/bridging_features.h
View File

@@ -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

18
include/asterisk/bridging_technology.h
View File

@@ -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
*