bridge.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2007 - 2009, 2013 Digium, Inc.
00005  *
00006  * Richard Mudgett <rmudgett@digium.com>
00007  * Joshua Colp <jcolp@digium.com>
00008  *
00009  * See http://www.asterisk.org for more information about
00010  * the Asterisk project. Please do not directly contact
00011  * any of the maintainers of this project for assistance;
00012  * the project provides a web site, mailing lists and IRC
00013  * channels for your use.
00014  *
00015  * This program is free software, distributed under the terms of
00016  * the GNU General Public License Version 2. See the LICENSE file
00017  * at the top of the source tree.
00018  */
00019 
00020 /*!
00021  * \file
00022  * \brief Bridging API
00023  *
00024  * \author Richard Mudgett <rmudgett@digium.com>
00025  * \author Joshua Colp <jcolp@digium.com>
00026  * \ref AstBridging
00027  *
00028  * See Also:
00029  * \arg \ref AstCREDITS
00030  */
00031 
00032 /*!
00033  * \page AstBridging Bridging API
00034  *
00035  * The purpose of this API is to provide an easy and flexible way to bridge
00036  * channels of different technologies with different features.
00037  *
00038  * Bridging technologies provide the mechanism that do the actual handling
00039  * of frames between channels. They provide capability information, codec information,
00040  * and preference value to assist the bridging core in choosing a bridging technology when
00041  * creating a bridge. Different bridges may use different bridging technologies based on needs
00042  * but once chosen they all operate under the same premise; they receive frames and send frames.
00043  *
00044  * Bridges are a combination of bridging technology, channels, and features. A
00045  * developer creates a new bridge based on what they are currently expecting to do
00046  * with it or what they will do with it in the future. The bridging core determines what
00047  * available bridging technology will best fit the requirements and creates a new bridge.
00048  * Once created, channels can be added to the bridge in a blocking or non-blocking fashion.
00049  *
00050  * Features are such things as channel muting or DTMF based features such as attended transfer,
00051  * blind transfer, and hangup. Feature information must be set at the most granular level, on
00052  * the channel. While you can use features on a global scope the presence of a feature structure
00053  * on the channel will override the global scope. An example would be having the bridge muted
00054  * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted
00055  * it would be able to speak.
00056  *
00057  * Feature hooks allow a developer to tell the bridging core that when a DTMF string
00058  * is received from a channel a callback should be called in their application. For
00059  * example, a conference bridge application may want to provide an IVR to control various
00060  * settings on the conference bridge. This can be accomplished by attaching a feature hook
00061  * that calls an IVR function when a DTMF string is entered.
00062  *
00063  */
00064 
00065 #ifndef _ASTERISK_BRIDGING_H
00066 #define _ASTERISK_BRIDGING_H
00067 
00068 #if defined(__cplusplus) || defined(c_plusplus)
00069 extern "C" {
00070 #endif
00071 
00072 #include "asterisk/bridge_features.h"
00073 #include "asterisk/bridge_channel.h"
00074 #include "asterisk/bridge_roles.h"
00075 #include "asterisk/dsp.h"
00076 #include "asterisk/uuid.h"
00077 
00078 struct ast_bridge_technology;
00079 struct ast_bridge;
00080 struct ast_bridge_tech_optimizations;
00081 
00082 /*! \brief Capabilities for a bridge technology */
00083 enum ast_bridge_capability {
00084    /*! Bridge technology can service calls on hold. */
00085    AST_BRIDGE_CAPABILITY_HOLDING = (1 << 0),
00086    /*! Bridge waits for channel to answer.  Passes early media. (XXX Not supported yet) */
00087    AST_BRIDGE_CAPABILITY_EARLY = (1 << 1),
00088    /*! Bridge is capable of natively bridging two channels. (Smart bridge only) */
00089    AST_BRIDGE_CAPABILITY_NATIVE = (1 << 2),
00090    /*! Bridge is capable of mixing at most two channels. (Smart bridgeable) */
00091    AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 3),
00092    /*! Bridge is capable of mixing an arbitrary number of channels. (Smart bridgeable) */
00093    AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 4),
00094 };
00095 
00096 /*! \brief Video source modes */
00097 enum ast_bridge_video_mode_type {
00098    /*! Video is not allowed in the bridge */
00099    AST_BRIDGE_VIDEO_MODE_NONE = 0,
00100    /*! A single user is picked as the only distributed of video across the bridge */
00101    AST_BRIDGE_VIDEO_MODE_SINGLE_SRC,
00102    /*! A single user's video feed is distributed to all bridge channels, but
00103     *  that feed is automatically picked based on who is talking the most. */
00104    AST_BRIDGE_VIDEO_MODE_TALKER_SRC,
00105 };
00106 
00107 /*! \brief This is used for both SINGLE_SRC mode to set what channel
00108  *  should be the current single video feed */
00109 struct ast_bridge_video_single_src_data {
00110    /*! Only accept video coming from this channel */
00111    struct ast_channel *chan_vsrc;
00112 };
00113 
00114 /*! \brief This is used for both SINGLE_SRC_TALKER mode to set what channel
00115  *  should be the current single video feed */
00116 struct ast_bridge_video_talker_src_data {
00117    /*! Only accept video coming from this channel */
00118    struct ast_channel *chan_vsrc;
00119    int average_talking_energy;
00120 
00121    /*! Current talker see's this person */
00122    struct ast_channel *chan_old_vsrc;
00123 };
00124 
00125 /*! \brief Data structure that defines a video source mode */
00126 struct ast_bridge_video_mode {
00127    enum ast_bridge_video_mode_type mode;
00128    /* Add data for all the video modes here. */
00129    union {
00130       struct ast_bridge_video_single_src_data single_src_data;
00131       struct ast_bridge_video_talker_src_data talker_src_data;
00132    } mode_data;
00133 };
00134 
00135 /*!
00136  * \brief Destroy the bridge.
00137  *
00138  * \param self Bridge to operate upon.
00139  *
00140  * \return Nothing
00141  */
00142 typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
00143 
00144 /*!
00145  * \brief The bridge is being dissolved.
00146  *
00147  * \param self Bridge to operate upon.
00148  *
00149  * \details
00150  * The bridge is being dissolved.  Remove any external
00151  * references to the bridge so it can be destroyed.
00152  *
00153  * \note On entry, self must NOT be locked.
00154  *
00155  * \return Nothing
00156  */
00157 typedef void (*ast_bridge_dissolving_fn)(struct ast_bridge *self);
00158 
00159 /*!
00160  * \brief Push this channel into the bridge.
00161  *
00162  * \param self Bridge to operate upon.
00163  * \param bridge_channel Bridge channel to push.
00164  * \param swap Bridge channel to swap places with if not NULL.
00165  *
00166  * \details
00167  * Setup any channel hooks controlled by the bridge.  Allocate
00168  * bridge_channel->bridge_pvt and initialize any resources put
00169  * in bridge_channel->bridge_pvt if needed.  If there is a swap
00170  * channel, use it as a guide to setting up the bridge_channel.
00171  *
00172  * \note On entry, self is already locked.
00173  *
00174  * \retval 0 on success.
00175  * \retval -1 on failure.  The channel did not get pushed.
00176  */
00177 typedef int (*ast_bridge_push_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
00178 
00179 /*!
00180  * \brief Pull this channel from the bridge.
00181  *
00182  * \param self Bridge to operate upon.
00183  * \param bridge_channel Bridge channel to pull.
00184  *
00185  * \details
00186  * Remove any channel hooks controlled by the bridge.  Release
00187  * any resources held by bridge_channel->bridge_pvt and release
00188  * bridge_channel->bridge_pvt.
00189  *
00190  * \note On entry, self is already locked.
00191  *
00192  * \return Nothing
00193  */
00194 typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
00195 
00196 /*!
00197  * \brief Notify the bridge that this channel was just masqueraded.
00198  *
00199  * \param self Bridge to operate upon.
00200  * \param bridge_channel Bridge channel that was masqueraded.
00201  *
00202  * \details
00203  * A masquerade just happened to this channel.  The bridge needs
00204  * to re-evaluate this a channel in the bridge.
00205  *
00206  * \note On entry, self is already locked.
00207  *
00208  * \return Nothing
00209  */
00210 typedef void (*ast_bridge_notify_masquerade_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
00211 
00212 /*!
00213  * \brief Get the merge priority of this bridge.
00214  *
00215  * \param self Bridge to operate upon.
00216  *
00217  * \note On entry, self is already locked.
00218  *
00219  * \return Merge priority
00220  */
00221 typedef int (*ast_bridge_merge_priority_fn)(struct ast_bridge *self);
00222 
00223 /*!
00224  * \brief Bridge virtual methods table definition.
00225  *
00226  * \note Any changes to this struct must be reflected in
00227  * bridge_alloc() validity checking.
00228  */
00229 struct ast_bridge_methods {
00230    /*! Bridge class name for log messages. */
00231    const char *name;
00232    /*! Destroy the bridge. */
00233    ast_bridge_destructor_fn destroy;
00234    /*! The bridge is being dissolved.  Remove any references to the bridge. */
00235    ast_bridge_dissolving_fn dissolving;
00236    /*! Push the bridge channel into the bridge. */
00237    ast_bridge_push_channel_fn push;
00238    /*! Pull the bridge channel from the bridge. */
00239    ast_bridge_pull_channel_fn pull;
00240    /*! Notify the bridge of a masquerade with the channel. */
00241    ast_bridge_notify_masquerade_fn notify_masquerade;
00242    /*! Get the bridge merge priority. */
00243    ast_bridge_merge_priority_fn get_merge_priority;
00244    /*! Peek at swap channel before it can hang up, prior to push. */
00245    ast_bridge_push_channel_fn push_peek;
00246 };
00247 
00248 /*! Softmix technology parameters. */
00249 struct ast_bridge_softmix {
00250    /*! The video mode softmix is using */
00251    struct ast_bridge_video_mode video_mode;
00252    /*!
00253     * \brief The internal sample rate softmix uses to mix channels.
00254     *
00255     * \note If this value is 0, the sofmix may auto adjust the mixing rate.
00256     */
00257    unsigned int internal_sample_rate;
00258    /*!
00259     * \brief The mixing interval indicates how quickly softmix
00260     * mixing should occur to mix audio.
00261     *
00262     * \note When set to 0, softmix must choose a default interval
00263     * for itself.
00264     */
00265    unsigned int internal_mixing_interval;
00266 };
00267 
00268 /*!
00269  * \brief Structure that contains information about a bridge
00270  */
00271 struct ast_bridge {
00272    /*! Bridge virtual method table. */
00273    const struct ast_bridge_methods *v_table;
00274    /*! "Personality" currently exhibited by bridge subclass */
00275    void *personality;
00276    /*! Bridge technology that is handling the bridge */
00277    struct ast_bridge_technology *technology;
00278    /*! Private information unique to the bridge technology */
00279    void *tech_pvt;
00280    /*! Per-bridge topics */
00281    struct stasis_cp_single *topics;
00282    /*! Call ID associated with the bridge */
00283    ast_callid callid;
00284    /*! Linked list of channels participating in the bridge */
00285    AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
00286    /*! Queue of actions to perform on the bridge. */
00287    AST_LIST_HEAD_NOLOCK(, ast_frame) action_queue;
00288    /*! Softmix technology parameters. */
00289    struct ast_bridge_softmix softmix;
00290    /*! Bridge flags to tweak behavior */
00291    struct ast_flags feature_flags;
00292    /*! Allowed bridge technology capabilities when AST_BRIDGE_FLAG_SMART enabled. */
00293    uint32_t allowed_capabilities;
00294    /*! Number of channels participating in the bridge */
00295    unsigned int num_channels;
00296    /*! Number of active channels in the bridge. */
00297    unsigned int num_active;
00298    /*! Number of channels with AST_BRIDGE_CHANNEL_FLAG_LONELY in the bridge. */
00299    unsigned int num_lonely;
00300    /*!
00301     * \brief Count of the active temporary requests to inhibit bridge merges.
00302     * Zero if merges are allowed.
00303     *
00304     * \note Temporary as in try again in a moment.
00305     */
00306    unsigned int inhibit_merge;
00307    /*! Cause code of the dissolved bridge. */
00308    int cause;
00309    /*! TRUE if the bridge was reconfigured. */
00310    unsigned int reconfigured:1;
00311    /*! TRUE if the bridge has been dissolved.  Any channel that now tries to join is immediately ejected. */
00312    unsigned int dissolved:1;
00313    /*! TRUE if the bridge construction was completed. */
00314    unsigned int construction_completed:1;
00315 
00316    AST_DECLARE_STRING_FIELDS(
00317       /*! Immutable name of the creator for the bridge */
00318       AST_STRING_FIELD(creator);
00319       /*! Immutable name given to the bridge by its creator */
00320       AST_STRING_FIELD(name);
00321       /*! Immutable bridge UUID. */
00322       AST_STRING_FIELD(uniqueid);
00323    );
00324 };
00325 
00326 /*! \brief Bridge base class virtual method table. */
00327 extern struct ast_bridge_methods ast_bridge_base_v_table;
00328 
00329 /*!
00330  * \brief Create a new base class bridge
00331  *
00332  * \param capabilities The capabilities that we require to be used on the bridge
00333  * \param flags Flags that will alter the behavior of the bridge
00334  * \param creator Entity that created the bridge (optional)
00335  * \param name Name given to the bridge by its creator (optional, requires named creator)
00336  * \param id Unique ID given to the bridge by its creator (optional)
00337  *
00338  * \retval a pointer to a new bridge on success
00339  * \retval NULL on failure
00340  *
00341  * Example usage:
00342  *
00343  * \code
00344  * struct ast_bridge *bridge;
00345  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
00346  * \endcode
00347  *
00348  * This creates a no frills two party bridge that will be
00349  * destroyed once one of the channels hangs up.
00350  */
00351 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
00352 
00353 /*!
00354  * \brief Try locking the bridge.
00355  *
00356  * \param bridge Bridge to try locking
00357  *
00358  * \retval 0 on success.
00359  * \retval non-zero on error.
00360  */
00361 #define ast_bridge_trylock(bridge)  _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
00362 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
00363 {
00364    return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
00365 }
00366 
00367 /*!
00368  * \brief Lock the bridge.
00369  *
00370  * \param bridge Bridge to lock
00371  *
00372  * \return Nothing
00373  */
00374 #define ast_bridge_lock(bridge)  _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
00375 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
00376 {
00377    __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
00378 }
00379 
00380 /*!
00381  * \brief Unlock the bridge.
00382  *
00383  * \param bridge Bridge to unlock
00384  *
00385  * \return Nothing
00386  */
00387 #define ast_bridge_unlock(bridge)   _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
00388 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
00389 {
00390    __ao2_unlock(bridge, file, function, line, var);
00391 }
00392 
00393 /*! \brief Lock two bridges. */
00394 #define ast_bridge_lock_both(bridge1, bridge2)     \
00395    do {                                \
00396       for (;;) {                          \
00397          ast_bridge_lock(bridge1);           \
00398          if (!ast_bridge_trylock(bridge2)) {    \
00399             break;                        \
00400          }                             \
00401          ast_bridge_unlock(bridge1);            \
00402          sched_yield();                   \
00403       }                                \
00404    } while (0)
00405 
00406 /*!
00407  * \brief Destroy a bridge
00408  *
00409  * \param bridge Bridge to destroy
00410  * \param cause Cause of bridge being destroyed.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
00411  *
00412  * \retval 0 on success
00413  * \retval -1 on failure
00414  *
00415  * Example usage:
00416  *
00417  * \code
00418  * ast_bridge_destroy(bridge, AST_CAUSE_NORMAL_CLEARING);
00419  * \endcode
00420  *
00421  * This destroys a bridge that was previously created.
00422  *
00423  * \note
00424  * While this function will kick all channels out of the bridge, channels that
00425  * were added to the bridge using ast_bridge_impart() with the flag
00426  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE set must have ast_bridge_depart() called
00427  * on them.
00428  */
00429 int ast_bridge_destroy(struct ast_bridge *bridge, int cause);
00430 
00431 /*!
00432  * \brief Notify bridging that this channel was just masqueraded.
00433  * \since 12.0.0
00434  *
00435  * \param chan Channel just involved in a masquerade
00436  *
00437  * \return Nothing
00438  */
00439 void ast_bridge_notify_masquerade(struct ast_channel *chan);
00440 
00441 enum ast_bridge_join_flags {
00442    /*! The bridge reference is being passed by the caller. */
00443    AST_BRIDGE_JOIN_PASS_REFERENCE = (1 << 0),
00444    /*! The initial bridge join does not cause a COLP exchange. */
00445    AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP = (1 << 1),
00446 };
00447 
00448 /*!
00449  * \brief Join a channel to a bridge (blocking)
00450  *
00451  * \param bridge Bridge to join
00452  * \param chan Channel to join
00453  * \param swap Channel to swap out if swapping (A channel reference is stolen.)
00454  * \param features Bridge features structure
00455  * \param tech_args Optional Bridging tech optimization parameters for this channel.
00456  * \param flags defined by enum ast_bridge_join_flags.
00457  *
00458  * \note The passed in swap channel is always unreffed on return.  It is not a
00459  * good idea to access the swap channel on return or for the caller to keep a
00460  * reference to it.
00461  *
00462  * \note Absolutely _NO_ locks should be held before calling
00463  * this function since it blocks.
00464  *
00465  * \retval 0 if the channel successfully joined the bridge before it exited.
00466  * \retval -1 if the channel failed to join the bridge
00467  *
00468  * Example usage:
00469  *
00470  * \code
00471  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, AST_BRIDGE_JOIN_PASS_REFERENCE);
00472  * \endcode
00473  *
00474  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
00475  * the bridge pointer. This function will not return until the channel has been
00476  * removed from the bridge, swapped out for another channel, or has hung up.
00477  *
00478  * If this channel will be replacing another channel the other channel can be specified
00479  * in the swap parameter. The other channel will be thrown out of the bridge in an
00480  * atomic fashion.
00481  *
00482  * If channel specific features are enabled a pointer to the features structure
00483  * can be specified in the features parameter.
00484  */
00485 int ast_bridge_join(struct ast_bridge *bridge,
00486    struct ast_channel *chan,
00487    struct ast_channel *swap,
00488    struct ast_bridge_features *features,
00489    struct ast_bridge_tech_optimizations *tech_args,
00490    enum ast_bridge_join_flags flags);
00491 
00492 enum ast_bridge_impart_flags {
00493    /*! Field describing what the caller can do with the channel after it is imparted. */
00494    AST_BRIDGE_IMPART_CHAN_MASK = (1 << 0),
00495    /*! The caller wants to reclaim the channel using ast_bridge_depart(). */
00496    AST_BRIDGE_IMPART_CHAN_DEPARTABLE = (0 << 0),
00497    /*! The caller is passing channel control entirely to the bridging system. */
00498    AST_BRIDGE_IMPART_CHAN_INDEPENDENT = (1 << 0),
00499    /*! The initial bridge join does not cause a COLP exchange. */
00500    AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP = (1 << 1),
00501 };
00502 
00503 /*!
00504  * \brief Impart a channel to a bridge (non-blocking)
00505  *
00506  * \param bridge Bridge to impart on
00507  * \param chan Channel to impart (The channel reference is stolen if impart successful.)
00508  * \param swap Channel to swap out if swapping.  NULL if not swapping.
00509  * \param features Bridge features structure.
00510  * \param flags defined by enum ast_bridge_impart_flags.
00511  *
00512  * \note The features parameter must be NULL or obtained by
00513  * ast_bridge_features_new().  You must not dereference features
00514  * after calling even if the call fails.
00515  *
00516  * \note chan is locked by this function.
00517  *
00518  * \retval 0 on success
00519  * \retval -1 on failure (Caller still has ownership of chan)
00520  *
00521  * Example usage:
00522  *
00523  * \code
00524  * ast_bridge_impart(bridge, chan, NULL, NULL, AST_BRIDGE_IMPART_CHAN_INDEPENDENT);
00525  * \endcode
00526  *
00527  * \details
00528  * This adds a channel pointed to by the chan pointer to the
00529  * bridge pointed to by the bridge pointer.  This function will
00530  * return immediately and will not wait until the channel is no
00531  * longer part of the bridge.
00532  *
00533  * If this channel will be replacing another channel the other
00534  * channel can be specified in the swap parameter.  The other
00535  * channel will be thrown out of the bridge in an atomic
00536  * fashion.
00537  *
00538  * If channel specific features are enabled, a pointer to the
00539  * features structure can be specified in the features
00540  * parameter.
00541  *
00542  * \note If you impart a channel with
00543  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE you MUST
00544  * ast_bridge_depart() the channel if this call succeeds.  The
00545  * bridge channel thread is created join-able.  The implication
00546  * is that the channel is special and will not behave like a
00547  * normal channel.
00548  *
00549  * \note If you impart a channel with
00550  * AST_BRIDGE_IMPART_CHAN_INDEPENDENT you must not
00551  * ast_bridge_depart() the channel.  The bridge channel thread
00552  * is created non-join-able.  The channel must be treated as if
00553  * it were placed into the bridge by ast_bridge_join().
00554  * Channels placed into a bridge by ast_bridge_join() are
00555  * removed by a third party using ast_bridge_remove().
00556  */
00557 int ast_bridge_impart(struct ast_bridge *bridge,
00558    struct ast_channel *chan,
00559    struct ast_channel *swap,
00560    struct ast_bridge_features *features,
00561    enum ast_bridge_impart_flags flags) attribute_warn_unused_result;
00562 
00563 /*!
00564  * \brief Depart a channel from a bridge
00565  *
00566  * \param chan Channel to depart
00567  *
00568  * \note chan is locked by this function.
00569  *
00570  * \retval 0 on success
00571  * \retval -1 on failure
00572  *
00573  * Example usage:
00574  *
00575  * \code
00576  * ast_bridge_depart(chan);
00577  * \endcode
00578  *
00579  * This removes the channel pointed to by the chan pointer from any bridge
00580  * it may be in and gives control to the calling thread.
00581  * This does not hang up the channel.
00582  *
00583  * \note This API call can only be used on channels that were added to the bridge
00584  *       using the ast_bridge_impart API call with the AST_BRIDGE_IMPART_CHAN_DEPARTABLE
00585  *       flag.
00586  */
00587 int ast_bridge_depart(struct ast_channel *chan);
00588 
00589 /*!
00590  * \brief Remove a channel from a bridge
00591  *
00592  * \param bridge Bridge that the channel is to be removed from
00593  * \param chan Channel to remove
00594  *
00595  * \retval 0 on success
00596  * \retval -1 on failure
00597  *
00598  * Example usage:
00599  *
00600  * \code
00601  * ast_bridge_remove(bridge, chan);
00602  * \endcode
00603  *
00604  * This removes the channel pointed to by the chan pointer from the bridge
00605  * pointed to by the bridge pointer and requests that it be hung up. Control
00606  * over the channel will NOT be given to the calling thread.
00607  *
00608  * \note This API call can be used on channels that were added to the bridge
00609  *       using both ast_bridge_join and ast_bridge_impart.
00610  */
00611 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
00612 
00613 /*!
00614  * \brief Kick a channel from a bridge
00615  *
00616  * \param bridge Bridge that the channel is to be kicked from
00617  * \param chan Channel to kick
00618  *
00619  * \retval 0 on success
00620  * \retval -1 on failure
00621  *
00622  * Example usage:
00623  *
00624  * \code
00625  * ast_bridge_kick(bridge, chan);
00626  * \endcode
00627  *
00628  * \details
00629  * This kicks the channel pointed to by the chan pointer from
00630  * the bridge pointed to by the bridge pointer and requests that
00631  * it be hung up.  Control over the channel will NOT be given to
00632  * the calling thread.
00633  *
00634  * \note The functional difference between ast_bridge_kick() and
00635  * ast_bridge_remove() is that the bridge may dissolve as a
00636  * result of the channel being kicked.
00637  *
00638  * \note This API call can be used on channels that were added
00639  * to the bridge using both ast_bridge_join and
00640  * ast_bridge_impart.
00641  */
00642 int ast_bridge_kick(struct ast_bridge *bridge, struct ast_channel *chan);
00643 
00644 /*!
00645  * \brief Merge two bridges together
00646  *
00647  * \param dst_bridge Destination bridge of merge.
00648  * \param src_bridge Source bridge of merge.
00649  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
00650  * \param kick_me Array of channels to kick from the bridges.
00651  * \param num_kick Number of channels in the kick_me array.
00652  *
00653  * \note Absolutely _NO_ bridge or channel locks should be held
00654  * before calling this function.
00655  *
00656  * \retval 0 on success
00657  * \retval -1 on failure
00658  *
00659  * Example usage:
00660  *
00661  * \code
00662  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
00663  * \endcode
00664  *
00665  * This moves the channels in src_bridge into the bridge pointed
00666  * to by dst_bridge.
00667  */
00668 int ast_bridge_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge, int merge_best_direction, struct ast_channel **kick_me, unsigned int num_kick);
00669 
00670 /*!
00671  * \brief Move a channel from one bridge to another.
00672  * \since 12.0.0
00673  *
00674  * \param dst_bridge Destination bridge of bridge channel move.
00675  * \param src_bridge Source bridge of bridge channel move.
00676  * \param chan Channel to move.
00677  * \param swap Channel to replace in dst_bridge.
00678  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
00679  *
00680  * \note Absolutely _NO_ bridge or channel locks should be held
00681  * before calling this function.
00682  *
00683  * \retval 0 on success.
00684  * \retval -1 on failure.
00685  */
00686 int ast_bridge_move(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge, struct ast_channel *chan, struct ast_channel *swap, int attempt_recovery);
00687 
00688 /*!
00689  * \brief Adjust the bridge merge inhibit request count.
00690  * \since 12.0.0
00691  *
00692  * \param bridge What to operate on.
00693  * \param request Inhibit request increment.
00694  *     (Positive to add requests.  Negative to remove requests.)
00695  *
00696  * \return Nothing
00697  */
00698 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
00699 
00700 /*!
00701  * \brief Suspend a channel temporarily from a bridge
00702  *
00703  * \param bridge Bridge to suspend the channel from
00704  * \param chan Channel to suspend
00705  *
00706  * \retval 0 on success
00707  * \retval -1 on failure
00708  *
00709  * Example usage:
00710  *
00711  * \code
00712  * ast_bridge_suspend(bridge, chan);
00713  * \endcode
00714  *
00715  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
00716  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
00717  * the channel will not be removed from the bridge.
00718  *
00719  * \note This API call can be used on channels that were added to the bridge
00720  *       using both ast_bridge_join and ast_bridge_impart.
00721  */
00722 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
00723 
00724 /*!
00725  * \brief Unsuspend a channel from a bridge
00726  *
00727  * \param bridge Bridge to unsuspend the channel from
00728  * \param chan Channel to unsuspend
00729  *
00730  * \retval 0 on success
00731  * \retval -1 on failure
00732  *
00733  * Example usage:
00734  *
00735  * \code
00736  * ast_bridge_unsuspend(bridge, chan);
00737  * \endcode
00738  *
00739  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
00740  * The bridge will go back to handling the channel once this function returns.
00741  *
00742  * \note You must not mess with the channel once this function returns.
00743  *       Doing so may result in bad things happening.
00744  */
00745 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
00746 
00747 struct ast_unreal_pvt;
00748 
00749 /*!
00750  * \brief Check and optimize out the unreal channels between bridges.
00751  * \since 12.0.0
00752  *
00753  * \param chan Unreal channel writing a frame into the channel driver.
00754  * \param peer Other unreal channel in the pair.
00755  * \param pvt Private data provided by an implementation of the unreal driver that
00756  * contains the callbacks that should be called when optimization begins/ends
00757  *
00758  * \note It is assumed that chan is already locked.
00759  *
00760  * \retval 0 if unreal channels were not optimized out.
00761  * \retval non-zero if unreal channels were optimized out.
00762  */
00763 int ast_bridge_unreal_optimize_out(struct ast_channel *chan, struct ast_channel *peer, struct ast_unreal_pvt *pvt);
00764 
00765 /*!
00766  * \brief Tells, if optimization is allowed, how the optimization would be performed
00767  */
00768 enum ast_bridge_optimization {
00769    /*! Optimization would swap peer into the chan_bridge */
00770    AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
00771    /*! Optimization would swap chan into the peer_bridge */
00772    AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
00773    /*! Optimization would merge peer_bridge into chan_bridge */
00774    AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
00775    /*! Optimization would merge chan_bridge into peer_bridge */
00776    AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
00777    /*! Optimization is not permitted on one or both bridges */
00778    AST_BRIDGE_OPTIMIZE_PROHIBITED,
00779 };
00780 
00781 /*!
00782  * \brief Determine if bridges allow for optimization to occur betweem them
00783  * \since 12.0.0
00784  *
00785  * \param chan_bridge First bridge being tested
00786  * \param peer_bridge Second bridge being tested
00787  *
00788  * This determines if two bridges allow for unreal channel optimization
00789  * to occur between them. The function does not require for unreal channels
00790  * to already be in the bridges when called.
00791  *
00792  * \note It is assumed that both bridges are locked prior to calling this function
00793  *
00794  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
00795  * that an optimization attempt will succeed. However, a return of
00796  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
00797  * never succeed.
00798  *
00799  * \returns Optimization allowability for the bridges
00800  */
00801 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
00802       struct ast_bridge *peer_bridge);
00803 
00804 /*!
00805  * \brief Put an action onto the specified bridge.
00806  * \since 12.0.0
00807  *
00808  * \param bridge What to queue the action on.
00809  * \param action What to do.
00810  *
00811  * \retval 0 on success.
00812  * \retval -1 on error.
00813  *
00814  * \note This API call is meant for internal bridging operations.
00815  */
00816 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
00817 
00818 /*!
00819  * \brief Queue the given frame to everyone else.
00820  * \since 12.0.0
00821  *
00822  * \param bridge What bridge to distribute frame.
00823  * \param bridge_channel Channel to optionally not pass frame to. (NULL to pass to everyone)
00824  * \param frame Frame to pass.
00825  *
00826  * \note This is intended to be called by bridge hooks and
00827  * bridge technologies.
00828  *
00829  * \retval 0 Frame written to at least one channel.
00830  * \retval -1 Frame written to no channels.
00831  */
00832 int ast_bridge_queue_everyone_else(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
00833 
00834 /*!
00835  * \brief Adjust the internal mixing sample rate of a bridge
00836  * used during multimix mode.
00837  *
00838  * \param bridge Channel to change the sample rate on.
00839  * \param sample_rate the sample rate to change to. If a
00840  *        value of 0 is passed here, the bridge will be free to pick
00841  *        what ever sample rate it chooses.
00842  *
00843  */
00844 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
00845 
00846 /*!
00847  * \brief Adjust the internal mixing interval of a bridge used
00848  * during multimix mode.
00849  *
00850  * \param bridge Channel to change the sample rate on.
00851  * \param mixing_interval the sample rate to change to.  If 0 is set
00852  * the bridge tech is free to choose any mixing interval it uses by default.
00853  */
00854 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
00855 
00856 /*!
00857  * \brief Set a bridge to feed a single video source to all participants.
00858  */
00859 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
00860 
00861 /*!
00862  * \brief Set the bridge to pick the strongest talker supporting
00863  * video as the single source video feed
00864  */
00865 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
00866 
00867 /*!
00868  * \brief Update information about talker energy for talker src video mode.
00869  */
00870 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
00871 
00872 /*!
00873  * \brief Returns the number of video sources currently active in the bridge
00874  */
00875 int ast_bridge_number_video_src(struct ast_bridge *bridge);
00876 
00877 /*!
00878  * \brief Determine if a channel is a video src for the bridge
00879  *
00880  * \retval 0 Not a current video source of the bridge.
00881  * \retval None 0, is a video source of the bridge, The number
00882  *         returned represents the priority this video stream has
00883  *         on the bridge where 1 is the highest priority.
00884  */
00885 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
00886 
00887 /*!
00888  * \brief remove a channel as a source of video for the bridge.
00889  */
00890 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
00891 
00892 enum ast_transfer_result {
00893    /*! The transfer completed successfully */
00894    AST_BRIDGE_TRANSFER_SUCCESS,
00895    /*! A bridge involved does not permit transferring */
00896    AST_BRIDGE_TRANSFER_NOT_PERMITTED,
00897    /*! The current bridge setup makes transferring an invalid operation */
00898    AST_BRIDGE_TRANSFER_INVALID,
00899    /*! The transfer operation failed for a miscellaneous reason */
00900    AST_BRIDGE_TRANSFER_FAIL,
00901 };
00902 
00903 enum ast_transfer_type {
00904    /*! Transfer of a single party */
00905    AST_BRIDGE_TRANSFER_SINGLE_PARTY,
00906    /*! Transfer of multiple parties */
00907    AST_BRIDGE_TRANSFER_MULTI_PARTY,
00908 };
00909 
00910 /*!
00911  * \brief AO2 object that wraps data for transfer_channel_cb
00912  */
00913 struct transfer_channel_data {
00914    void *data;    /*! Data to be used by the transfer_channel_cb -- note that this
00915                    *  pointer is going to be pointing to something on the stack, so
00916                    *  it must not be used at any point after returning from the
00917                    *  transfer_channel_cb. */
00918    int completed; /*! Initially 0, This will be set to 1 by either the transfer
00919                    *  code or by transfer code hooks (e.g. parking) when the
00920                    *  transfer is completed and any remaining actions have taken
00921                    *  place (e.g. parking announcements). It will never be reset
00922                    *  to 0. This is used for deferring progress for channel
00923                    *  drivers that support deferred progress. */
00924 };
00925 
00926 /*!
00927  * \brief Callback function type called during blind transfers
00928  *
00929  * A caller of ast_bridge_transfer_blind() may wish to set data on
00930  * the channel that ends up running dialplan. For instance, it may
00931  * be useful to set channel variables on the channel.
00932  *
00933  * \param chan The involved channel
00934  * \param user_data User-provided data needed in the callback
00935  * \param transfer_type The type of transfer being completed
00936  */
00937 typedef void (*transfer_channel_cb)(struct ast_channel *chan, struct transfer_channel_data *user_data,
00938       enum ast_transfer_type transfer_type);
00939 
00940 /*!
00941  * \brief Blind transfer target to the extension and context provided
00942  *
00943  * The channel given is bridged to one or multiple channels. Depending on
00944  * the bridge and the number of participants, the entire bridge could be
00945  * transferred to the given destination, or a single channel may be redirected.
00946  *
00947  * Callers may also provide a callback to be called on the channel that will
00948  * be running dialplan. The user data passed into ast_bridge_transfer_blind
00949  * will be given as the argument to the callback to be interpreted as desired.
00950  * This callback is guaranteed to be called in the same thread as
00951  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
00952  *
00953  * \note Absolutely _NO_ channel locks should be held before
00954  * calling this function.
00955  *
00956  * \param is_external Indicates that transfer was initiated externally
00957  * \param transferer The channel performing the blind transfer
00958  * \param exten The dialplan extension to send the call to
00959  * \param context The dialplan context to send the call to
00960  * \param new_channel_cb A callback to be called on the channel that will
00961  *        be executing dialplan
00962  * \param user_data Argument for new_channel_cb
00963  * \return The success or failure result of the blind transfer
00964  */
00965 enum ast_transfer_result ast_bridge_transfer_blind(int is_external,
00966       struct ast_channel *transferer, const char *exten, const char *context,
00967       transfer_channel_cb new_channel_cb, void *user_data);
00968 
00969 /*!
00970  * \brief Attended transfer
00971  *
00972  * The two channels are both transferer channels. The first is the channel
00973  * that is bridged to the transferee (or if unbridged, the 'first' call of
00974  * the transfer). The second is the channel that is bridged to the transfer
00975  * target (or if unbridged, the 'second' call of the transfer).
00976  *
00977  * \note Absolutely _NO_ channel locks should be held before
00978  * calling this function.
00979  *
00980  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
00981  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
00982  * \return The success or failure of the attended transfer
00983  */
00984 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
00985       struct ast_channel *to_transfer_target);
00986 
00987 /*!
00988  * \brief Set the relevant transfer variables for a single channel
00989  *
00990  * Sets either the ATTENDEDTRANSFER or BLINDTRANSFER variable for a channel while clearing
00991  * the opposite.
00992  *
00993  * \param chan Channel the variable is being set for
00994  * \param value Value the variable is being set to
00995  * \param is_attended false  set BLINDTRANSFER and unset ATTENDEDTRANSFER
00996  *                    true   set ATTENDEDTRANSFER and unset BLINDTRANSFER
00997  */
00998 void ast_bridge_set_transfer_variables(struct ast_channel *chan, const char *value, int is_attended);
00999 
01000 /*!
01001  * \brief Get a container of all channels in the bridge
01002  * \since 12.0.0
01003  *
01004  * \param bridge The bridge which is already locked.
01005  *
01006  * \retval NULL Failed to create container
01007  * \retval non-NULL Container of channels in the bridge
01008  */
01009 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
01010 
01011 /*!
01012  * \brief Get a container of all channels in the bridge
01013  * \since 12.0.0
01014  *
01015  * \param bridge The bridge
01016  *
01017  * \note The returned container is a snapshot of channels in the
01018  * bridge when called.
01019  *
01020  * \retval NULL Failed to create container
01021  * \retval non-NULL Container of channels in the bridge
01022  */
01023 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
01024 
01025 /*!
01026  * \brief Get the channel's bridge peer only if the bridge is two-party.
01027  * \since 12.0.0
01028  *
01029  * \param bridge The bridge which is already locked.
01030  * \param chan Channel desiring the bridge peer channel.
01031  *
01032  * \note The returned peer channel is the current peer in the
01033  * bridge when called.
01034  *
01035  * \retval NULL Channel not in a bridge or the bridge is not two-party.
01036  * \retval non-NULL Reffed peer channel at time of calling.
01037  */
01038 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
01039 
01040 /*!
01041  * \brief Get the channel's bridge peer only if the bridge is two-party.
01042  * \since 12.0.0
01043  *
01044  * \param bridge The bridge
01045  * \param chan Channel desiring the bridge peer channel.
01046  *
01047  * \note The returned peer channel is the current peer in the
01048  * bridge when called.
01049  *
01050  * \retval NULL Channel not in a bridge or the bridge is not two-party.
01051  * \retval non-NULL Reffed peer channel at time of calling.
01052  */
01053 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
01054 
01055 /*!
01056  * \brief Remove marked bridge channel feature hooks.
01057  * \since 12.0.0
01058  *
01059  * \param features Bridge features structure
01060  * \param flags Determinator for whether hook is removed.
01061  *
01062  * \return Nothing
01063  */
01064 void ast_bridge_features_remove(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags flags);
01065 
01066 /*!
01067  * \brief Find bridge by id
01068  * \since 12.0.0
01069  *
01070  * \param bridge_id Bridge identifier
01071  *
01072  * \return NULL bridge not found
01073  * \return non-NULL reference to bridge
01074  */
01075 struct ast_bridge *ast_bridge_find_by_id(const char *bridge_id);
01076 
01077 #if defined(__cplusplus) || defined(c_plusplus)
01078 }
01079 #endif
01080 
01081 #endif   /* _ASTERISK_BRIDGING_H */

Generated on Thu Apr 16 06:27:15 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6