include/asterisk/bridging.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2007 - 2009, Digium, Inc.
   5  *
   6  * Joshua Colp <jcolp@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Channel Bridging API
  21  * \author Joshua Colp <jcolp@digium.com>
  22  * \ref AstBridging
  23  */
  24
  25 /*!
  26  * \page AstBridging Channel Bridging API
  27  *
  28  * The purpose of this API is to provide an easy and flexible way to bridge
  29  * channels of different technologies with different features.
  30  *
  31  * Bridging technologies provide the mechanism that do the actual handling
  32  * of frames between channels. They provide capability information, codec information,
  33  * and preference value to assist the bridging core in choosing a bridging technology when
  34  * creating a bridge. Different bridges may use different bridging technologies based on needs
  35  * but once chosen they all operate under the same premise; they receive frames and send frames.
  36  *
  37  * Bridges are a combination of bridging technology, channels, and features. A
  38  * developer creates a new bridge based on what they are currently expecting to do
  39  * with it or what they will do with it in the future. The bridging core determines what
  40  * available bridging technology will best fit the requirements and creates a new bridge.
  41  * Once created, channels can be added to the bridge in a blocking or non-blocking fashion.
  42  *
  43  * Features are such things as channel muting or DTMF based features such as attended transfer,
  44  * blind transfer, and hangup. Feature information must be set at the most granular level, on
  45  * the channel. While you can use features on a global scope the presence of a feature structure
  46  * on the channel will override the global scope. An example would be having the bridge muted
  47  * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted
  48  * it would be able to speak.
  49  *
  50  * Feature hooks allow a developer to tell the bridging core that when a DTMF string
  51  * is received from a channel a callback should be called in their application. For
  52  * example, a conference bridge application may want to provide an IVR to control various
  53  * settings on the conference bridge. This can be accomplished by attaching a feature hook
  54  * that calls an IVR function when a DTMF string is entered.
  55  *
  56  */
  57
  58 #ifndef _ASTERISK_BRIDGING_H
  59 #define _ASTERISK_BRIDGING_H
  60
  61 #if defined(__cplusplus) || defined(c_plusplus)
  62 extern "C" {
  63 #endif
  64
  65 #include "asterisk/bridging_features.h"
  66 #include "asterisk/dsp.h"
  67
  68 /*! \brief Capabilities for a bridge technology */
  69 enum ast_bridge_capability {
  70         /*! Bridge is only capable of mixing 2 channels */
  71         AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1),
  72         /*! Bridge is capable of mixing 2 or more channels */
  73         AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2),
  74         /*! Bridge should natively bridge two channels if possible */
  75         AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3),
  76         /*! Bridge should run using the multithreaded model */
  77         AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),
  78         /*! Bridge should run a central bridge thread */
  79         AST_BRIDGE_CAPABILITY_THREAD = (1 << 5),
  80         /*! Bridge technology can do video mixing (or something along those lines) */
  81         AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
  82         /*! Bridge technology can optimize things based on who is talking */
  83         AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7),
  84 };
  85
  86 /*! \brief State information about a bridged channel */
  87 enum ast_bridge_channel_state {
  88         /*! Waiting for a signal */
  89         AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
  90         /*! Bridged channel has ended itself (it has hung up) */
  91         AST_BRIDGE_CHANNEL_STATE_END,
  92         /*! Bridged channel should be hung up */
  93         AST_BRIDGE_CHANNEL_STATE_HANGUP,
  94         /*! Bridged channel should be removed from the bridge without being hung up */
  95         AST_BRIDGE_CHANNEL_STATE_DEPART,
  96         /*! Bridged channel is executing a feature hook */
  97         AST_BRIDGE_CHANNEL_STATE_FEATURE,
  98         /*! Bridged channel is sending a DTMF stream out */
  99         AST_BRIDGE_CHANNEL_STATE_DTMF,
 100         /*! Bridged channel began talking */
 101         AST_BRIDGE_CHANNEL_STATE_START_TALKING,
 102         /*! Bridged channel has stopped talking */
 103         AST_BRIDGE_CHANNEL_STATE_STOP_TALKING,
 104 };
 105
 106 /*! \brief Return values for bridge technology write function */
 107 enum ast_bridge_write_result {
 108         /*! Bridge technology wrote out frame fine */
 109         AST_BRIDGE_WRITE_SUCCESS = 0,
 110         /*! Bridge technology attempted to write out the frame but failed */
 111         AST_BRIDGE_WRITE_FAILED,
 112         /*! Bridge technology does not support writing out a frame of this type */
 113         AST_BRIDGE_WRITE_UNSUPPORTED,
 114 };
 115
 116 struct ast_bridge_technology;
 117 struct ast_bridge;
 118
 119 /*!
 120  * \brief Structure specific to bridge technologies capable of
 121  * performing talking optimizations.
 122  */
 123 struct ast_bridge_tech_optimizations {
 124         /*! The amount of time in ms that talking must be detected before
 125          *  the dsp determines that talking has occurred */
 126         unsigned int talking_threshold;
 127         /*! The amount of time in ms that silence must be detected before
 128          *  the dsp determines that talking has stopped */
 129         unsigned int silence_threshold;
 130         /*! Whether or not the bridging technology should drop audio
 131          *  detected as silence from the mix. */
 132         unsigned int drop_silence:1;
 133 };
 134
 135 /*!
 136  * \brief Structure that contains information regarding a channel in a bridge
 137  */
 138 struct ast_bridge_channel {
 139         /*! Lock to protect this data structure */
 140         ast_mutex_t lock;
 141         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
 142         ast_cond_t cond;
 143         /*! Current bridged channel state */
 144         enum ast_bridge_channel_state state;
 145         /*! Asterisk channel participating in the bridge */
 146         struct ast_channel *chan;
 147         /*! Asterisk channel we are swapping with (if swapping) */
 148         struct ast_channel *swap;
 149         /*! Bridge this channel is participating in */
 150         struct ast_bridge *bridge;
 151         /*! Private information unique to the bridge technology */
 152         void *bridge_pvt;
 153         /*! Thread handling the bridged channel */
 154         pthread_t thread;
 155         /*! Additional file descriptors to look at */
 156         int fds[4];
 157         /*! Bit to indicate whether the channel is suspended from the bridge or not */
 158         unsigned int suspended:1;
 159         /*! Features structure for features that are specific to this channel */
 160         struct ast_bridge_features *features;
 161         /*! Technology optimization parameters used by bridging technologies capable of
 162          *  optimizing based upon talk detection. */
 163         struct ast_bridge_tech_optimizations tech_args;
 164         /*! Queue of DTMF digits used for DTMF streaming */
 165         char dtmf_stream_q[8];
 166         /*! Linked list information */
 167         AST_LIST_ENTRY(ast_bridge_channel) entry;
 168 };
 169
 170 enum ast_bridge_video_mode_type {
 171         /*! Video is not allowed in the bridge */
 172         AST_BRIDGE_VIDEO_MODE_NONE = 0,
 173         /*! A single user is picked as the only distributed of video across the bridge */
 174         AST_BRIDGE_VIDEO_MODE_SINGLE_SRC,
 175         /*! A single user's video feed is distributed to all bridge channels, but
 176          *  that feed is automatically picked based on who is talking the most. */
 177         AST_BRIDGE_VIDEO_MODE_TALKER_SRC,
 178 };
 179
 180 /*! This is used for both SINGLE_SRC mode to set what channel
 181  *  should be the current single video feed */
 182 struct ast_bridge_video_single_src_data {
 183         /*! Only accept video coming from this channel */
 184         struct ast_channel *chan_vsrc;
 185 };
 186
 187 /*! This is used for both SINGLE_SRC_TALKER mode to set what channel
 188  *  should be the current single video feed */
 189 struct ast_bridge_video_talker_src_data {
 190         /*! Only accept video coming from this channel */
 191         struct ast_channel *chan_vsrc;
 192         int average_talking_energy;
 193 };
 194
 195 struct ast_bridge_video_mode {
 196         enum ast_bridge_video_mode_type mode;
 197         /* Add data for all the video modes here. */
 198         union {
 199                 struct ast_bridge_video_single_src_data single_src_data;
 200                 struct ast_bridge_video_talker_src_data talker_src_data;
 201         } mode_data;
 202 };
 203
 204 /*!
 205  * \brief Structure that contains information about a bridge
 206  */
 207 struct ast_bridge {
 208         /*! Number of channels participating in the bridge */
 209         int num;
 210         /*! The video mode this bridge is using */
 211         struct ast_bridge_video_mode video_mode;
 212         /*! The internal sample rate this bridge is mixed at when multiple channels are being mixed.
 213          *  If this value is 0, the bridge technology may auto adjust the internal mixing rate. */
 214         unsigned int internal_sample_rate;
 215         /*! The mixing interval indicates how quickly the bridges internal mixing should occur
 216          * for bridge technologies that mix audio. When set to 0, the bridge tech must choose a
 217          * default interval for itself. */
 218         unsigned int internal_mixing_interval;
 219         /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */
 220         unsigned int waiting:1;
 221         /*! Bit to indicate the bridge thread should stop */
 222         unsigned int stop:1;
 223         /*! Bit to indicate the bridge thread should refresh itself */
 224         unsigned int refresh:1;
 225         /*! Bridge flags to tweak behavior */
 226         struct ast_flags feature_flags;
 227         /*! Bridge technology that is handling the bridge */
 228         struct ast_bridge_technology *technology;
 229         /*! Private information unique to the bridge technology */
 230         void *bridge_pvt;
 231         /*! Thread running the bridge */
 232         pthread_t thread;
 233         /*! Enabled features information */
 234         struct ast_bridge_features features;
 235         /*! Array of channels that the bridge thread is currently handling */
 236         struct ast_channel **array;
 237         /*! Number of channels in the above array */
 238         size_t array_num;
 239         /*! Number of channels the array can handle */
 240         size_t array_size;
 241         /*! Linked list of channels participating in the bridge */
 242         AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
 243 };
 244
 245 /*! \brief Create a new bridge
 246  *
 247  * \param capabilities The capabilities that we require to be used on the bridge
 248  * \param flags Flags that will alter the behavior of the bridge
 249  *
 250  * \retval a pointer to a new bridge on success
 251  * \retval NULL on failure
 252  *
 253  * Example usage:
 254  *
 255  * \code
 256  * struct ast_bridge *bridge;
 257  * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE);
 258  * \endcode
 259  *
 260  * This creates a simple two party bridge that will be destroyed once one of
 261  * the channels hangs up.
 262  */
 263 struct ast_bridge *ast_bridge_new(uint32_t capabilities, int flags);
 264
 265 /*! \brief See if it is possible to create a bridge
 266  *
 267  * \param capabilities The capabilities that the bridge will use
 268  *
 269  * \retval 1 if possible
 270  * \retval 0 if not possible
 271  *
 272  * Example usage:
 273  *
 274  * \code
 275  * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX);
 276  * \endcode
 277  *
 278  * This sees if it is possible to create a bridge capable of bridging two channels
 279  * together.
 280  */
 281 int ast_bridge_check(uint32_t capabilities);
 282
 283 /*! \brief Destroy a bridge
 284  *
 285  * \param bridge Bridge to destroy
 286  *
 287  * \retval 0 on success
 288  * \retval -1 on failure
 289  *
 290  * Example usage:
 291  *
 292  * \code
 293  * ast_bridge_destroy(bridge);
 294  * \endcode
 295  *
 296  * This destroys a bridge that was previously created using ast_bridge_new.
 297  */
 298 int ast_bridge_destroy(struct ast_bridge *bridge);
 299
 300 /*! \brief Join (blocking) a channel to a bridge
 301  *
 302  * \param bridge Bridge to join
 303  * \param chan Channel to join
 304  * \param swap Channel to swap out if swapping
 305  * \param features Bridge features structure
 306  * \param (Optional) Bridging tech optimization parameters for this channel.
 307  *
 308  * \retval state that channel exited the bridge with
 309  *
 310  * Example usage:
 311  *
 312  * \code
 313  * ast_bridge_join(bridge, chan, NULL, NULL);
 314  * \endcode
 315  *
 316  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
 317  * the bridge pointer. This function will not return until the channel has been
 318  * removed from the bridge, swapped out for another channel, or has hung up.
 319  *
 320  * If this channel will be replacing another channel the other channel can be specified
 321  * in the swap parameter. The other channel will be thrown out of the bridge in an
 322  * atomic fashion.
 323  *
 324  * If channel specific features are enabled a pointer to the features structure
 325  * can be specified in the features parameter.
 326  */
 327 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
 328         struct ast_channel *chan,
 329         struct ast_channel *swap,
 330         struct ast_bridge_features *features,
 331         struct ast_bridge_tech_optimizations *tech_args);
 332
 333 /*! \brief Impart (non-blocking) a channel on a bridge
 334  *
 335  * \param bridge Bridge to impart on
 336  * \param chan Channel to impart
 337  * \param swap Channel to swap out if swapping
 338  * \param features Bridge features structure
 339  *
 340  * \retval 0 on success
 341  * \retval -1 on failure
 342  *
 343  * Example usage:
 344  *
 345  * \code
 346  * ast_bridge_impart(bridge, chan, NULL, NULL);
 347  * \endcode
 348  *
 349  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
 350  * the bridge pointer. This function will return immediately and will not wait
 351  * until the channel is no longer part of the bridge.
 352  *
 353  * If this channel will be replacing another channel the other channel can be specified
 354  * in the swap parameter. The other channel will be thrown out of the bridge in an
 355  * atomic fashion.
 356  *
 357  * If channel specific features are enabled a pointer to the features structure
 358  * can be specified in the features parameter.
 359  */
 360 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features);
 361
 362 /*! \brief Depart a channel from a bridge
 363  *
 364  * \param bridge Bridge to depart from
 365  * \param chan Channel to depart
 366  *
 367  * \retval 0 on success
 368  * \retval -1 on failure
 369  *
 370  * Example usage:
 371  *
 372  * \code
 373  * ast_bridge_depart(bridge, chan);
 374  * \endcode
 375  *
 376  * This removes the channel pointed to by the chan pointer from the bridge
 377  * pointed to by the bridge pointer and gives control to the calling thread.
 378  * This does not hang up the channel.
 379  *
 380  * \note This API call can only be used on channels that were added to the bridge
 381  *       using the ast_bridge_impart API call.
 382  */
 383 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
 384
 385 /*! \brief Remove a channel from a bridge
 386  *
 387  * \param bridge Bridge that the channel is to be removed from
 388  * \param chan Channel to remove
 389  *
 390  * \retval 0 on success
 391  * \retval -1 on failure
 392  *
 393  * Example usage:
 394  *
 395  * \code
 396  * ast_bridge_remove(bridge, chan);
 397  * \endcode
 398  *
 399  * This removes the channel pointed to by the chan pointer from the bridge
 400  * pointed to by the bridge pointer and requests that it be hung up. Control
 401  * over the channel will NOT be given to the calling thread.
 402  *
 403  * \note This API call can be used on channels that were added to the bridge
 404  *       using both ast_bridge_join and ast_bridge_impart.
 405  */
 406 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
 407
 408 /*! \brief Merge two bridges together
 409  *
 410  * \param bridge0 First bridge
 411  * \param bridge1 Second bridge
 412  *
 413  * \retval 0 on success
 414  * \retval -1 on failure
 415  *
 416  * Example usage:
 417  *
 418  * \code
 419  * ast_bridge_merge(bridge0, bridge1);
 420  * \endcode
 421  *
 422  * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0.
 423  * In reality all of the channels in bridge1 are simply moved to bridge0.
 424  *
 425  * \note The second bridge specified is not destroyed when this operation is
 426  *       completed.
 427  */
 428 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
 429
 430 /*! \brief Suspend a channel temporarily from a bridge
 431  *
 432  * \param bridge Bridge to suspend the channel from
 433  * \param chan Channel to suspend
 434  *
 435  * \retval 0 on success
 436  * \retval -1 on failure
 437  *
 438  * Example usage:
 439  *
 440  * \code
 441  * ast_bridge_suspend(bridge, chan);
 442  * \endcode
 443  *
 444  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
 445  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
 446  * the channel will not be removed from the bridge.
 447  *
 448  * \note This API call can be used on channels that were added to the bridge
 449  *       using both ast_bridge_join and ast_bridge_impart.
 450  */
 451 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
 452
 453 /*! \brief Unsuspend a channel from a bridge
 454  *
 455  * \param bridge Bridge to unsuspend the channel from
 456  * \param chan Channel to unsuspend
 457  *
 458  * \retval 0 on success
 459  * \retval -1 on failure
 460  *
 461  * Example usage:
 462  *
 463  * \code
 464  * ast_bridge_unsuspend(bridge, chan);
 465  * \endcode
 466  *
 467  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
 468  * The bridge will go back to handling the channel once this function returns.
 469  *
 470  * \note You must not mess with the channel once this function returns.
 471  *       Doing so may result in bad things happening.
 472  */
 473 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
 474
 475 /*! \brief Change the state of a bridged channel
 476  *
 477  * \param bridge_channel Channel to change the state on
 478  * \param new_state The new state to place the channel into
 479  *
 480  * Example usage:
 481  *
 482  * \code
 483  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT);
 484  * \endcode
 485  *
 486  * This places the channel pointed to by bridge_channel into the state
 487  * AST_BRIDGE_CHANNEL_STATE_WAIT.
 488  *
 489  * \note This API call is only meant to be used in feature hook callbacks to
 490  *       make sure the channel either hangs up or returns to the bridge.
 491  */
 492 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
 493
 494 /*! \brief Adjust the internal mixing sample rate of a bridge used during
 495  *         multimix mode.
 496  *
 497  * \param bridge_channel Channel to change the sample rate on.
 498  * \param sample rate, the sample rate to change to. If a
 499  *        value of 0 is passed here, the bridge will be free to pick
 500  *        what ever sample rate it chooses.
 501  *
 502  */
 503 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
 504
 505 /*! \brief Adjust the internal mixing interval of a bridge used during
 506  *         multimix mode.
 507  *
 508  * \param bridge_channel Channel to change the sample rate on.
 509  * \param mixing_interval, the sample rate to change to.  If 0 is set
 510  * the bridge tech is free to choose any mixing interval it uses by default.
 511  */
 512 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
 513
 514 /*!
 515  * \brief Set a bridge to feed a single video source to all participants.
 516  */
 517 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
 518
 519 /*!
 520  * \brief Set the bridge to pick the strongest talker supporting
 521  * video as the single source video feed
 522  */
 523 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
 524
 525 /*!
 526  * \brief Update information about talker energy for talker src video mode.
 527  */
 528 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
 529
 530 /*!
 531  * \brief Determine if a channel is a video src for the bridge
 532  */
 533 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
 534
 535 /*!
 536  * \brief remove a channel as a source of video for the bridge.
 537  */
 538 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
 539
 540 #if defined(__cplusplus) || defined(c_plusplus)
 541 }
 542 #endif
 543
 544 #endif /* _ASTERISK_BRIDGING_H */