Thu Apr 28 2011 17:13:29

Asterisk developer's documentation


bridging.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2007 - 2009, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Channel Bridging API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  * \ref AstBridging
00023  */
00024 
00025 /*!
00026  * \page AstBridging Channel Bridging API
00027  *
00028  * The purpose of this API is to provide an easy and flexible way to bridge
00029  * channels of different technologies with different features.
00030  *
00031  * Bridging technologies provide the mechanism that do the actual handling
00032  * of frames between channels. They provide capability information, codec information,
00033  * and preference value to assist the bridging core in choosing a bridging technology when
00034  * creating a bridge. Different bridges may use different bridging technologies based on needs
00035  * but once chosen they all operate under the same premise; they receive frames and send frames.
00036  *
00037  * Bridges are a combination of bridging technology, channels, and features. A
00038  * developer creates a new bridge based on what they are currently expecting to do
00039  * with it or what they will do with it in the future. The bridging core determines what
00040  * available bridging technology will best fit the requirements and creates a new bridge.
00041  * Once created, channels can be added to the bridge in a blocking or non-blocking fashion.
00042  *
00043  * Features are such things as channel muting or DTMF based features such as attended transfer,
00044  * blind transfer, and hangup. Feature information must be set at the most granular level, on
00045  * the channel. While you can use features on a global scope the presence of a feature structure
00046  * on the channel will override the global scope. An example would be having the bridge muted
00047  * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted
00048  * it would be able to speak.
00049  *
00050  * Feature hooks allow a developer to tell the bridging core that when a DTMF string
00051  * is received from a channel a callback should be called in their application. For
00052  * example, a conference bridge application may want to provide an IVR to control various
00053  * settings on the conference bridge. This can be accomplished by attaching a feature hook
00054  * that calls an IVR function when a DTMF string is entered.
00055  *
00056  */
00057 
00058 #ifndef _ASTERISK_BRIDGING_H
00059 #define _ASTERISK_BRIDGING_H
00060 
00061 #if defined(__cplusplus) || defined(c_plusplus)
00062 extern "C" {
00063 #endif
00064 
00065 #include "asterisk/bridging_features.h"
00066 
00067 /*! \brief Capabilities for a bridge technology */
00068 enum ast_bridge_capability {
00069    /*! Bridge is only capable of mixing 2 channels */
00070    AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1),
00071    /*! Bridge is capable of mixing 2 or more channels */
00072    AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2),
00073    /*! Bridge should natively bridge two channels if possible */
00074    AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3),
00075    /*! Bridge should run using the multithreaded model */
00076    AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),
00077    /*! Bridge should run a central bridge thread */
00078    AST_BRIDGE_CAPABILITY_THREAD = (1 << 5),
00079    /*! Bridge technology can do video mixing (or something along those lines) */
00080    AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
00081    /*! Bridge technology can optimize things based on who is talking */
00082    AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7),
00083 };
00084 
00085 /*! \brief State information about a bridged channel */
00086 enum ast_bridge_channel_state {
00087    /*! Waiting for a signal */
00088    AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
00089    /*! Bridged channel has ended itself (it has hung up) */
00090    AST_BRIDGE_CHANNEL_STATE_END,
00091    /*! Bridged channel should be hung up */
00092    AST_BRIDGE_CHANNEL_STATE_HANGUP,
00093    /*! Bridged channel should be removed from the bridge without being hung up */
00094    AST_BRIDGE_CHANNEL_STATE_DEPART,
00095    /*! Bridged channel is executing a feature hook */
00096    AST_BRIDGE_CHANNEL_STATE_FEATURE,
00097    /*! Bridged channel is sending a DTMF stream out */
00098    AST_BRIDGE_CHANNEL_STATE_DTMF,
00099 };
00100 
00101 /*! \brief Return values for bridge technology write function */
00102 enum ast_bridge_write_result {
00103    /*! Bridge technology wrote out frame fine */
00104    AST_BRIDGE_WRITE_SUCCESS = 0,
00105    /*! Bridge technology attempted to write out the frame but failed */
00106    AST_BRIDGE_WRITE_FAILED,
00107    /*! Bridge technology does not support writing out a frame of this type */
00108    AST_BRIDGE_WRITE_UNSUPPORTED,
00109 };
00110 
00111 struct ast_bridge_technology;
00112 struct ast_bridge;
00113 
00114 /*!
00115  * \brief Structure that contains information regarding a channel in a bridge
00116  */
00117 struct ast_bridge_channel {
00118    /*! Lock to protect this data structure */
00119    ast_mutex_t lock;
00120    /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
00121    ast_cond_t cond;
00122    /*! Current bridged channel state */
00123    enum ast_bridge_channel_state state;
00124    /*! Asterisk channel participating in the bridge */
00125    struct ast_channel *chan;
00126    /*! Asterisk channel we are swapping with (if swapping) */
00127    struct ast_channel *swap;
00128    /*! Bridge this channel is participating in */
00129    struct ast_bridge *bridge;
00130    /*! Private information unique to the bridge technology */
00131    void *bridge_pvt;
00132    /*! Thread handling the bridged channel */
00133    pthread_t thread;
00134    /*! Additional file descriptors to look at */
00135    int fds[4];
00136    /*! Bit to indicate whether the channel is suspended from the bridge or not */
00137    unsigned int suspended:1;
00138    /*! Features structure for features that are specific to this channel */
00139    struct ast_bridge_features *features;
00140    /*! Queue of DTMF digits used for DTMF streaming */
00141    char dtmf_stream_q[8];
00142    /*! Linked list information */
00143    AST_LIST_ENTRY(ast_bridge_channel) entry;
00144 };
00145 
00146 /*!
00147  * \brief Structure that contains information about a bridge
00148  */
00149 struct ast_bridge {
00150    /*! Number of channels participating in the bridge */
00151    int num;
00152    /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */
00153    unsigned int waiting:1;
00154    /*! Bit to indicate the bridge thread should stop */
00155    unsigned int stop:1;
00156    /*! Bit to indicate the bridge thread should refresh itself */
00157    unsigned int refresh:1;
00158    /*! Bridge flags to tweak behavior */
00159    struct ast_flags feature_flags;
00160    /*! Bridge technology that is handling the bridge */
00161    struct ast_bridge_technology *technology;
00162    /*! Private information unique to the bridge technology */
00163    void *bridge_pvt;
00164    /*! Thread running the bridge */
00165    pthread_t thread;
00166    /*! Enabled features information */
00167    struct ast_bridge_features features;
00168    /*! Array of channels that the bridge thread is currently handling */
00169    struct ast_channel **array;
00170    /*! Number of channels in the above array */
00171    size_t array_num;
00172    /*! Number of channels the array can handle */
00173    size_t array_size;
00174    /*! Linked list of channels participating in the bridge */
00175    AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
00176 };
00177 
00178 /*! \brief Create a new bridge
00179  *
00180  * \param capabilities The capabilities that we require to be used on the bridge
00181  * \param flags Flags that will alter the behavior of the bridge
00182  *
00183  * \retval a pointer to a new bridge on success
00184  * \retval NULL on failure
00185  *
00186  * Example usage:
00187  *
00188  * \code
00189  * struct ast_bridge *bridge;
00190  * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE);
00191  * \endcode
00192  *
00193  * This creates a simple two party bridge that will be destroyed once one of
00194  * the channels hangs up.
00195  */
00196 struct ast_bridge *ast_bridge_new(int capabilities, int flags);
00197 
00198 /*! \brief See if it is possible to create a bridge
00199  *
00200  * \param capabilities The capabilities that the bridge will use
00201  *
00202  * \retval 1 if possible
00203  * \retval 0 if not possible
00204  *
00205  * Example usage:
00206  *
00207  * \code
00208  * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX);
00209  * \endcode
00210  *
00211  * This sees if it is possible to create a bridge capable of bridging two channels
00212  * together.
00213  */
00214 int ast_bridge_check(int capabilities);
00215 
00216 /*! \brief Destroy a bridge
00217  *
00218  * \param bridge Bridge to destroy
00219  *
00220  * \retval 0 on success
00221  * \retval -1 on failure
00222  *
00223  * Example usage:
00224  *
00225  * \code
00226  * ast_bridge_destroy(bridge);
00227  * \endcode
00228  *
00229  * This destroys a bridge that was previously created using ast_bridge_new.
00230  */
00231 int ast_bridge_destroy(struct ast_bridge *bridge);
00232 
00233 /*! \brief Join (blocking) a channel to a bridge
00234  *
00235  * \param bridge Bridge to join
00236  * \param chan Channel to join
00237  * \param swap Channel to swap out if swapping
00238  * \param features Bridge features structure
00239  *
00240  * \retval state that channel exited the bridge with
00241  *
00242  * Example usage:
00243  *
00244  * \code
00245  * ast_bridge_join(bridge, chan, NULL, NULL);
00246  * \endcode
00247  *
00248  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
00249  * the bridge pointer. This function will not return until the channel has been
00250  * removed from the bridge, swapped out for another channel, or has hung up.
00251  *
00252  * If this channel will be replacing another channel the other channel can be specified
00253  * in the swap parameter. The other channel will be thrown out of the bridge in an
00254  * atomic fashion.
00255  *
00256  * If channel specific features are enabled a pointer to the features structure
00257  * can be specified in the features parameter.
00258  */
00259 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);
00260 
00261 /*! \brief Impart (non-blocking) a channel on a bridge
00262  *
00263  * \param bridge Bridge to impart on
00264  * \param chan Channel to impart
00265  * \param swap Channel to swap out if swapping
00266  * \param features Bridge features structure
00267  *
00268  * \retval 0 on success
00269  * \retval -1 on failure
00270  *
00271  * Example usage:
00272  *
00273  * \code
00274  * ast_bridge_impart(bridge, chan, NULL, NULL);
00275  * \endcode
00276  *
00277  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
00278  * the bridge pointer. This function will return immediately and will not wait
00279  * until the channel is no longer part of the bridge.
00280  *
00281  * If this channel will be replacing another channel the other channel can be specified
00282  * in the swap parameter. The other channel will be thrown out of the bridge in an
00283  * atomic fashion.
00284  *
00285  * If channel specific features are enabled a pointer to the features structure
00286  * can be specified in the features parameter.
00287  */
00288 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features);
00289 
00290 /*! \brief Depart a channel from a bridge
00291  *
00292  * \param bridge Bridge to depart from
00293  * \param chan Channel to depart
00294  *
00295  * \retval 0 on success
00296  * \retval -1 on failure
00297  *
00298  * Example usage:
00299  *
00300  * \code
00301  * ast_bridge_depart(bridge, chan);
00302  * \endcode
00303  *
00304  * This removes the channel pointed to by the chan pointer from the bridge
00305  * pointed to by the bridge pointer and gives control to the calling thread.
00306  * This does not hang up the channel.
00307  *
00308  * \note This API call can only be used on channels that were added to the bridge
00309  *       using the ast_bridge_impart API call.
00310  */
00311 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
00312 
00313 /*! \brief Remove a channel from a bridge
00314  *
00315  * \param bridge Bridge that the channel is to be removed from
00316  * \param chan Channel to remove
00317  *
00318  * \retval 0 on success
00319  * \retval -1 on failure
00320  *
00321  * Example usage:
00322  *
00323  * \code
00324  * ast_bridge_remove(bridge, chan);
00325  * \endcode
00326  *
00327  * This removes the channel pointed to by the chan pointer from the bridge
00328  * pointed to by the bridge pointer and requests that it be hung up. Control
00329  * over the channel will NOT be given to the calling thread.
00330  *
00331  * \note This API call can be used on channels that were added to the bridge
00332  *       using both ast_bridge_join and ast_bridge_impart.
00333  */
00334 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
00335 
00336 /*! \brief Merge two bridges together
00337  *
00338  * \param bridge0 First bridge
00339  * \param bridge1 Second bridge
00340  *
00341  * \retval 0 on success
00342  * \retval -1 on failure
00343  *
00344  * Example usage:
00345  *
00346  * \code
00347  * ast_bridge_merge(bridge0, bridge1);
00348  * \endcode
00349  *
00350  * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0.
00351  * In reality all of the channels in bridge1 are simply moved to bridge0.
00352  *
00353  * \note The second bridge specified is not destroyed when this operation is
00354  *       completed.
00355  */
00356 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
00357 
00358 /*! \brief Suspend a channel temporarily from a bridge
00359  *
00360  * \param bridge Bridge to suspend the channel from
00361  * \param chan Channel to suspend
00362  *
00363  * \retval 0 on success
00364  * \retval -1 on failure
00365  *
00366  * Example usage:
00367  *
00368  * \code
00369  * ast_bridge_suspend(bridge, chan);
00370  * \endcode
00371  *
00372  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
00373  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
00374  * the channel will not be removed from the bridge.
00375  *
00376  * \note This API call can be used on channels that were added to the bridge
00377  *       using both ast_bridge_join and ast_bridge_impart.
00378  */
00379 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
00380 
00381 /*! \brief Unsuspend a channel from a bridge
00382  *
00383  * \param bridge Bridge to unsuspend the channel from
00384  * \param chan Channel to unsuspend
00385  *
00386  * \retval 0 on success
00387  * \retval -1 on failure
00388  *
00389  * Example usage:
00390  *
00391  * \code
00392  * ast_bridge_unsuspend(bridge, chan);
00393  * \endcode
00394  *
00395  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
00396  * The bridge will go back to handling the channel once this function returns.
00397  *
00398  * \note You must not mess with the channel once this function returns.
00399  *       Doing so may result in bad things happening.
00400  */
00401 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
00402 
00403 /*! \brief Change the state of a bridged channel
00404  *
00405  * \param bridge_channel Channel to change the state on
00406  * \param new_state The new state to place the channel into
00407  *
00408  * Example usage:
00409  *
00410  * \code
00411  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT);
00412  * \endcode
00413  *
00414  * This places the channel pointed to by bridge_channel into the state
00415  * AST_BRIDGE_CHANNEL_STATE_WAIT.
00416  *
00417  * \note This API call is only meant to be used in feature hook callbacks to
00418  *       make sure the channel either hangs up or returns to the bridge.
00419  */
00420 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
00421 
00422 #if defined(__cplusplus) || defined(c_plusplus)
00423 }
00424 #endif
00425 
00426 #endif /* _ASTERISK_BRIDGING_H */