[asterisk-commits] file: branch file/bridging r126150 - /team/file/bridging/include/asterisk/

SVN commits to the Asterisk project asterisk-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 asterisk-commits mailing list