[svn-commits] file: branch file/bridging r126150 - /team/file/bridging/include/asterisk/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Fri Jun 27 20:40:07 CDT 2008
Author: file
Date: Fri Jun 27 20:40:07 2008
New Revision: 126150
URL: http://svn.digium.com/view/asterisk?view=rev&rev=126150
Log:
Expand bridging API documentation. Each API call now includes example usage, general description of what it does, sometimes how it works, and notes.
Modified:
team/file/bridging/include/asterisk/bridging.h
Modified: team/file/bridging/include/asterisk/bridging.h
URL: http://svn.digium.com/view/asterisk/team/file/bridging/include/asterisk/bridging.h?view=diff&rev=126150&r1=126149&r2=126150
==============================================================================
--- team/file/bridging/include/asterisk/bridging.h (original)
+++ team/file/bridging/include/asterisk/bridging.h Fri Jun 27 20:40:07 2008
@@ -18,6 +18,41 @@
/*! \file
* \brief Channel Bridging API
+ * \author Joshua Colp <jcolp at 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
@@ -29,281 +64,623 @@
/*! \brief Capabilities for a bridge technology */
enum ast_bridge_capability {
- AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1), /*! Bridge is only capable of mixing 2 sources */
- AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2), /*! Bridge is capable of mixing 2+ sources */
- AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3), /*! Bridge can natively bridge two channels */
- AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4), /*! Run in a multithreaded model */
- AST_BRIDGE_CAPABILITY_THREAD = (1 << 5), /*! Run central bridge thread */
- AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6), /*! Bridge can do video mixing (or something along those lines) */
- AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7), /*! Bridge can optimize things based on who is talking */
+ /*! 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 Preference for choosing the bridge technology */
enum ast_bridge_preference {
- AST_BRIDGE_PREFERENCE_HIGH = 0, /*! Strongly prefer this bridge technology when compared to others */
- AST_BRIDGE_PREFERENCE_MEDIUM, /*! Meh, middle - this isn't great but this isn't the best */
- AST_BRIDGE_PREFERENCE_LOW, /*! Only use this bridge technology as a last resort */
+ /*! 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 State information about a bridged channel */
enum ast_bridge_channel_state {
- AST_BRIDGE_CHANNEL_STATE_WAIT = 0, /*! Waiting for a signal */
- AST_BRIDGE_CHANNEL_STATE_END, /*! Bridged channel ended itself */
- AST_BRIDGE_CHANNEL_STATE_HANGUP, /*! Bridge requested that this channel be hungup, unless otherwise instructed */
- AST_BRIDGE_CHANNEL_STATE_DEPART, /*! Depart from the bridge */
- AST_BRIDGE_CHANNEL_STATE_FEATURE, /*! Channel is currently executing a feature */
- AST_BRIDGE_CHANNEL_STATE_DTMF, /*! A DTMF stream is playing/to be played on this channel */
+ /*! 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 Flags used for bridge features */
enum ast_bridge_feature_flags {
- AST_BRIDGE_FLAG_DISSOLVE = (1 << 0), /*! Upon hangup of any channel dissolve the bridge */
- AST_BRIDGE_FLAG_SMART = (1 << 1), /*! Move between bridge technologies as needed */
+ /*! 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 Return values for bridge technology write function */
enum ast_bridge_write_result {
- AST_BRIDGE_WRITE_SUCCESS = 0, /*! Frame was written out fine */
- AST_BRIDGE_WRITE_FAILED, /*! Tried to write out the frame but failed */
- AST_BRIDGE_WRITE_UNSUPPORTED, /*! Bridge technology can't write out this frame type */
+ /*! 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,
};
/*! \brief Built in features */
enum ast_bridge_builtin_feature {
- AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0, /*! Blind transfer */
- AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, /*! Attended transfer */
- AST_BRIDGE_BUILTIN_HANGUP, /*! Hangup on DTMF stream */
- AST_BRIDGE_BUILTIN_END, /*! End terminator for list of built in features */
+ /*! 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;
struct ast_bridge_features;
+/*!
+ * \brief Structure that is the essence of a bridge technology
+ */
struct ast_bridge_technology {
- const char *name; /*! Unique name to this bridge technology */
- int capabilities; /*! What this bridge technology is capable of */
- enum ast_bridge_preference preference; /*! Preference level of this bridge technology */
- int (*create)(struct ast_bridge *bridge); /*! Callback for when a bridge is created */
- int (*destroy)(struct ast_bridge *bridge); /*! Callback for when a bridge is destroyed */
- int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); /*! Callback for when a channel joins a bridge */
- int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); /*! Callback for when a channel leaves a bridge */
- enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame); /*! Callback for writing a frame to the bridge */
- int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd); /*! Callback for when a file descriptor trips */
- int (*thread)(struct ast_bridge *bridge); /*! Callback for replacement thread function */
- int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel); /*! Callback for poking a bridge technology */
- int formats; /*! Formats this bridge technology can support */
- unsigned int suspended:1; /*! Is this bridge technology suspended from use or not? */
- struct ast_module *mod; /*! Module this bridge technology belongs to */
- AST_RWLIST_ENTRY(ast_bridge_technology) entry; /*! Linked list information */
-};
-
-
+ /*! 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 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 Features hook callback type
+ *
+ * \param bridge
+ * \param bridge_channel
+ * \param hook_pvt
+ *
+ * \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 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[8];
+ /*! 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 {
- AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks; /*! Attached hooks */
- struct ast_flags feature_flags; /*! Feature flags */
- unsigned int usable:1; /*! Whether this should be considered usable or not */
- unsigned int mute:1; /*! Whether to mute audio or not */
-};
-
+ /*! 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 information regarding a channel in a bridge
+ */
struct ast_bridge_channel {
- enum ast_bridge_channel_state state; /*! Current bridged channel state */
- struct ast_channel *chan; /*! Asterisk channel participating in this bridge */
- struct ast_channel *swap; /*! Asterisk channel we are swapping with */
- struct ast_bridge *bridge; /*! Bridge this channel is in */
- ast_mutex_t lock; /*! Lock, to protect this bridge channel structure */
- ast_cond_t cond; /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
- void *bridge_pvt; /*! Private information unique to the bridge technology (not always needed) */
- pthread_t thread; /*! Thread handling the bridged channel */
- int fds[4]; /*! Additional file descriptors to look at */
- unsigned int suspended:1; /*! Is this bridged channel suspended from the bridge or not? */
- struct ast_bridge_features *features; /*! Enabled features information */
- char dtmf_stream_q[8]; /*! DTMF stream queue */
- AST_LIST_ENTRY(ast_bridge_channel) entry;/*! Linked list information */
-};
-
+ /*! 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 {
- int num; /*! Number of channels involved in the bridge */
- unsigned int rebuild:1; /*! Something outside wants us to rebuild the bridge data */
- struct ast_flags feature_flags; /*! Feature flags */
- struct ast_bridge_technology *technology; /*! Technology in use on the bridge */
- void *bridge_pvt; /*! Private information unique to the bridge technology (not always needed) */
- pthread_t thread; /*! Thread running the bridge */
- struct ast_bridge_features features; /*! Enabled features information */
- AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels; /*! Channels participating in this bridge */
+ /*! Number of channels participating in the bridge */
+ int num;
+ /*! Bit to indicate that the bridge thread should examine the bridge */
+ unsigned int rebuild: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;
+ /*! Linked list of channels participating in the bridge */
+ AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
};
/*! \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
+ *
+ * \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.
*/
#define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
/*! \brief Unregister a bridge technology from use
+ *
* \param technology The bridge technology to unregister
- * \retval 0 on success
- * \retval -1 on failure
+ *
+ * \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 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 Destroy a bridge
+ *
* \param bridge Bridge to destroy
- * \retval 0 on success
- * \retval -1 on failure
+ *
+ * \retval 0 on success
+ * \retval -1 on failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_bridge_destroy(bridge);
+ * \endcode
+ *
+ * This destroys a bridge that was previously created used ast_bridge_new.
*/
int ast_bridge_destroy(struct ast_bridge *bridge);
-/*! \brief Join a channel to a 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 a channel on a bridge
+/*! \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
+ *
+ * \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
+ *
+ * \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
+ *
+ * \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 Change the state of a bridge channel
- * \param bridge_channel Bridge channel
- * \param new_state State to change to
- * \retval 0 on success
- * \retval -1 on failure
- */
-int ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
-
-/*! \brief Request that the bridge rebuild itself
- * \param bridge Bridge in question
- * \retval 0 on success
- * \retval -1 on failure
- */
-int ast_bridge_rebuild(struct ast_bridge *bridge);
-
/*! \brief Merge two bridges together
+ *
* \param bridge0 First bridge
* \param bridge1 Second bridge
- * \retval 0 on success
- * \retval -1 on failure
+ *
+ * \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. Control will be given to the current thread.
+/*! \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
+ *
+ * \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.
+/*! \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
+ *
+ * \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 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);
/*! \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
+ *
+ * \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
- * \retval 0 on success
- * \retval -1 on failure
+ *
+ * \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);
/*! \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
+ *
+ * \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
+ *
+ * \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
+ *
+ * \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
+ *
+ * \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);
More information about the svn-commits
mailing list