include/asterisk/bridge.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2007 - 2009, 2013 Digium, Inc.
   5  *
   6  * Richard Mudgett <rmudgett@digium.com>
   7  * Joshua Colp <jcolp@digium.com>
   8  *
   9  * See http://www.asterisk.org for more information about
  10  * the Asterisk project. Please do not directly contact
  11  * any of the maintainers of this project for assistance;
  12  * the project provides a web site, mailing lists and IRC
  13  * channels for your use.
  14  *
  15  * This program is free software, distributed under the terms of
  16  * the GNU General Public License Version 2. See the LICENSE file
  17  * at the top of the source tree.
  18  */
  19
  20 /*!
  21  * \file
  22  * \brief Bridging API
  23  *
  24  * \author Richard Mudgett <rmudgett@digium.com>
  25  * \author Joshua Colp <jcolp@digium.com>
  26  * \ref AstBridging
  27  *
  28  * See Also:
  29  * \arg \ref AstCREDITS
  30  */
  31
  32 /*!
  33  * \page AstBridging Bridging API
  34  *
  35  * The purpose of this API is to provide an easy and flexible way to bridge
  36  * channels of different technologies with different features.
  37  *
  38  * Bridging technologies provide the mechanism that do the actual handling
  39  * of frames between channels. They provide capability information, codec information,
  40  * and preference value to assist the bridging core in choosing a bridging technology when
  41  * creating a bridge. Different bridges may use different bridging technologies based on needs
  42  * but once chosen they all operate under the same premise; they receive frames and send frames.
  43  *
  44  * Bridges are a combination of bridging technology, channels, and features. A
  45  * developer creates a new bridge based on what they are currently expecting to do
  46  * with it or what they will do with it in the future. The bridging core determines what
  47  * available bridging technology will best fit the requirements and creates a new bridge.
  48  * Once created, channels can be added to the bridge in a blocking or non-blocking fashion.
  49  *
  50  * Features are such things as channel muting or DTMF based features such as attended transfer,
  51  * blind transfer, and hangup. Feature information must be set at the most granular level, on
  52  * the channel. While you can use features on a global scope the presence of a feature structure
  53  * on the channel will override the global scope. An example would be having the bridge muted
  54  * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted
  55  * it would be able to speak.
  56  *
  57  * Feature hooks allow a developer to tell the bridging core that when a DTMF string
  58  * is received from a channel a callback should be called in their application. For
  59  * example, a conference bridge application may want to provide an IVR to control various
  60  * settings on the conference bridge. This can be accomplished by attaching a feature hook
  61  * that calls an IVR function when a DTMF string is entered.
  62  *
  63  */
  64
  65 #ifndef _ASTERISK_BRIDGING_H
  66 #define _ASTERISK_BRIDGING_H
  67
  68 #if defined(__cplusplus) || defined(c_plusplus)
  69 extern "C" {
  70 #endif
  71
  72 #include "asterisk/bridge_features.h"
  73 #include "asterisk/bridge_channel.h"
  74 #include "asterisk/bridge_roles.h"
  75 #include "asterisk/dsp.h"
  76 #include "asterisk/uuid.h"
  77
  78 struct ast_bridge_technology;
  79 struct ast_bridge;
  80 struct ast_bridge_tech_optimizations;
  81
  82 /*! \brief Capabilities for a bridge technology */
  83 enum ast_bridge_capability {
  84         /*! Bridge technology can service calls on hold. */
  85         AST_BRIDGE_CAPABILITY_HOLDING = (1 << 0),
  86         /*! Bridge waits for channel to answer.  Passes early media. (XXX Not supported yet) */
  87         AST_BRIDGE_CAPABILITY_EARLY = (1 << 1),
  88         /*! Bridge is capable of natively bridging two channels. (Smart bridge only) */
  89         AST_BRIDGE_CAPABILITY_NATIVE = (1 << 2),
  90         /*! Bridge is capable of mixing at most two channels. (Smart bridgeable) */
  91         AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 3),
  92         /*! Bridge is capable of mixing an arbitrary number of channels. (Smart bridgeable) */
  93         AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 4),
  94 };
  95
  96 /*! \brief Video source modes */
  97 enum ast_bridge_video_mode_type {
  98         /*! Video is not allowed in the bridge */
  99         AST_BRIDGE_VIDEO_MODE_NONE = 0,
 100         /*! A single user is picked as the only distributed of video across the bridge */
 101         AST_BRIDGE_VIDEO_MODE_SINGLE_SRC,
 102         /*! A single user's video feed is distributed to all bridge channels, but
 103          *  that feed is automatically picked based on who is talking the most. */
 104         AST_BRIDGE_VIDEO_MODE_TALKER_SRC,
 105 };
 106
 107 /*! \brief This is used for both SINGLE_SRC mode to set what channel
 108  *  should be the current single video feed */
 109 struct ast_bridge_video_single_src_data {
 110         /*! Only accept video coming from this channel */
 111         struct ast_channel *chan_vsrc;
 112 };
 113
 114 /*! \brief This is used for both SINGLE_SRC_TALKER mode to set what channel
 115  *  should be the current single video feed */
 116 struct ast_bridge_video_talker_src_data {
 117         /*! Only accept video coming from this channel */
 118         struct ast_channel *chan_vsrc;
 119         int average_talking_energy;
 120
 121         /*! Current talker see's this person */
 122         struct ast_channel *chan_old_vsrc;
 123 };
 124
 125 /*! \brief Data structure that defines a video source mode */
 126 struct ast_bridge_video_mode {
 127         enum ast_bridge_video_mode_type mode;
 128         /* Add data for all the video modes here. */
 129         union {
 130                 struct ast_bridge_video_single_src_data single_src_data;
 131                 struct ast_bridge_video_talker_src_data talker_src_data;
 132         } mode_data;
 133 };
 134
 135 /*!
 136  * \brief Destroy the bridge.
 137  *
 138  * \param self Bridge to operate upon.
 139  *
 140  * \return Nothing
 141  */
 142 typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
 143
 144 /*!
 145  * \brief The bridge is being dissolved.
 146  *
 147  * \param self Bridge to operate upon.
 148  *
 149  * \details
 150  * The bridge is being dissolved.  Remove any external
 151  * references to the bridge so it can be destroyed.
 152  *
 153  * \note On entry, self must NOT be locked.
 154  *
 155  * \return Nothing
 156  */
 157 typedef void (*ast_bridge_dissolving_fn)(struct ast_bridge *self);
 158
 159 /*!
 160  * \brief Push this channel into the bridge.
 161  *
 162  * \param self Bridge to operate upon.
 163  * \param bridge_channel Bridge channel to push.
 164  * \param swap Bridge channel to swap places with if not NULL.
 165  *
 166  * \details
 167  * Setup any channel hooks controlled by the bridge.  Allocate
 168  * bridge_channel->bridge_pvt and initialize any resources put
 169  * in bridge_channel->bridge_pvt if needed.  If there is a swap
 170  * channel, use it as a guide to setting up the bridge_channel.
 171  *
 172  * \note On entry, self is already locked.
 173  *
 174  * \retval 0 on success.
 175  * \retval -1 on failure.  The channel did not get pushed.
 176  */
 177 typedef int (*ast_bridge_push_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
 178
 179 /*!
 180  * \brief Pull this channel from the bridge.
 181  *
 182  * \param self Bridge to operate upon.
 183  * \param bridge_channel Bridge channel to pull.
 184  *
 185  * \details
 186  * Remove any channel hooks controlled by the bridge.  Release
 187  * any resources held by bridge_channel->bridge_pvt and release
 188  * bridge_channel->bridge_pvt.
 189  *
 190  * \note On entry, self is already locked.
 191  *
 192  * \return Nothing
 193  */
 194 typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
 195
 196 /*!
 197  * \brief Notify the bridge that this channel was just masqueraded.
 198  *
 199  * \param self Bridge to operate upon.
 200  * \param bridge_channel Bridge channel that was masqueraded.
 201  *
 202  * \details
 203  * A masquerade just happened to this channel.  The bridge needs
 204  * to re-evaluate this a channel in the bridge.
 205  *
 206  * \note On entry, self is already locked.
 207  *
 208  * \return Nothing
 209  */
 210 typedef void (*ast_bridge_notify_masquerade_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
 211
 212 /*!
 213  * \brief Get the merge priority of this bridge.
 214  *
 215  * \param self Bridge to operate upon.
 216  *
 217  * \note On entry, self is already locked.
 218  *
 219  * \return Merge priority
 220  */
 221 typedef int (*ast_bridge_merge_priority_fn)(struct ast_bridge *self);
 222
 223 /*!
 224  * \brief Bridge virtual methods table definition.
 225  *
 226  * \note Any changes to this struct must be reflected in
 227  * bridge_alloc() validity checking.
 228  */
 229 struct ast_bridge_methods {
 230         /*! Bridge class name for log messages. */
 231         const char *name;
 232         /*! Destroy the bridge. */
 233         ast_bridge_destructor_fn destroy;
 234         /*! The bridge is being dissolved.  Remove any references to the bridge. */
 235         ast_bridge_dissolving_fn dissolving;
 236         /*! Push the bridge channel into the bridge. */
 237         ast_bridge_push_channel_fn push;
 238         /*! Pull the bridge channel from the bridge. */
 239         ast_bridge_pull_channel_fn pull;
 240         /*! Notify the bridge of a masquerade with the channel. */
 241         ast_bridge_notify_masquerade_fn notify_masquerade;
 242         /*! Get the bridge merge priority. */
 243         ast_bridge_merge_priority_fn get_merge_priority;
 244 };
 245
 246 struct ast_bridge_channel;
 247
 248 /*! Softmix technology parameters. */
 249 struct ast_bridge_softmix {
 250         /*! The video mode softmix is using */
 251         struct ast_bridge_video_mode video_mode;
 252         /*!
 253          * \brief The internal sample rate softmix uses to mix channels.
 254          *
 255          * \note If this value is 0, the sofmix may auto adjust the mixing rate.
 256          */
 257         unsigned int internal_sample_rate;
 258         /*!
 259          * \brief The mixing interval indicates how quickly softmix
 260          * mixing should occur to mix audio.
 261          *
 262          * \note When set to 0, softmix must choose a default interval
 263          * for itself.
 264          */
 265         unsigned int internal_mixing_interval;
 266 };
 267
 268 /*!
 269  * \brief Structure that contains information about a bridge
 270  */
 271 struct ast_bridge {
 272         /*! Bridge virtual method table. */
 273         const struct ast_bridge_methods *v_table;
 274         /*! "Personality" currently exhibited by bridge subclass */
 275         void *personality;
 276         /*! Bridge technology that is handling the bridge */
 277         struct ast_bridge_technology *technology;
 278         /*! Private information unique to the bridge technology */
 279         void *tech_pvt;
 280         /*! Per-bridge topics */
 281         struct stasis_cp_single *topics;
 282         /*! Call ID associated with the bridge */
 283         struct ast_callid *callid;
 284         /*! Linked list of channels participating in the bridge */
 285         AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
 286         /*! Queue of actions to perform on the bridge. */
 287         AST_LIST_HEAD_NOLOCK(, ast_frame) action_queue;
 288         /*! Softmix technology parameters. */
 289         struct ast_bridge_softmix softmix;
 290         /*! Bridge flags to tweak behavior */
 291         struct ast_flags feature_flags;
 292         /*! Allowed bridge technology capabilities when AST_BRIDGE_FLAG_SMART enabled. */
 293         uint32_t allowed_capabilities;
 294         /*! Number of channels participating in the bridge */
 295         unsigned int num_channels;
 296         /*! Number of active channels in the bridge. */
 297         unsigned int num_active;
 298         /*! Number of channels with AST_BRIDGE_CHANNEL_FLAG_LONELY in the bridge. */
 299         unsigned int num_lonely;
 300         /*!
 301          * \brief Count of the active temporary requests to inhibit bridge merges.
 302          * Zero if merges are allowed.
 303          *
 304          * \note Temporary as in try again in a moment.
 305          */
 306         unsigned int inhibit_merge;
 307         /*! Cause code of the dissolved bridge. */
 308         int cause;
 309         /*! TRUE if the bridge was reconfigured. */
 310         unsigned int reconfigured:1;
 311         /*! TRUE if the bridge has been dissolved.  Any channel that now tries to join is immediately ejected. */
 312         unsigned int dissolved:1;
 313         /*! TRUE if the bridge construction was completed. */
 314         unsigned int construction_completed:1;
 315
 316         AST_DECLARE_STRING_FIELDS(
 317                 /*! Immutable name of the creator for the bridge */
 318                 AST_STRING_FIELD(creator);
 319                 /*! Immutable name given to the bridge by its creator */
 320                 AST_STRING_FIELD(name);
 321                 /*! Immutable bridge UUID. */
 322                 AST_STRING_FIELD(uniqueid);
 323         );
 324 };
 325
 326 /*! \brief Bridge base class virtual method table. */
 327 extern struct ast_bridge_methods ast_bridge_base_v_table;
 328
 329 /*!
 330  * \brief Create a new base class bridge
 331  *
 332  * \param capabilities The capabilities that we require to be used on the bridge
 333  * \param flags Flags that will alter the behavior of the bridge
 334  * \param creator Entity that created the bridge (optional)
 335  * \param name Name given to the bridge by its creator (optional, requires named creator)
 336  *
 337  * \retval a pointer to a new bridge on success
 338  * \retval NULL on failure
 339  *
 340  * Example usage:
 341  *
 342  * \code
 343  * struct ast_bridge *bridge;
 344  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
 345  * \endcode
 346  *
 347  * This creates a no frills two party bridge that will be
 348  * destroyed once one of the channels hangs up.
 349  */
 350 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name);
 351
 352 /*!
 353  * \brief Try locking the bridge.
 354  *
 355  * \param bridge Bridge to try locking
 356  *
 357  * \retval 0 on success.
 358  * \retval non-zero on error.
 359  */
 360 #define ast_bridge_trylock(bridge)      _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
 361 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
 362 {
 363         return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
 364 }
 365
 366 /*!
 367  * \brief Lock the bridge.
 368  *
 369  * \param bridge Bridge to lock
 370  *
 371  * \return Nothing
 372  */
 373 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
 374 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
 375 {
 376         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
 377 }
 378
 379 /*!
 380  * \brief Unlock the bridge.
 381  *
 382  * \param bridge Bridge to unlock
 383  *
 384  * \return Nothing
 385  */
 386 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
 387 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
 388 {
 389         __ao2_unlock(bridge, file, function, line, var);
 390 }
 391
 392 /*! \brief Lock two bridges. */
 393 #define ast_bridge_lock_both(bridge1, bridge2)          \
 394         do {                                                                                    \
 395                 for (;;) {                                                                      \
 396                         ast_bridge_lock(bridge1);                               \
 397                         if (!ast_bridge_trylock(bridge2)) {             \
 398                                 break;                                                          \
 399                         }                                                                               \
 400                         ast_bridge_unlock(bridge1);                             \
 401                         sched_yield();                                                  \
 402                 }                                                                                       \
 403         } while (0)
 404
 405 /*!
 406  * \brief Destroy a bridge
 407  *
 408  * \param bridge Bridge to destroy
 409  * \param cause Cause of bridge being destroyed.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
 410  *
 411  * \retval 0 on success
 412  * \retval -1 on failure
 413  *
 414  * Example usage:
 415  *
 416  * \code
 417  * ast_bridge_destroy(bridge, AST_CAUSE_NORMAL_CLEARING);
 418  * \endcode
 419  *
 420  * This destroys a bridge that was previously created.
 421  *
 422  * \note
 423  * While this function will kick all channels out of the bridge, channels that
 424  * were added to the bridge using ast_bridge_impart() with the flag
 425  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE set must have ast_bridge_depart() called
 426  * on them.
 427  */
 428 int ast_bridge_destroy(struct ast_bridge *bridge, int cause);
 429
 430 /*!
 431  * \brief Notify bridging that this channel was just masqueraded.
 432  * \since 12.0.0
 433  *
 434  * \param chan Channel just involved in a masquerade
 435  *
 436  * \return Nothing
 437  */
 438 void ast_bridge_notify_masquerade(struct ast_channel *chan);
 439
 440 enum ast_bridge_join_flags {
 441         /*! The bridge reference is being passed by the caller. */
 442         AST_BRIDGE_JOIN_PASS_REFERENCE = (1 << 0),
 443         /*! The initial bridge join does not cause a COLP exchange. */
 444         AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP = (1 << 1),
 445 };
 446
 447 /*!
 448  * \brief Join (blocking) a channel to a bridge
 449  *
 450  * \param bridge Bridge to join
 451  * \param chan Channel to join
 452  * \param swap Channel to swap out if swapping
 453  * \param features Bridge features structure
 454  * \param tech_args Optional Bridging tech optimization parameters for this channel.
 455  * \param flags defined by enum ast_bridge_join_flags.
 456  *
 457  * \note Absolutely _NO_ locks should be held before calling
 458  * this function since it blocks.
 459  *
 460  * \retval 0 if the channel successfully joined the bridge before it exited.
 461  * \retval -1 if the channel failed to join the bridge
 462  *
 463  * Example usage:
 464  *
 465  * \code
 466  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, AST_BRIDGE_JOIN_PASS_REFERENCE);
 467  * \endcode
 468  *
 469  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
 470  * the bridge pointer. This function will not return until the channel has been
 471  * removed from the bridge, swapped out for another channel, or has hung up.
 472  *
 473  * If this channel will be replacing another channel the other channel can be specified
 474  * in the swap parameter. The other channel will be thrown out of the bridge in an
 475  * atomic fashion.
 476  *
 477  * If channel specific features are enabled a pointer to the features structure
 478  * can be specified in the features parameter.
 479  */
 480 int ast_bridge_join(struct ast_bridge *bridge,
 481         struct ast_channel *chan,
 482         struct ast_channel *swap,
 483         struct ast_bridge_features *features,
 484         struct ast_bridge_tech_optimizations *tech_args,
 485         enum ast_bridge_join_flags flags);
 486
 487 enum ast_bridge_impart_flags {
 488         /*! Field describing what the caller can do with the channel after it is imparted. */
 489         AST_BRIDGE_IMPART_CHAN_MASK = (1 << 0),
 490         /*! The caller wants to reclaim the channel using ast_bridge_depart(). */
 491         AST_BRIDGE_IMPART_CHAN_DEPARTABLE = (0 << 0),
 492         /*! The caller is passing channel control entirely to the bridging system. */
 493         AST_BRIDGE_IMPART_CHAN_INDEPENDENT = (1 << 0),
 494         /*! The initial bridge join does not cause a COLP exchange. */
 495         AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP = (1 << 1),
 496 };
 497
 498 /*!
 499  * \brief Impart (non-blocking) a channel onto a bridge
 500  *
 501  * \param bridge Bridge to impart on
 502  * \param chan Channel to impart (The channel reference is stolen if impart successful.)
 503  * \param swap Channel to swap out if swapping.  NULL if not swapping.
 504  * \param features Bridge features structure.
 505  * \param flags defined by enum ast_bridge_impart_flags.
 506  *
 507  * \note The features parameter must be NULL or obtained by
 508  * ast_bridge_features_new().  You must not dereference features
 509  * after calling even if the call fails.
 510  *
 511  * \note chan is locked by this function.
 512  *
 513  * \retval 0 on success
 514  * \retval -1 on failure (Caller still has ownership of chan)
 515  *
 516  * Example usage:
 517  *
 518  * \code
 519  * ast_bridge_impart(bridge, chan, NULL, NULL, AST_BRIDGE_IMPART_CHAN_INDEPENDENT);
 520  * \endcode
 521  *
 522  * \details
 523  * This adds a channel pointed to by the chan pointer to the
 524  * bridge pointed to by the bridge pointer.  This function will
 525  * return immediately and will not wait until the channel is no
 526  * longer part of the bridge.
 527  *
 528  * If this channel will be replacing another channel the other
 529  * channel can be specified in the swap parameter.  The other
 530  * channel will be thrown out of the bridge in an atomic
 531  * fashion.
 532  *
 533  * If channel specific features are enabled, a pointer to the
 534  * features structure can be specified in the features
 535  * parameter.
 536  *
 537  * \note If you impart a channel with
 538  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE you MUST
 539  * ast_bridge_depart() the channel if this call succeeds.  The
 540  * bridge channel thread is created join-able.  The implication
 541  * is that the channel is special and will not behave like a
 542  * normal channel.
 543  *
 544  * \note If you impart a channel with
 545  * AST_BRIDGE_IMPART_CHAN_INDEPENDENT you must not
 546  * ast_bridge_depart() the channel.  The bridge channel thread
 547  * is created non-join-able.  The channel must be treated as if
 548  * it were placed into the bridge by ast_bridge_join().
 549  * Channels placed into a bridge by ast_bridge_join() are
 550  * removed by a third party using ast_bridge_remove().
 551  */
 552 int ast_bridge_impart(struct ast_bridge *bridge,
 553         struct ast_channel *chan,
 554         struct ast_channel *swap,
 555         struct ast_bridge_features *features,
 556         enum ast_bridge_impart_flags flags) attribute_warn_unused_result;
 557
 558 /*!
 559  * \brief Depart a channel from a bridge
 560  *
 561  * \param chan Channel to depart
 562  *
 563  * \note chan is locked by this function.
 564  *
 565  * \retval 0 on success
 566  * \retval -1 on failure
 567  *
 568  * Example usage:
 569  *
 570  * \code
 571  * ast_bridge_depart(chan);
 572  * \endcode
 573  *
 574  * This removes the channel pointed to by the chan pointer from any bridge
 575  * it may be in and gives control to the calling thread.
 576  * This does not hang up the channel.
 577  *
 578  * \note This API call can only be used on channels that were added to the bridge
 579  *       using the ast_bridge_impart API call with the AST_BRIDGE_IMPART_CHAN_DEPARTABLE
 580  *       flag.
 581  */
 582 int ast_bridge_depart(struct ast_channel *chan);
 583
 584 /*!
 585  * \brief Remove a channel from a bridge
 586  *
 587  * \param bridge Bridge that the channel is to be removed from
 588  * \param chan Channel to remove
 589  *
 590  * \retval 0 on success
 591  * \retval -1 on failure
 592  *
 593  * Example usage:
 594  *
 595  * \code
 596  * ast_bridge_remove(bridge, chan);
 597  * \endcode
 598  *
 599  * This removes the channel pointed to by the chan pointer from the bridge
 600  * pointed to by the bridge pointer and requests that it be hung up. Control
 601  * over the channel will NOT be given to the calling thread.
 602  *
 603  * \note This API call can be used on channels that were added to the bridge
 604  *       using both ast_bridge_join and ast_bridge_impart.
 605  */
 606 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
 607
 608 /*!
 609  * \brief Kick a channel from a bridge
 610  *
 611  * \param bridge Bridge that the channel is to be kicked from
 612  * \param chan Channel to kick
 613  *
 614  * \retval 0 on success
 615  * \retval -1 on failure
 616  *
 617  * Example usage:
 618  *
 619  * \code
 620  * ast_bridge_kick(bridge, chan);
 621  * \endcode
 622  *
 623  * \details
 624  * This kicks the channel pointed to by the chan pointer from
 625  * the bridge pointed to by the bridge pointer and requests that
 626  * it be hung up.  Control over the channel will NOT be given to
 627  * the calling thread.
 628  *
 629  * \note The functional difference between ast_bridge_kick() and
 630  * ast_bridge_remove() is that the bridge may dissolve as a
 631  * result of the channel being kicked.
 632  *
 633  * \note This API call can be used on channels that were added
 634  * to the bridge using both ast_bridge_join and
 635  * ast_bridge_impart.
 636  */
 637 int ast_bridge_kick(struct ast_bridge *bridge, struct ast_channel *chan);
 638
 639 /*!
 640  * \brief Merge two bridges together
 641  *
 642  * \param dst_bridge Destination bridge of merge.
 643  * \param src_bridge Source bridge of merge.
 644  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
 645  * \param kick_me Array of channels to kick from the bridges.
 646  * \param num_kick Number of channels in the kick_me array.
 647  *
 648  * \note Absolutely _NO_ bridge or channel locks should be held
 649  * before calling this function.
 650  *
 651  * \retval 0 on success
 652  * \retval -1 on failure
 653  *
 654  * Example usage:
 655  *
 656  * \code
 657  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
 658  * \endcode
 659  *
 660  * This moves the channels in src_bridge into the bridge pointed
 661  * to by dst_bridge.
 662  */
 663 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);
 664
 665 /*!
 666  * \brief Move a channel from one bridge to another.
 667  * \since 12.0.0
 668  *
 669  * \param dst_bridge Destination bridge of bridge channel move.
 670  * \param src_bridge Source bridge of bridge channel move.
 671  * \param chan Channel to move.
 672  * \param swap Channel to replace in dst_bridge.
 673  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
 674  *
 675  * \note Absolutely _NO_ bridge or channel locks should be held
 676  * before calling this function.
 677  *
 678  * \retval 0 on success.
 679  * \retval -1 on failure.
 680  */
 681 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);
 682
 683 /*!
 684  * \brief Adjust the bridge merge inhibit request count.
 685  * \since 12.0.0
 686  *
 687  * \param bridge What to operate on.
 688  * \param request Inhibit request increment.
 689  *     (Positive to add requests.  Negative to remove requests.)
 690  *
 691  * \return Nothing
 692  */
 693 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
 694
 695 /*!
 696  * \brief Suspend a channel temporarily from a bridge
 697  *
 698  * \param bridge Bridge to suspend the channel from
 699  * \param chan Channel to suspend
 700  *
 701  * \retval 0 on success
 702  * \retval -1 on failure
 703  *
 704  * Example usage:
 705  *
 706  * \code
 707  * ast_bridge_suspend(bridge, chan);
 708  * \endcode
 709  *
 710  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
 711  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
 712  * the channel will not be removed from the bridge.
 713  *
 714  * \note This API call can be used on channels that were added to the bridge
 715  *       using both ast_bridge_join and ast_bridge_impart.
 716  */
 717 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
 718
 719 /*!
 720  * \brief Unsuspend a channel from a bridge
 721  *
 722  * \param bridge Bridge to unsuspend the channel from
 723  * \param chan Channel to unsuspend
 724  *
 725  * \retval 0 on success
 726  * \retval -1 on failure
 727  *
 728  * Example usage:
 729  *
 730  * \code
 731  * ast_bridge_unsuspend(bridge, chan);
 732  * \endcode
 733  *
 734  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
 735  * The bridge will go back to handling the channel once this function returns.
 736  *
 737  * \note You must not mess with the channel once this function returns.
 738  *       Doing so may result in bad things happening.
 739  */
 740 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
 741
 742 struct ast_unreal_pvt;
 743
 744 /*!
 745  * \brief Check and optimize out the unreal channels between bridges.
 746  * \since 12.0.0
 747  *
 748  * \param chan Unreal channel writing a frame into the channel driver.
 749  * \param peer Other unreal channel in the pair.
 750  * \param pvt Private data provided by an implementation of the unreal driver that
 751  * contains the callbacks that should be called when optimization begins/ends
 752  *
 753  * \note It is assumed that chan is already locked.
 754  *
 755  * \retval 0 if unreal channels were not optimized out.
 756  * \retval non-zero if unreal channels were optimized out.
 757  */
 758 int ast_bridge_unreal_optimize_out(struct ast_channel *chan, struct ast_channel *peer, struct ast_unreal_pvt *pvt);
 759
 760 /*!
 761  * \brief Tells, if optimization is allowed, how the optimization would be performed
 762  */
 763 enum ast_bridge_optimization {
 764         /*! Optimization would swap peer into the chan_bridge */
 765         AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
 766         /*! Optimization would swap chan into the peer_bridge */
 767         AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
 768         /*! Optimization would merge peer_bridge into chan_bridge */
 769         AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
 770         /*! Optimization would merge chan_bridge into peer_bridge */
 771         AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
 772         /*! Optimization is not permitted on one or both bridges */
 773         AST_BRIDGE_OPTIMIZE_PROHIBITED,
 774 };
 775
 776 /*!
 777  * \brief Determine if bridges allow for optimization to occur betweem them
 778  * \since 12.0.0
 779  *
 780  * \param chan_bridge First bridge being tested
 781  * \param peer_bridge Second bridge being tested
 782  *
 783  * This determines if two bridges allow for unreal channel optimization
 784  * to occur between them. The function does not require for unreal channels
 785  * to already be in the bridges when called.
 786  *
 787  * \note It is assumed that both bridges are locked prior to calling this function
 788  *
 789  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
 790  * that an optimization attempt will succeed. However, a return of
 791  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
 792  * never succeed.
 793  *
 794  * \returns Optimization allowability for the bridges
 795  */
 796 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
 797                 struct ast_bridge *peer_bridge);
 798
 799 /*!
 800  * \brief Put an action onto the specified bridge.
 801  * \since 12.0.0
 802  *
 803  * \param bridge What to queue the action on.
 804  * \param action What to do.
 805  *
 806  * \retval 0 on success.
 807  * \retval -1 on error.
 808  *
 809  * \note This API call is meant for internal bridging operations.
 810  */
 811 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
 812
 813 /*!
 814  * \brief Queue the given frame to everyone else.
 815  * \since 12.0.0
 816  *
 817  * \param bridge What bridge to distribute frame.
 818  * \param bridge_channel Channel to optionally not pass frame to. (NULL to pass to everyone)
 819  * \param frame Frame to pass.
 820  *
 821  * \note This is intended to be called by bridge hooks and
 822  * bridge technologies.
 823  *
 824  * \retval 0 Frame written to at least one channel.
 825  * \retval -1 Frame written to no channels.
 826  */
 827 int ast_bridge_queue_everyone_else(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
 828
 829 /*!
 830  * \brief Adjust the internal mixing sample rate of a bridge
 831  * used during multimix mode.
 832  *
 833  * \param bridge Channel to change the sample rate on.
 834  * \param sample_rate the sample rate to change to. If a
 835  *        value of 0 is passed here, the bridge will be free to pick
 836  *        what ever sample rate it chooses.
 837  *
 838  */
 839 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
 840
 841 /*!
 842  * \brief Adjust the internal mixing interval of a bridge used
 843  * during multimix mode.
 844  *
 845  * \param bridge Channel to change the sample rate on.
 846  * \param mixing_interval the sample rate to change to.  If 0 is set
 847  * the bridge tech is free to choose any mixing interval it uses by default.
 848  */
 849 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
 850
 851 /*!
 852  * \brief Set a bridge to feed a single video source to all participants.
 853  */
 854 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
 855
 856 /*!
 857  * \brief Set the bridge to pick the strongest talker supporting
 858  * video as the single source video feed
 859  */
 860 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
 861
 862 /*!
 863  * \brief Update information about talker energy for talker src video mode.
 864  */
 865 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
 866
 867 /*!
 868  * \brief Returns the number of video sources currently active in the bridge
 869  */
 870 int ast_bridge_number_video_src(struct ast_bridge *bridge);
 871
 872 /*!
 873  * \brief Determine if a channel is a video src for the bridge
 874  *
 875  * \retval 0 Not a current video source of the bridge.
 876  * \retval None 0, is a video source of the bridge, The number
 877  *         returned represents the priority this video stream has
 878  *         on the bridge where 1 is the highest priority.
 879  */
 880 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
 881
 882 /*!
 883  * \brief remove a channel as a source of video for the bridge.
 884  */
 885 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
 886
 887 enum ast_transfer_result {
 888         /*! The transfer completed successfully */
 889         AST_BRIDGE_TRANSFER_SUCCESS,
 890         /*! A bridge involved does not permit transferring */
 891         AST_BRIDGE_TRANSFER_NOT_PERMITTED,
 892         /*! The current bridge setup makes transferring an invalid operation */
 893         AST_BRIDGE_TRANSFER_INVALID,
 894         /*! The transfer operation failed for a miscellaneous reason */
 895         AST_BRIDGE_TRANSFER_FAIL,
 896 };
 897
 898 enum ast_transfer_type {
 899         /*! Transfer of a single party */
 900         AST_BRIDGE_TRANSFER_SINGLE_PARTY,
 901         /*! Transfer of multiple parties */
 902         AST_BRIDGE_TRANSFER_MULTI_PARTY,
 903 };
 904
 905 /*!
 906  * \brief Callback function type called during blind transfers
 907  *
 908  * A caller of ast_bridge_transfer_blind() may wish to set data on
 909  * the channel that ends up running dialplan. For instance, it may
 910  * be useful to set channel variables on the channel.
 911  *
 912  * \param chan The involved channel
 913  * \param user_data User-provided data needed in the callback
 914  * \param transfer_type The type of transfer being completed
 915  */
 916 typedef void (*transfer_channel_cb)(struct ast_channel *chan, void *user_data,
 917                 enum ast_transfer_type transfer_type);
 918
 919 /*!
 920  * \brief Blind transfer target to the extension and context provided
 921  *
 922  * The channel given is bridged to one or multiple channels. Depending on
 923  * the bridge and the number of participants, the entire bridge could be
 924  * transferred to the given destination, or a single channel may be redirected.
 925  *
 926  * Callers may also provide a callback to be called on the channel that will
 927  * be running dialplan. The user data passed into ast_bridge_transfer_blind
 928  * will be given as the argument to the callback to be interpreted as desired.
 929  * This callback is guaranteed to be called in the same thread as
 930  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
 931  *
 932  * \note Absolutely _NO_ channel locks should be held before
 933  * calling this function.
 934  *
 935  * \param is_external Indicates that transfer was initiated externally
 936  * \param transferer The channel performing the blind transfer
 937  * \param exten The dialplan extension to send the call to
 938  * \param context The dialplan context to send the call to
 939  * \param new_channel_cb A callback to be called on the channel that will
 940  *        be executing dialplan
 941  * \param user_data Argument for new_channel_cb
 942  * \return The success or failure result of the blind transfer
 943  */
 944 enum ast_transfer_result ast_bridge_transfer_blind(int is_external,
 945                 struct ast_channel *transferer, const char *exten, const char *context,
 946                 transfer_channel_cb new_channel_cb, void *user_data);
 947
 948 /*!
 949  * \brief Attended transfer
 950  *
 951  * The two channels are both transferer channels. The first is the channel
 952  * that is bridged to the transferee (or if unbridged, the 'first' call of
 953  * the transfer). The second is the channel that is bridged to the transfer
 954  * target (or if unbridged, the 'second' call of the transfer).
 955  *
 956  * \note Absolutely _NO_ channel locks should be held before
 957  * calling this function.
 958  *
 959  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
 960  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
 961  * \return The success or failure of the attended transfer
 962  */
 963 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
 964                 struct ast_channel *to_transfer_target);
 965
 966 /*!
 967  * \brief Set the relevant transfer variables for a single channel
 968  *
 969  * Sets either the ATTENDEDTRANSFER or BLINDTRANSFER variable for a channel while clearing
 970  * the opposite.
 971  *
 972  * \param chan Channel the variable is being set for
 973  * \param value Value the variable is being set to
 974  * \param is_attended false  set BLINDTRANSFER and unset ATTENDEDTRANSFER
 975  *                    true   set ATTENDEDTRANSFER and unset BLINDTRANSFER
 976  */
 977 void ast_bridge_set_transfer_variables(struct ast_channel *chan, const char *value, int is_attended);
 978
 979 /*!
 980  * \brief Get a container of all channels in the bridge
 981  * \since 12.0.0
 982  *
 983  * \param bridge The bridge which is already locked.
 984  *
 985  * \retval NULL Failed to create container
 986  * \retval non-NULL Container of channels in the bridge
 987  */
 988 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
 989
 990 /*!
 991  * \brief Get a container of all channels in the bridge
 992  * \since 12.0.0
 993  *
 994  * \param bridge The bridge
 995  *
 996  * \note The returned container is a snapshot of channels in the
 997  * bridge when called.
 998  *
 999  * \retval NULL Failed to create container
1000  * \retval non-NULL Container of channels in the bridge
1001  */
1002 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
1003
1004 /*!
1005  * \brief Get the channel's bridge peer only if the bridge is two-party.
1006  * \since 12.0.0
1007  *
1008  * \param bridge The bridge which is already locked.
1009  * \param chan Channel desiring the bridge peer channel.
1010  *
1011  * \note The returned peer channel is the current peer in the
1012  * bridge when called.
1013  *
1014  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1015  * \retval non-NULL Reffed peer channel at time of calling.
1016  */
1017 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
1018
1019 /*!
1020  * \brief Get the channel's bridge peer only if the bridge is two-party.
1021  * \since 12.0.0
1022  *
1023  * \param bridge The bridge
1024  * \param chan Channel desiring the bridge peer channel.
1025  *
1026  * \note The returned peer channel is the current peer in the
1027  * bridge when called.
1028  *
1029  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1030  * \retval non-NULL Reffed peer channel at time of calling.
1031  */
1032 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
1033
1034 /*!
1035  * \brief Remove marked bridge channel feature hooks.
1036  * \since 12.0.0
1037  *
1038  * \param features Bridge features structure
1039  * \param flags Determinator for whether hook is removed.
1040  *
1041  * \return Nothing
1042  */
1043 void ast_bridge_features_remove(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags flags);
1044
1045 /*!
1046  * \brief Find bridge by id
1047  * \since 12.0.0
1048  *
1049  * \param bridge_id Bridge identifier
1050  *
1051  * \return NULL bridge not found
1052  * \return non-NULL reference to bridge
1053  */
1054 struct ast_bridge *ast_bridge_find_by_id(const char *bridge_id);
1055
1056 #if defined(__cplusplus) || defined(c_plusplus)
1057 }
1058 #endif
1059
1060 #endif  /* _ASTERISK_BRIDGING_H */