diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/asterisk/bridging.h | 426 | ||||
| -rw-r--r-- | include/asterisk/bridging_features.h | 298 | ||||
| -rw-r--r-- | include/asterisk/bridging_technology.h | 180 | ||||
| -rw-r--r-- | include/asterisk/channel.h | 8 |
4 files changed, 911 insertions, 1 deletions
diff --git a/include/asterisk/bridging.h b/include/asterisk/bridging.h new file mode 100644 index 000000000..33fe041ca --- /dev/null +++ b/include/asterisk/bridging.h @@ -0,0 +1,426 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2007 - 2009, Digium, Inc. + * + * Joshua Colp <jcolp@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Channel Bridging API + * \author Joshua Colp <jcolp@digium.com> + * \ref AstBridging + */ + +/*! + * \page AstBridging Channel Bridging API + * + * The purpose of this API is to provide an easy and flexible way to bridge + * channels of different technologies with different features. + * + * Bridging technologies provide the mechanism that do the actual handling + * of frames between channels. They provide capability information, codec information, + * and preference value to assist the bridging core in choosing a bridging technology when + * creating a bridge. Different bridges may use different bridging technologies based on needs + * but once chosen they all operate under the same premise; they receive frames and send frames. + * + * Bridges are a combination of bridging technology, channels, and features. A + * developer creates a new bridge based on what they are currently expecting to do + * with it or what they will do with it in the future. The bridging core determines what + * available bridging technology will best fit the requirements and creates a new bridge. + * Once created, channels can be added to the bridge in a blocking or non-blocking fashion. + * + * Features are such things as channel muting or DTMF based features such as attended transfer, + * blind transfer, and hangup. Feature information must be set at the most granular level, on + * the channel. While you can use features on a global scope the presence of a feature structure + * on the channel will override the global scope. An example would be having the bridge muted + * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted + * it would be able to speak. + * + * Feature hooks allow a developer to tell the bridging core that when a DTMF string + * is received from a channel a callback should be called in their application. For + * example, a conference bridge application may want to provide an IVR to control various + * settings on the conference bridge. This can be accomplished by attaching a feature hook + * that calls an IVR function when a DTMF string is entered. + * + */ + +#ifndef _ASTERISK_BRIDGING_H +#define _ASTERISK_BRIDGING_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +#include "asterisk/bridging_features.h" + +/*! \brief Capabilities for a bridge technology */ +enum ast_bridge_capability { + /*! Bridge is only capable of mixing 2 channels */ + AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1), + /*! Bridge is capable of mixing 2 or more channels */ + AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2), + /*! Bridge should natively bridge two channels if possible */ + AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3), + /*! Bridge should run using the multithreaded model */ + AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4), + /*! Bridge should run a central bridge thread */ + AST_BRIDGE_CAPABILITY_THREAD = (1 << 5), + /*! Bridge technology can do video mixing (or something along those lines) */ + AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6), + /*! Bridge technology can optimize things based on who is talking */ + AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7), +}; + +/*! \brief State information about a bridged channel */ +enum ast_bridge_channel_state { + /*! Waiting for a signal */ + AST_BRIDGE_CHANNEL_STATE_WAIT = 0, + /*! Bridged channel has ended itself (it has hung up) */ + AST_BRIDGE_CHANNEL_STATE_END, + /*! Bridged channel should be hung up */ + AST_BRIDGE_CHANNEL_STATE_HANGUP, + /*! Bridged channel should be removed from the bridge without being hung up */ + AST_BRIDGE_CHANNEL_STATE_DEPART, + /*! Bridged channel is executing a feature hook */ + AST_BRIDGE_CHANNEL_STATE_FEATURE, + /*! Bridged channel is sending a DTMF stream out */ + AST_BRIDGE_CHANNEL_STATE_DTMF, +}; + +/*! \brief Return values for bridge technology write function */ +enum ast_bridge_write_result { + /*! Bridge technology wrote out frame fine */ + AST_BRIDGE_WRITE_SUCCESS = 0, + /*! Bridge technology attempted to write out the frame but failed */ + AST_BRIDGE_WRITE_FAILED, + /*! Bridge technology does not support writing out a frame of this type */ + AST_BRIDGE_WRITE_UNSUPPORTED, +}; + +struct ast_bridge_technology; +struct ast_bridge; + +/*! + * \brief Structure that contains information regarding a channel in a bridge + */ +struct ast_bridge_channel { + /*! Lock to protect this data structure */ + ast_mutex_t lock; + /*! Condition, used if we want to wake up a thread waiting on the bridged channel */ + ast_cond_t cond; + /*! Current bridged channel state */ + enum ast_bridge_channel_state state; + /*! Asterisk channel participating in the bridge */ + struct ast_channel *chan; + /*! Asterisk channel we are swapping with (if swapping) */ + struct ast_channel *swap; + /*! Bridge this channel is participating in */ + struct ast_bridge *bridge; + /*! Private information unique to the bridge technology */ + void *bridge_pvt; + /*! Thread handling the bridged channel */ + pthread_t thread; + /*! Additional file descriptors to look at */ + int fds[4]; + /*! Bit to indicate whether the channel is suspended from the bridge or not */ + unsigned int suspended:1; + /*! Features structure for features that are specific to this channel */ + struct ast_bridge_features *features; + /*! Queue of DTMF digits used for DTMF streaming */ + char dtmf_stream_q[8]; + /*! Linked list information */ + AST_LIST_ENTRY(ast_bridge_channel) entry; +}; + +/*! + * \brief Structure that contains information about a bridge + */ +struct ast_bridge { + /*! Number of channels participating in the bridge */ + int num; + /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */ + unsigned int waiting:1; + /*! Bit to indicate the bridge thread should stop */ + unsigned int stop:1; + /*! Bit to indicate the bridge thread should refresh itself */ + unsigned int refresh:1; + /*! Bridge flags to tweak behavior */ + struct ast_flags feature_flags; + /*! Bridge technology that is handling the bridge */ + struct ast_bridge_technology *technology; + /*! Private information unique to the bridge technology */ + void *bridge_pvt; + /*! Thread running the bridge */ + pthread_t thread; + /*! Enabled features information */ + struct ast_bridge_features features; + /*! Array of channels that the bridge thread is currently handling */ + struct ast_channel **array; + /*! Number of channels in the above array */ + size_t array_num; + /*! Number of channels the array can handle */ + size_t array_size; + /*! Linked list of channels participating in the bridge */ + AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels; +}; + +/*! \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 + * + * \retval a pointer to a new bridge on success + * \retval NULL on failure + * + * Example usage: + * + * \code + * struct ast_bridge *bridge; + * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE); + * \endcode + * + * This creates a simple two party bridge that will be destroyed once one of + * the channels hangs up. + */ +struct ast_bridge *ast_bridge_new(int capabilities, int flags); + +/*! \brief See if it is possible to create a bridge + * + * \param capabilities The capabilities that the bridge will use + * + * \retval 1 if possible + * \retval 0 if not possible + * + * Example usage: + * + * \code + * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX); + * \endcode + * + * This sees if it is possible to create a bridge capable of bridging two channels + * together. + */ +int ast_bridge_check(int capabilities); + +/*! \brief Destroy a bridge + * + * \param bridge Bridge to destroy + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_destroy(bridge); + * \endcode + * + * This destroys a bridge that was previously created using ast_bridge_new. + */ +int ast_bridge_destroy(struct ast_bridge *bridge); + +/*! \brief Join (blocking) a channel to a bridge + * + * \param bridge Bridge to join + * \param chan Channel to join + * \param swap Channel to swap out if swapping + * \param features Bridge features structure + * + * \retval state that channel exited the bridge with + * + * Example usage: + * + * \code + * ast_bridge_join(bridge, chan, NULL, NULL); + * \endcode + * + * This adds a channel pointed to by the chan pointer to the bridge pointed to by + * the bridge pointer. This function will not return until the channel has been + * removed from the bridge, swapped out for another channel, or has hung up. + * + * If this channel will be replacing another channel the other channel can be specified + * in the swap parameter. The other channel will be thrown out of the bridge in an + * atomic fashion. + * + * If channel specific features are enabled a pointer to the features structure + * can be specified in the features parameter. + */ +enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features); + +/*! \brief Impart (non-blocking) a channel on a bridge + * + * \param bridge Bridge to impart on + * \param chan Channel to impart + * \param swap Channel to swap out if swapping + * \param features Bridge features structure + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_impart(bridge, chan, NULL, NULL); + * \endcode + * + * This adds a channel pointed to by the chan pointer to the bridge pointed to by + * the bridge pointer. This function will return immediately and will not wait + * until the channel is no longer part of the bridge. + * + * If this channel will be replacing another channel the other channel can be specified + * in the swap parameter. The other channel will be thrown out of the bridge in an + * atomic fashion. + * + * If channel specific features are enabled a pointer to the features structure + * can be specified in the features parameter. + */ +int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features); + +/*! \brief Depart a channel from a bridge + * + * \param bridge Bridge to depart from + * \param chan Channel to depart + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_depart(bridge, chan); + * \endcode + * + * This removes the channel pointed to by the chan pointer from the bridge + * pointed to by the bridge pointer and gives control to the calling thread. + * This does not hang up the channel. + * + * \note This API call can only be used on channels that were added to the bridge + * using the ast_bridge_impart API call. + */ +int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan); + +/*! \brief Remove a channel from a bridge + * + * \param bridge Bridge that the channel is to be removed from + * \param chan Channel to remove + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_remove(bridge, chan); + * \endcode + * + * This removes the channel pointed to by the chan pointer from the bridge + * pointed to by the bridge pointer and requests that it be hung up. Control + * over the channel will NOT be given to the calling thread. + * + * \note This API call can be used on channels that were added to the bridge + * using both ast_bridge_join and ast_bridge_impart. + */ +int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan); + +/*! \brief Merge two bridges together + * + * \param bridge0 First bridge + * \param bridge1 Second bridge + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_merge(bridge0, bridge1); + * \endcode + * + * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0. + * In reality all of the channels in bridge1 are simply moved to bridge0. + * + * \note The second bridge specified is not destroyed when this operation is + * completed. + */ +int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1); + +/*! \brief Suspend a channel temporarily from a bridge + * + * \param bridge Bridge to suspend the channel from + * \param chan Channel to suspend + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_suspend(bridge, chan); + * \endcode + * + * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily. + * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as + * the channel will not be removed from the bridge. + * + * \note This API call can be used on channels that were added to the bridge + * using both ast_bridge_join and ast_bridge_impart. + */ +int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan); + +/*! \brief Unsuspend a channel from a bridge + * + * \param bridge Bridge to unsuspend the channel from + * \param chan Channel to unsuspend + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_unsuspend(bridge, chan); + * \endcode + * + * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge. + * The bridge will go back to handling the channel once this function returns. + * + * \note You must not mess with the channel once this function returns. + * Doing so may result in bad things happening. + */ +int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan); + +/*! \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 + * + * Example usage: + * + * \code + * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT); + * \endcode + * + * This places the channel pointed to by bridge_channel into the state + * AST_BRIDGE_CHANNEL_STATE_WAIT. + * + * \note This API call is only meant to be used in feature hook callbacks to + * make sure the channel either hangs up or returns to the bridge. + */ +void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_BRIDGING_H */ diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h new file mode 100644 index 000000000..ee36a561c --- /dev/null +++ b/include/asterisk/bridging_features.h @@ -0,0 +1,298 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2009, Digium, Inc. + * + * Joshua Colp <jcolp@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Channel Bridging API + * \author Joshua Colp <jcolp@digium.com> + */ + +#ifndef _ASTERISK_BRIDGING_FEATURES_H +#define _ASTERISK_BRIDGING_FEATURES_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +/*! \brief Flags used for bridge features */ +enum ast_bridge_feature_flags { + /*! Upon hangup the bridge should be discontinued */ + AST_BRIDGE_FLAG_DISSOLVE = (1 << 0), + /*! Move between bridging technologies as needed. */ + AST_BRIDGE_FLAG_SMART = (1 << 1), +}; + +/*! \brief Built in features */ +enum ast_bridge_builtin_feature { + /*! DTMF Based Blind Transfer */ + AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, + /*! DTMF Based Attended Transfer */ + AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, + /*! DTMF Based Hangup Feature */ + AST_BRIDGE_BUILTIN_HANGUP, + /*! End terminator for list of built in features. Must remain last. */ + AST_BRIDGE_BUILTIN_END, +}; + +struct ast_bridge; +struct ast_bridge_channel; + +/*! + * \brief Features hook callback type + * + * \param bridge The bridge that the channel is part of + * \param bridge_channel Channel executing the feature + * \param hook_pvt Private data passed in when the hook was created + * + * \retval 0 success + * \retval -1 failure + */ +typedef int (*ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt); + +/*! + * \brief Maximum length of a DTMF feature string + */ +#define MAXIMUM_DTMF_FEATURE_STRING 8 + +/*! + * \brief Structure that is the essence of a features hook + */ +struct ast_bridge_features_hook { + /*! DTMF String that is examined during a feature hook lookup */ + char dtmf[MAXIMUM_DTMF_FEATURE_STRING]; + /*! Callback that is called when DTMF string is matched */ + ast_bridge_features_hook_callback callback; + /*! Unique data that was passed into us */ + void *hook_pvt; + /*! Linked list information */ + AST_LIST_ENTRY(ast_bridge_features_hook) entry; +}; + +/*! + * \brief Structure that contains features information + */ +struct ast_bridge_features { + /*! Attached DTMF based feature hooks */ + AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks; + /*! Feature flags that are enabled */ + struct ast_flags feature_flags; + /*! Bit to indicate that this structure is useful and should be considered when looking for features */ + unsigned int usable:1; + /*! Bit to indicate whether the channel/bridge is muted or not */ + unsigned int mute:1; +}; + +/*! + * \brief Structure that contains configuration information for the blind transfer built in feature + */ +struct ast_bridge_features_blind_transfer { + /*! Context to use for transfers */ + char context[AST_MAX_CONTEXT]; +}; + +/*! + * \brief Structure that contains configuration information for the attended transfer built in feature + */ +struct ast_bridge_features_attended_transfer { + /*! DTMF string used to abort the transfer */ + char abort[MAXIMUM_DTMF_FEATURE_STRING]; + /*! DTMF string used to turn the transfer into a three way conference */ + char threeway[MAXIMUM_DTMF_FEATURE_STRING]; + /*! DTMF string used to complete the transfer */ + char complete[MAXIMUM_DTMF_FEATURE_STRING]; + /*! Context to use for transfers */ + char context[AST_MAX_CONTEXT]; +}; + +/*! \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 + * \param dtmf Default DTMF string used to activate the feature + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1"); + * \endcode + * + * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in + * attended transfer feature. + */ +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 + * + * \param feature The feature to unregister + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER); + * \endcode + * + * This unregisters the function that is handling the built in attended transfer feature. + */ +int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature); + +/*! \brief Attach a custom hook to a bridge features structure + * + * \param features Bridge features structure + * \param dtmf DTMF string to be activated upon + * \param callback Function to execute upon activation + * \param hook_pvt Unique data + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * ast_bridge_features_hook(&features, "#", pound_callback, NULL); + * \endcode + * + * This makes the bridging core call pound_callback if a channel that has this + * feature structure inputs the DTMF string '#'. A pointer to useful data may be + * provided to the hook_pvt parameter. + * + * \note It is important that the callback set the bridge channel state back to + * AST_BRIDGE_CHANNEL_STATE_WAIT or the bridge thread will not service the channel. + */ +int ast_bridge_features_hook(struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt); + +/*! \brief Enable a built in feature on a bridge features structure + * + * \param features Bridge features structure + * \param feature Feature to enable + * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default + * \param config Configuration structure unique to the built in type + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL); + * \endcode + * + * This enables the attended transfer DTMF option using the default DTMF string. An alternate + * string may be provided using the dtmf parameter. Internally this is simply setting up a hook + * to a built in feature callback function. + */ +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 + * + * \param features Bridge features structure + * \param flag Flag to enable + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE); + * \endcode + * + * This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure + * 'features'. + */ +int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag); + +/*! \brief Initialize bridge features structure + * + * \param features Bridge featues structure + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * \endcode + * + * This initializes the feature structure 'features' to have nothing enabled. + * + * \note This MUST be called before enabling features or flags. Failure to do so + * may result in a crash. + */ +int ast_bridge_features_init(struct ast_bridge_features *features); + +/*! \brief Clean up the contents of a bridge features structure + * + * \param features Bridge features structure + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * struct ast_bridge_features features; + * ast_bridge_features_init(&features); + * ast_bridge_features_cleanup(&features); + * \endcode + * + * This cleans up the feature structure 'features'. + * + * \note This MUST be called after the features structure is done being used + * or a memory leak may occur. + */ +int ast_bridge_features_cleanup(struct ast_bridge_features *features); + +/*! \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 + * \param chan Channel to optionally not play to + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_dtmf_stream(bridge, "0123456789", NULL); + * \endcode + * + * This sends the DTMF digits '0123456789' to all channels in the bridge pointed to + * by the bridge pointer. Optionally a channel may be excluded by passing it's channel pointer + * using the chan parameter. + */ +int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_BRIDGING_FEATURES_H */ diff --git a/include/asterisk/bridging_technology.h b/include/asterisk/bridging_technology.h new file mode 100644 index 000000000..58b27a4b4 --- /dev/null +++ b/include/asterisk/bridging_technology.h @@ -0,0 +1,180 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2009, Digium, Inc. + * + * Joshua Colp <jcolp@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Channel Bridging API + * \author Joshua Colp <jcolp@digium.com> + */ + +#ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H +#define _ASTERISK_BRIDGING_TECHNOLOGY_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +/*! \brief Preference for choosing the bridge technology */ +enum ast_bridge_preference { + /*! Bridge technology should have high precedence over other bridge technologies */ + AST_BRIDGE_PREFERENCE_HIGH = 0, + /*! Bridge technology is decent, not the best but should still be considered over low */ + AST_BRIDGE_PREFERENCE_MEDIUM, + /*! Bridge technology is low, it should not be considered unless it is absolutely needed */ + AST_BRIDGE_PREFERENCE_LOW, +}; + +/*! + * \brief Structure that is the essence of a bridge technology + */ +struct ast_bridge_technology { + /*! Unique name to this bridge technology */ + const char *name; + /*! The capabilities that this bridge technology is capable of */ + int capabilities; + /*! Preference level that should be used when determining whether to use this bridge technology or not */ + enum ast_bridge_preference preference; + /*! Callback for when a bridge is being created */ + int (*create)(struct ast_bridge *bridge); + /*! Callback for when a bridge is being destroyed */ + int (*destroy)(struct ast_bridge *bridge); + /*! Callback for when a channel is being added to a bridge */ + int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); + /*! Callback for when a channel is leaving a bridge */ + int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); + /*! Callback for when a channel is suspended from the bridge */ + void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); + /*! Callback for when a channel is unsuspended from the bridge */ + void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); + /*! Callback to see if a channel is compatible with the bridging technology */ + int (*compatible)(struct ast_bridge_channel *bridge_channel); + /*! Callback for writing a frame into the bridging technology */ + enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame); + /*! Callback for when a file descriptor trips */ + int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd); + /*! Callback for replacement thread function */ + int (*thread)(struct ast_bridge *bridge); + /*! Callback for poking a bridge thread */ + int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); + /*! Formats that the bridge technology supports */ + int formats; + /*! Bit to indicate whether the bridge technology is currently suspended or not */ + unsigned int suspended:1; + /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */ + struct ast_module *mod; + /*! Linked list information */ + AST_RWLIST_ENTRY(ast_bridge_technology) entry; +}; + +/*! \brief Register a bridge technology for use + * + * \param technology The bridge technology to register + * \param module The module that is registering the bridge technology + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_technology_register(&simple_bridge_tech); + * \endcode + * + * This registers a bridge technology declared as the structure + * simple_bridge_tech with the bridging core and makes it available for + * use when creating bridges. + */ +int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod); + +/*! \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 + * + * \param technology The bridge technology to unregister + * + * \retval 0 on success + * \retval -1 on failure + * + * Example usage: + * + * \code + * ast_bridge_technology_unregister(&simple_bridge_tech); + * \endcode + * + * This unregisters a bridge technlogy declared as the structure + * simple_bridge_tech with the bridging core. It will no longer be + * considered when creating a new bridge. + */ +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 + * + * \param bridge The bridge that the notification should influence + * \param bridge_channel Bridge channel the notification was received on (if known) + * \param chan Channel the notification was received on (if known) + * \param outfd File descriptor that the notification was received on (if known) + * + * Example usage: + * + * \code + * ast_bridge_handle_trip(bridge, NULL, chan, -1); + * \endcode + * + * This tells the bridging core that a frame has been received on + * the channel pointed to by chan and that it should be read and handled. + * + * \note This should only be used by bridging technologies. + */ +void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd); + +/*! \brief Suspend a bridge technology from consideration + * + * \param technology The bridge technology to suspend + * + * Example usage: + * + * \code + * ast_bridge_technology_suspend(&simple_bridge_tech); + * \endcode + * + * This suspends the bridge technology simple_bridge_tech from being considered + * when creating a new bridge. Existing bridges using the bridge technology + * are not affected. + */ +void ast_bridge_technology_suspend(struct ast_bridge_technology *technology); + +/*! \brief Unsuspend a bridge technology + * + * \param technology The bridge technology to unsuspend + * + * Example usage: + * + * \code + * ast_bridge_technology_unsuspend(&simple_bridge_tech); + * \endcode + * + * This makes the bridge technology simple_bridge_tech considered when + * creating a new bridge again. + */ +void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */ diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 39b302fc8..2d0643a0f 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -496,7 +496,13 @@ struct ast_channel { unsigned short transfercapability; /*!< ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */ - char unused_old_dtmfq[AST_MAX_EXTENSION]; /*!< (deprecated, use readq instead) Any/all queued DTMF characters */ + union { + char unused_old_dtmfq[AST_MAX_EXTENSION]; /*!< (deprecated, use readq instead) Any/all queued DTMF characters */ + struct { + struct ast_bridge *bridge; /*!< Bridge this channel is participating in */ + }; + }; + char context[AST_MAX_CONTEXT]; /*!< Dialplan: Current extension context */ char exten[AST_MAX_EXTENSION]; /*!< Dialplan: Current extension number */ char macrocontext[AST_MAX_CONTEXT]; /*!< Macro: Current non-macro context. See app_macro.c */ |