diff options
author | Richard Mudgett <rmudgett@digium.com> | 2013-07-24 21:13:00 +0000 |
---|---|---|
committer | Richard Mudgett <rmudgett@digium.com> | 2013-07-24 21:13:00 +0000 |
commit | 07d2694f725557854142fb6ae8fafa0e708b389e (patch) | |
tree | d4acf240ded6041d72ea4aedf10a062901c51b3d /include/asterisk | |
parent | 50d69a9d12c7001f37d011b2860734619b45b2a9 (diff) |
Refactor ast_bridge_features struct.
* Reduced the number of hook containers to just dtmf_hooks,
interval_hooks, and other_hooks. As a result, several functions dealing
with the different hook containers could be combined.
* Extended the generic hook struct for DTMF and interval hooks instead of
using a variant record.
* Merged the special talk detector hook into the other_hooks container.
* Replaced ast_bridge_features_set_talk_detector() with
ast_bridge_talk_detector_hook().
(issue ASTERISK-22107)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@395322 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk')
-rw-r--r-- | include/asterisk/bridging_features.h | 133 |
1 files changed, 79 insertions, 54 deletions
diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h index 7ab46327d..acdd6e0ba 100644 --- a/include/asterisk/bridging_features.h +++ b/include/asterisk/bridging_features.h @@ -149,13 +149,43 @@ typedef void (*ast_bridge_hook_pvt_destructor)(void *hook_pvt); * \param bridge_channel Channel executing the feature * \param talking TRUE if the channel is now talking * - * \retval 0 success - * \retval -1 failure + * \retval 0 Keep the callback hook. + * \retval -1 Remove the callback hook. */ -typedef void (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *pvt_data, int talking); +typedef int (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *pvt_data, int talking); +enum ast_bridge_hook_remove_flags { + /*! The hook is removed when the channel is pulled from the bridge. */ + AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0), + /*! The hook is removed when the bridge's personality changes. */ + AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE = (1 << 1), +}; -typedef void (*ast_bridge_talking_indicate_destructor)(void *pvt_data); +enum ast_bridge_hook_type { + /*! The hook type has not been specified. */ + AST_BRIDGE_HOOK_TYPE_NONE, + AST_BRIDGE_HOOK_TYPE_DTMF, + AST_BRIDGE_HOOK_TYPE_TIMER, + AST_BRIDGE_HOOK_TYPE_HANGUP, + AST_BRIDGE_HOOK_TYPE_JOIN, + AST_BRIDGE_HOOK_TYPE_LEAVE, + AST_BRIDGE_HOOK_TYPE_TALK, +}; + +/* BUGBUG Need to be able to selectively remove DTMF, hangup, and interval hooks. */ +/*! \brief Structure that is the essence of a feature hook. */ +struct ast_bridge_hook { + /*! Callback that is called when hook is tripped */ + ast_bridge_hook_callback callback; + /*! Callback to destroy hook_pvt data right before destruction. */ + ast_bridge_hook_pvt_destructor destructor; + /*! Unique data that was passed into us */ + void *hook_pvt; + /*! Flags determining when hooks should be removed from a bridge channel */ + struct ast_flags remove_flags; + /*! What kind of hook this is. */ + enum ast_bridge_hook_type type; +}; /*! * \brief Maximum length of a DTMF feature string @@ -163,13 +193,21 @@ typedef void (*ast_bridge_talking_indicate_destructor)(void *pvt_data); #define MAXIMUM_DTMF_FEATURE_STRING (11 + 1) /*! Extra parameters for a DTMF feature hook. */ -struct ast_bridge_hook_dtmf { +struct ast_bridge_hook_dtmf_parms { /*! DTMF String that is examined during a feature hook lookup */ char code[MAXIMUM_DTMF_FEATURE_STRING]; }; +/*! DTMF specific hook. */ +struct ast_bridge_hook_dtmf { + /*! Generic feature hook information. */ + struct ast_bridge_hook generic; + /*! Extra parameters for a DTMF feature hook. */ + struct ast_bridge_hook_dtmf_parms dtmf; +}; + /*! Extra parameters for an interval timer hook. */ -struct ast_bridge_hook_timer { +struct ast_bridge_hook_timer_parms { /*! Time at which the hook should actually trip */ struct timeval trip_time; /*! Heap index for interval hook */ @@ -180,33 +218,12 @@ struct ast_bridge_hook_timer { unsigned int seqno; }; -enum ast_bridge_hook_remove_flags { - /*! The hook is removed when the channel is pulled from the bridge. */ - AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0), - /*! The hook is removed when the bridge's personality changes. */ - AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE = (1 << 1), -}; - -/* BUGBUG Need to be able to selectively remove DTMF, hangup, and interval hooks. */ -/*! \brief Structure that is the essence of a feature hook. */ -struct ast_bridge_hook { - /*! Linked list information */ - AST_LIST_ENTRY(ast_bridge_hook) entry; - /*! Callback that is called when hook is tripped */ - ast_bridge_hook_callback callback; - /*! Callback to destroy hook_pvt data right before destruction. */ - ast_bridge_hook_pvt_destructor destructor; - /*! Unique data that was passed into us */ - void *hook_pvt; - /*! Flags determining when hooks should be removed from a bridge channel */ - struct ast_flags remove_flags; - /*! Extra hook parameters. */ - union { - /*! Extra parameters for a DTMF feature hook. */ - struct ast_bridge_hook_dtmf dtmf; - /*! Extra parameters for an interval timer hook. */ - struct ast_bridge_hook_timer timer; - } parms; +/*! Timer specific hook. */ +struct ast_bridge_hook_timer { + /*! Generic feature hook information. */ + struct ast_bridge_hook generic; + /*! Extra parameters for an interval timer hook. */ + struct ast_bridge_hook_timer_parms timer; }; #define BRIDGE_FEATURES_INTERVAL_RATE 10 @@ -217,24 +234,14 @@ struct ast_bridge_hook { struct ast_bridge_features { /*! Attached DTMF feature hooks */ struct ao2_container *dtmf_hooks; - /*! Attached hangup interception hooks container */ - struct ao2_container *hangup_hooks; - /*! Attached bridge channel join interception hooks container */ - struct ao2_container *join_hooks; - /*! Attached bridge channel leave interception hooks container */ - struct ao2_container *leave_hooks; + /*! Attached miscellaneous other hooks. */ + struct ao2_container *other_hooks; /*! Attached interval hooks */ struct ast_heap *interval_hooks; /*! Used to determine when interval based features should be checked */ struct ast_timer *interval_timer; /*! Limits feature data */ struct ast_bridge_features_limits *limits; - /*! Callback to indicate when a bridge channel has started and stopped talking */ - ast_bridge_talking_indicate_callback talker_cb; - /*! Callback to destroy any pvt data stored for the talker. */ - ast_bridge_talking_indicate_destructor talker_destructor_cb; - /*! Talker callback pvt data */ - void *talker_pvt_data; /*! Feature flags that are enabled */ struct ast_flags feature_flags; /*! Used to assign the sequence number to the next interval hook added. */ @@ -575,19 +582,37 @@ int ast_bridge_interval_hook(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags remove_flags); /*! - * \brief Set a callback on the features structure to receive talking notifications on. + * \brief Attach a bridge channel talk detection hook to a bridge features structure * * \param features Bridge features structure - * \param talker_cb Callback function to execute when talking events occur in the bridge core. - * \param pvt_data Optional unique data that will be passed with the talking events. - * \param talker_destructor Optional destructor callback for pvt data. + * \param callback Function to execute upon activation + * \param hook_pvt Unique data + * \param destructor Optional destructor callback for hook_pvt data + * \param remove_flags Dictates what situations the hook should be removed. * - * \return Nothing + * \retval 0 on success + * \retval -1 on failure (The caller must cleanup any hook_pvt resources.) + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * ast_bridge_talk_hook(&features, talk_callback, NULL, NULL, 0); + * \endcode + * + * This makes the bridging technology call talk_callback when a + * channel is recognized as starting and stopping talking. A + * pointer to useful data may be provided to the hook_pvt + * parameter. + * + * \note This hook is currently only supported by softmix. */ -void ast_bridge_features_set_talk_detector(struct ast_bridge_features *features, - ast_bridge_talking_indicate_callback talker_cb, - ast_bridge_talking_indicate_destructor talker_destructor, - void *pvt_data); +int ast_bridge_talk_detector_hook(struct ast_bridge_features *features, + ast_bridge_talking_indicate_callback callback, + void *hook_pvt, + ast_bridge_hook_pvt_destructor destructor, + enum ast_bridge_hook_remove_flags remove_flags); /*! * \brief Enable a built in feature on a bridge features structure |