app_confbridge / bridge_softmix: Add ability to configure REMB interval.
[asterisk/asterisk.git] / 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         /*! Operate as a selective forwarding unit. Video from each participant is
106          * cloned to a dedicated stream on a subset of the remaining participants.
107          */
108         AST_BRIDGE_VIDEO_MODE_SFU,
109 };
110
111 /*! \brief This is used for both SINGLE_SRC mode to set what channel
112  *  should be the current single video feed */
113 struct ast_bridge_video_single_src_data {
114         /*! Only accept video coming from this channel */
115         struct ast_channel *chan_vsrc;
116 };
117
118 /*! \brief This is used for both SINGLE_SRC_TALKER mode to set what channel
119  *  should be the current single video feed */
120 struct ast_bridge_video_talker_src_data {
121         /*! Only accept video coming from this channel */
122         struct ast_channel *chan_vsrc;
123         int average_talking_energy;
124
125         /*! Current talker see's this person */
126         struct ast_channel *chan_old_vsrc;
127 };
128
129 /*! \brief Data structure that defines a video source mode */
130 struct ast_bridge_video_mode {
131         enum ast_bridge_video_mode_type mode;
132         /* Add data for all the video modes here. */
133         union {
134                 struct ast_bridge_video_single_src_data single_src_data;
135                 struct ast_bridge_video_talker_src_data talker_src_data;
136         } mode_data;
137         unsigned int video_update_discard;
138         unsigned int remb_send_interval;
139 };
140
141 /*!
142  * \brief Destroy the bridge.
143  *
144  * \param self Bridge to operate upon.
145  *
146  * \return Nothing
147  */
148 typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
149
150 /*!
151  * \brief The bridge is being dissolved.
152  *
153  * \param self Bridge to operate upon.
154  *
155  * \details
156  * The bridge is being dissolved.  Remove any external
157  * references to the bridge so it can be destroyed.
158  *
159  * \note On entry, self must NOT be locked.
160  *
161  * \return Nothing
162  */
163 typedef void (*ast_bridge_dissolving_fn)(struct ast_bridge *self);
164
165 /*!
166  * \brief Push this channel into the bridge.
167  *
168  * \param self Bridge to operate upon.
169  * \param bridge_channel Bridge channel to push.
170  * \param swap Bridge channel to swap places with if not NULL.
171  *
172  * \details
173  * Setup any channel hooks controlled by the bridge.  Allocate
174  * bridge_channel->bridge_pvt and initialize any resources put
175  * in bridge_channel->bridge_pvt if needed.  If there is a swap
176  * channel, use it as a guide to setting up the bridge_channel.
177  *
178  * \note On entry, self is already locked.
179  *
180  * \retval 0 on success.
181  * \retval -1 on failure.  The channel did not get pushed.
182  */
183 typedef int (*ast_bridge_push_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
184
185 /*!
186  * \brief Pull this channel from the bridge.
187  *
188  * \param self Bridge to operate upon.
189  * \param bridge_channel Bridge channel to pull.
190  *
191  * \details
192  * Remove any channel hooks controlled by the bridge.  Release
193  * any resources held by bridge_channel->bridge_pvt and release
194  * bridge_channel->bridge_pvt.
195  *
196  * \note On entry, self is already locked.
197  *
198  * \return Nothing
199  */
200 typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
201
202 /*!
203  * \brief Notify the bridge that this channel was just masqueraded.
204  *
205  * \param self Bridge to operate upon.
206  * \param bridge_channel Bridge channel that was masqueraded.
207  *
208  * \details
209  * A masquerade just happened to this channel.  The bridge needs
210  * to re-evaluate this a channel in the bridge.
211  *
212  * \note On entry, self is already locked.
213  *
214  * \return Nothing
215  */
216 typedef void (*ast_bridge_notify_masquerade_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
217
218 /*!
219  * \brief Get the merge priority of this bridge.
220  *
221  * \param self Bridge to operate upon.
222  *
223  * \note On entry, self is already locked.
224  *
225  * \return Merge priority
226  */
227 typedef int (*ast_bridge_merge_priority_fn)(struct ast_bridge *self);
228
229 /*!
230  * \brief Bridge virtual methods table definition.
231  *
232  * \note Any changes to this struct must be reflected in
233  * bridge_alloc() validity checking.
234  */
235 struct ast_bridge_methods {
236         /*! Bridge class name for log messages. */
237         const char *name;
238         /*! Destroy the bridge. */
239         ast_bridge_destructor_fn destroy;
240         /*! The bridge is being dissolved.  Remove any references to the bridge. */
241         ast_bridge_dissolving_fn dissolving;
242         /*! Push the bridge channel into the bridge. */
243         ast_bridge_push_channel_fn push;
244         /*! Pull the bridge channel from the bridge. */
245         ast_bridge_pull_channel_fn pull;
246         /*! Notify the bridge of a masquerade with the channel. */
247         ast_bridge_notify_masquerade_fn notify_masquerade;
248         /*! Get the bridge merge priority. */
249         ast_bridge_merge_priority_fn get_merge_priority;
250         /*! Peek at swap channel before it can hang up, prior to push. */
251         ast_bridge_push_channel_fn push_peek;
252 };
253
254 /*! Softmix technology parameters. */
255 struct ast_bridge_softmix {
256         /*! The video mode softmix is using */
257         struct ast_bridge_video_mode video_mode;
258         /*!
259          * \brief The internal sample rate softmix uses to mix channels.
260          *
261          * \note If this value is 0, the sofmix may auto adjust the mixing rate.
262          */
263         unsigned int internal_sample_rate;
264         /*!
265          * \brief The mixing interval indicates how quickly softmix
266          * mixing should occur to mix audio.
267          *
268          * \note When set to 0, softmix must choose a default interval
269          * for itself.
270          */
271         unsigned int internal_mixing_interval;
272         /*! TRUE if binaural convolve is activated in configuration. */
273         unsigned int binaural_active;
274 };
275
276 AST_LIST_HEAD_NOLOCK(ast_bridge_channels_list, ast_bridge_channel);
277
278 /*!
279  * \brief Structure that contains information about a bridge
280  */
281 struct ast_bridge {
282         /*! Bridge virtual method table. */
283         const struct ast_bridge_methods *v_table;
284         /*! "Personality" currently exhibited by bridge subclass */
285         void *personality;
286         /*! Bridge technology that is handling the bridge */
287         struct ast_bridge_technology *technology;
288         /*! Private information unique to the bridge technology */
289         void *tech_pvt;
290         /*! Per-bridge topics */
291         struct stasis_cp_single *topics;
292         /*! Call ID associated with the bridge */
293         ast_callid callid;
294         /*! Linked list of channels participating in the bridge */
295         struct ast_bridge_channels_list channels;
296         /*! Queue of actions to perform on the bridge. */
297         AST_LIST_HEAD_NOLOCK(, ast_frame) action_queue;
298         /*! Softmix technology parameters. */
299         struct ast_bridge_softmix softmix;
300         /*! Bridge flags to tweak behavior */
301         struct ast_flags feature_flags;
302         /*! Allowed bridge technology capabilities when AST_BRIDGE_FLAG_SMART enabled. */
303         uint32_t allowed_capabilities;
304         /*! Number of channels participating in the bridge */
305         unsigned int num_channels;
306         /*! Number of active channels in the bridge. */
307         unsigned int num_active;
308         /*! Number of channels with AST_BRIDGE_CHANNEL_FLAG_LONELY in the bridge. */
309         unsigned int num_lonely;
310         /*!
311          * \brief Count of the active temporary requests to inhibit bridge merges.
312          * Zero if merges are allowed.
313          *
314          * \note Temporary as in try again in a moment.
315          */
316         unsigned int inhibit_merge;
317         /*! Cause code of the dissolved bridge. */
318         int cause;
319         /*! TRUE if the bridge was reconfigured. */
320         unsigned int reconfigured:1;
321         /*! TRUE if the bridge has been dissolved.  Any channel that now tries to join is immediately ejected. */
322         unsigned int dissolved:1;
323         /*! TRUE if the bridge construction was completed. */
324         unsigned int construction_completed:1;
325
326         AST_DECLARE_STRING_FIELDS(
327                 /*! Immutable name of the creator for the bridge */
328                 AST_STRING_FIELD(creator);
329                 /*! Immutable name given to the bridge by its creator */
330                 AST_STRING_FIELD(name);
331                 /*! Immutable bridge UUID. */
332                 AST_STRING_FIELD(uniqueid);
333         );
334
335         /*! Type mapping used for media routing */
336         struct ast_vector_int media_types;
337 };
338
339 /*! \brief Bridge base class virtual method table. */
340 extern struct ast_bridge_methods ast_bridge_base_v_table;
341
342 /*!
343  * \brief Create a new base class bridge
344  *
345  * \param capabilities The capabilities that we require to be used on the bridge
346  * \param flags Flags that will alter the behavior of the bridge
347  * \param creator Entity that created the bridge (optional)
348  * \param name Name given to the bridge by its creator (optional, requires named creator)
349  * \param id Unique ID given to the bridge by its creator (optional)
350  *
351  * \retval a pointer to a new bridge on success
352  * \retval NULL on failure
353  *
354  * Example usage:
355  *
356  * \code
357  * struct ast_bridge *bridge;
358  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
359  * \endcode
360  *
361  * This creates a no frills two party bridge that will be
362  * destroyed once one of the channels hangs up.
363  */
364 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
365
366 /*!
367  * \brief Try locking the bridge.
368  *
369  * \param bridge Bridge to try locking
370  *
371  * \retval 0 on success.
372  * \retval non-zero on error.
373  */
374 #define ast_bridge_trylock(bridge)      _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
375 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
376 {
377         return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
378 }
379
380 /*!
381  * \brief Lock the bridge.
382  *
383  * \param bridge Bridge to lock
384  *
385  * \return Nothing
386  */
387 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
388 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
389 {
390         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
391 }
392
393 /*!
394  * \brief Unlock the bridge.
395  *
396  * \param bridge Bridge to unlock
397  *
398  * \return Nothing
399  */
400 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
401 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
402 {
403         __ao2_unlock(bridge, file, function, line, var);
404 }
405
406 /*! \brief Lock two bridges. */
407 #define ast_bridge_lock_both(bridge1, bridge2)          \
408         do {                                                                                    \
409                 for (;;) {                                                                      \
410                         ast_bridge_lock(bridge1);                               \
411                         if (!ast_bridge_trylock(bridge2)) {             \
412                                 break;                                                          \
413                         }                                                                               \
414                         ast_bridge_unlock(bridge1);                             \
415                         sched_yield();                                                  \
416                 }                                                                                       \
417         } while (0)
418
419 /*!
420  * \brief Destroy a bridge
421  *
422  * \param bridge Bridge to destroy
423  * \param cause Cause of bridge being destroyed.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
424  *
425  * \retval 0 on success
426  * \retval -1 on failure
427  *
428  * Example usage:
429  *
430  * \code
431  * ast_bridge_destroy(bridge, AST_CAUSE_NORMAL_CLEARING);
432  * \endcode
433  *
434  * This destroys a bridge that was previously created.
435  *
436  * \note
437  * While this function will kick all channels out of the bridge, channels that
438  * were added to the bridge using ast_bridge_impart() with the flag
439  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE set must have ast_bridge_depart() called
440  * on them.
441  */
442 int ast_bridge_destroy(struct ast_bridge *bridge, int cause);
443
444 /*!
445  * \brief Notify bridging that this channel was just masqueraded.
446  * \since 12.0.0
447  *
448  * \param chan Channel just involved in a masquerade
449  *
450  * \return Nothing
451  */
452 void ast_bridge_notify_masquerade(struct ast_channel *chan);
453
454 enum ast_bridge_join_flags {
455         /*! The bridge reference is being passed by the caller. */
456         AST_BRIDGE_JOIN_PASS_REFERENCE = (1 << 0),
457         /*! The initial bridge join does not cause a COLP exchange. */
458         AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP = (1 << 1),
459 };
460
461 /*!
462  * \brief Join a channel to a bridge (blocking)
463  *
464  * \param bridge Bridge to join
465  * \param chan Channel to join
466  * \param swap Channel to swap out if swapping (A channel reference is stolen.)
467  * \param features Bridge features structure
468  * \param tech_args Optional Bridging tech optimization parameters for this channel.
469  * \param flags defined by enum ast_bridge_join_flags.
470  *
471  * \note The passed in swap channel is always unreffed on return.  It is not a
472  * good idea to access the swap channel on return or for the caller to keep a
473  * reference to it.
474  *
475  * \note Absolutely _NO_ locks should be held before calling
476  * this function since it blocks.
477  *
478  * \retval 0 if the channel successfully joined the bridge before it exited.
479  * \retval -1 if the channel failed to join the bridge
480  *
481  * Example usage:
482  *
483  * \code
484  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, AST_BRIDGE_JOIN_PASS_REFERENCE);
485  * \endcode
486  *
487  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
488  * the bridge pointer. This function will not return until the channel has been
489  * removed from the bridge, swapped out for another channel, or has hung up.
490  *
491  * If this channel will be replacing another channel the other channel can be specified
492  * in the swap parameter. The other channel will be thrown out of the bridge in an
493  * atomic fashion.
494  *
495  * If channel specific features are enabled a pointer to the features structure
496  * can be specified in the features parameter.
497  */
498 int ast_bridge_join(struct ast_bridge *bridge,
499         struct ast_channel *chan,
500         struct ast_channel *swap,
501         struct ast_bridge_features *features,
502         struct ast_bridge_tech_optimizations *tech_args,
503         enum ast_bridge_join_flags flags);
504
505 enum ast_bridge_impart_flags {
506         /*! Field describing what the caller can do with the channel after it is imparted. */
507         AST_BRIDGE_IMPART_CHAN_MASK = (1 << 0),
508         /*! The caller wants to reclaim the channel using ast_bridge_depart(). */
509         AST_BRIDGE_IMPART_CHAN_DEPARTABLE = (0 << 0),
510         /*! The caller is passing channel control entirely to the bridging system. */
511         AST_BRIDGE_IMPART_CHAN_INDEPENDENT = (1 << 0),
512         /*! The initial bridge join does not cause a COLP exchange. */
513         AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP = (1 << 1),
514 };
515
516 /*!
517  * \brief Impart a channel to a bridge (non-blocking)
518  *
519  * \param bridge Bridge to impart on
520  * \param chan Channel to impart (The channel reference is stolen if impart successful.)
521  * \param swap Channel to swap out if swapping.  NULL if not swapping.
522  * \param features Bridge features structure.
523  * \param flags defined by enum ast_bridge_impart_flags.
524  *
525  * \note The given bridge must be unlocked when calling this function.
526  *
527  * \note The features parameter must be NULL or obtained by
528  * ast_bridge_features_new().  You must not dereference features
529  * after calling even if the call fails.
530  *
531  * \note chan is locked by this function.
532  *
533  * \retval 0 on success
534  * \retval -1 on failure (Caller still has ownership of chan)
535  *
536  * Example usage:
537  *
538  * \code
539  * ast_bridge_impart(bridge, chan, NULL, NULL, AST_BRIDGE_IMPART_CHAN_INDEPENDENT);
540  * \endcode
541  *
542  * \details
543  * This adds a channel pointed to by the chan pointer to the
544  * bridge pointed to by the bridge pointer.  This function will
545  * return immediately and will not wait until the channel is no
546  * longer part of the bridge.
547  *
548  * If this channel will be replacing another channel the other
549  * channel can be specified in the swap parameter.  The other
550  * channel will be thrown out of the bridge in an atomic
551  * fashion.
552  *
553  * If channel specific features are enabled, a pointer to the
554  * features structure can be specified in the features
555  * parameter.
556  *
557  * \note If you impart a channel with
558  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE you MUST
559  * ast_bridge_depart() the channel if this call succeeds.  The
560  * bridge channel thread is created join-able.  The implication
561  * is that the channel is special and will not behave like a
562  * normal channel.
563  *
564  * \note If you impart a channel with
565  * AST_BRIDGE_IMPART_CHAN_INDEPENDENT you must not
566  * ast_bridge_depart() the channel.  The bridge channel thread
567  * is created non-join-able.  The channel must be treated as if
568  * it were placed into the bridge by ast_bridge_join().
569  * Channels placed into a bridge by ast_bridge_join() are
570  * removed by a third party using ast_bridge_remove().
571  */
572 int ast_bridge_impart(struct ast_bridge *bridge,
573         struct ast_channel *chan,
574         struct ast_channel *swap,
575         struct ast_bridge_features *features,
576         enum ast_bridge_impart_flags flags) attribute_warn_unused_result;
577
578 /*!
579  * \brief Depart a channel from a bridge
580  *
581  * \param chan Channel to depart
582  *
583  * \note chan is locked by this function.
584  *
585  * \retval 0 on success
586  * \retval -1 on failure
587  *
588  * Example usage:
589  *
590  * \code
591  * ast_bridge_depart(chan);
592  * \endcode
593  *
594  * This removes the channel pointed to by the chan pointer from any bridge
595  * it may be in and gives control to the calling thread.
596  * This does not hang up the channel.
597  *
598  * \note This API call can only be used on channels that were added to the bridge
599  *       using the ast_bridge_impart API call with the AST_BRIDGE_IMPART_CHAN_DEPARTABLE
600  *       flag.
601  */
602 int ast_bridge_depart(struct ast_channel *chan);
603
604 /*!
605  * \brief Remove a channel from a bridge
606  *
607  * \param bridge Bridge that the channel is to be removed from
608  * \param chan Channel to remove
609  *
610  * \retval 0 on success
611  * \retval -1 on failure
612  *
613  * Example usage:
614  *
615  * \code
616  * ast_bridge_remove(bridge, chan);
617  * \endcode
618  *
619  * This removes the channel pointed to by the chan pointer from the bridge
620  * pointed to by the bridge pointer and requests that it be hung up. Control
621  * over the channel will NOT be given to the calling thread.
622  *
623  * \note This API call can be used on channels that were added to the bridge
624  *       using both ast_bridge_join and ast_bridge_impart.
625  */
626 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
627
628 /*!
629  * \brief Kick a channel from a bridge
630  *
631  * \param bridge Bridge that the channel is to be kicked from
632  * \param chan Channel to kick
633  *
634  * \retval 0 on success
635  * \retval -1 on failure
636  *
637  * Example usage:
638  *
639  * \code
640  * ast_bridge_kick(bridge, chan);
641  * \endcode
642  *
643  * \details
644  * This kicks the channel pointed to by the chan pointer from
645  * the bridge pointed to by the bridge pointer and requests that
646  * it be hung up.  Control over the channel will NOT be given to
647  * the calling thread.
648  *
649  * \note The functional difference between ast_bridge_kick() and
650  * ast_bridge_remove() is that the bridge may dissolve as a
651  * result of the channel being kicked.
652  *
653  * \note This API call can be used on channels that were added
654  * to the bridge using both ast_bridge_join and
655  * ast_bridge_impart.
656  */
657 int ast_bridge_kick(struct ast_bridge *bridge, struct ast_channel *chan);
658
659 /*!
660  * \brief Merge two bridges together
661  *
662  * \param dst_bridge Destination bridge of merge.
663  * \param src_bridge Source bridge of merge.
664  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
665  * \param kick_me Array of channels to kick from the bridges.
666  * \param num_kick Number of channels in the kick_me array.
667  *
668  * \note Absolutely _NO_ bridge or channel locks should be held
669  * before calling this function.
670  *
671  * \retval 0 on success
672  * \retval -1 on failure
673  *
674  * Example usage:
675  *
676  * \code
677  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
678  * \endcode
679  *
680  * This moves the channels in src_bridge into the bridge pointed
681  * to by dst_bridge.
682  */
683 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);
684
685 /*!
686  * \brief Move a channel from one bridge to another.
687  * \since 12.0.0
688  *
689  * \param dst_bridge Destination bridge of bridge channel move.
690  * \param src_bridge Source bridge of bridge channel move.
691  * \param chan Channel to move.
692  * \param swap Channel to replace in dst_bridge.
693  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
694  *
695  * \note Absolutely _NO_ bridge or channel locks should be held
696  * before calling this function.
697  *
698  * \retval 0 on success.
699  * \retval -1 on failure.
700  */
701 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);
702
703 /*!
704  * \brief Adjust the bridge merge inhibit request count.
705  * \since 12.0.0
706  *
707  * \param bridge What to operate on.
708  * \param request Inhibit request increment.
709  *     (Positive to add requests.  Negative to remove requests.)
710  *
711  * \return Nothing
712  */
713 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
714
715 /*!
716  * \brief Suspend a channel temporarily from a bridge
717  *
718  * \param bridge Bridge to suspend the channel from
719  * \param chan Channel to suspend
720  *
721  * \retval 0 on success
722  * \retval -1 on failure
723  *
724  * Example usage:
725  *
726  * \code
727  * ast_bridge_suspend(bridge, chan);
728  * \endcode
729  *
730  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
731  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
732  * the channel will not be removed from the bridge.
733  *
734  * \note This API call can be used on channels that were added to the bridge
735  *       using both ast_bridge_join and ast_bridge_impart.
736  */
737 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
738
739 /*!
740  * \brief Unsuspend a channel from a bridge
741  *
742  * \param bridge Bridge to unsuspend the channel from
743  * \param chan Channel to unsuspend
744  *
745  * \retval 0 on success
746  * \retval -1 on failure
747  *
748  * Example usage:
749  *
750  * \code
751  * ast_bridge_unsuspend(bridge, chan);
752  * \endcode
753  *
754  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
755  * The bridge will go back to handling the channel once this function returns.
756  *
757  * \note You must not mess with the channel once this function returns.
758  *       Doing so may result in bad things happening.
759  */
760 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
761
762 /*!
763  * \brief Sets BRIDGECHANNEL and BRIDGEPVTCALLID for a channel
764  *
765  * \pre chan must be locked before calling
766  *
767  * \param name channel name of the bridged peer
768  * \param pvtid Private CallID of the bridged peer
769  *
770  * \return nothing
771  */
772 void ast_bridge_vars_set(struct ast_channel *chan, const char *name, const char *pvtid);
773
774 struct ast_unreal_pvt;
775
776 /*!
777  * \brief Check and optimize out the unreal channels between bridges.
778  * \since 12.0.0
779  *
780  * \param chan Unreal channel writing a frame into the channel driver.
781  * \param peer Other unreal channel in the pair.
782  * \param pvt Private data provided by an implementation of the unreal driver that
783  * contains the callbacks that should be called when optimization begins/ends
784  *
785  * \note It is assumed that chan is already locked.
786  *
787  * \retval 0 if unreal channels were not optimized out.
788  * \retval non-zero if unreal channels were optimized out.
789  */
790 int ast_bridge_unreal_optimize_out(struct ast_channel *chan, struct ast_channel *peer, struct ast_unreal_pvt *pvt);
791
792 /*!
793  * \brief Tells, if optimization is allowed, how the optimization would be performed
794  */
795 enum ast_bridge_optimization {
796         /*! Optimization would swap peer into the chan_bridge */
797         AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
798         /*! Optimization would swap chan into the peer_bridge */
799         AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
800         /*! Optimization would merge peer_bridge into chan_bridge */
801         AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
802         /*! Optimization would merge chan_bridge into peer_bridge */
803         AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
804         /*! Optimization is not permitted on one or both bridges */
805         AST_BRIDGE_OPTIMIZE_PROHIBITED,
806 };
807
808 /*!
809  * \brief Determine if bridges allow for optimization to occur betweem them
810  * \since 12.0.0
811  *
812  * \param chan_bridge First bridge being tested
813  * \param peer_bridge Second bridge being tested
814  *
815  * This determines if two bridges allow for unreal channel optimization
816  * to occur between them. The function does not require for unreal channels
817  * to already be in the bridges when called.
818  *
819  * \note It is assumed that both bridges are locked prior to calling this function
820  *
821  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
822  * that an optimization attempt will succeed. However, a return of
823  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
824  * never succeed.
825  *
826  * \returns Optimization allowability for the bridges
827  */
828 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
829                 struct ast_bridge *peer_bridge);
830
831 /*!
832  * \brief Put an action onto the specified bridge.
833  * \since 12.0.0
834  *
835  * \param bridge What to queue the action on.
836  * \param action What to do.
837  *
838  * \retval 0 on success.
839  * \retval -1 on error.
840  *
841  * \note This API call is meant for internal bridging operations.
842  */
843 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
844
845 /*!
846  * \brief Queue the given frame to everyone else.
847  * \since 12.0.0
848  *
849  * \param bridge What bridge to distribute frame.
850  * \param bridge_channel Channel to optionally not pass frame to. (NULL to pass to everyone)
851  * \param frame Frame to pass.
852  *
853  * \note This is intended to be called by bridge hooks and
854  * bridge technologies.
855  *
856  * \retval 0 Frame written to at least one channel.
857  * \retval -1 Frame written to no channels.
858  */
859 int ast_bridge_queue_everyone_else(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
860
861 /*!
862  * \brief Adjust the internal mixing sample rate of a bridge
863  * used during multimix mode.
864  *
865  * \param bridge Channel to change the sample rate on.
866  * \param sample_rate the sample rate to change to. If a
867  *        value of 0 is passed here, the bridge will be free to pick
868  *        what ever sample rate it chooses.
869  *
870  */
871 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
872
873 /*!
874  * \brief Adjust the internal mixing interval of a bridge used
875  * during multimix mode.
876  *
877  * \param bridge Channel to change the sample rate on.
878  * \param mixing_interval the sample rate to change to.  If 0 is set
879  * the bridge tech is free to choose any mixing interval it uses by default.
880  */
881 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
882
883 /*!
884  * \brief Activates the use of binaural signals in a conference bridge.
885  *
886  *  \param bridge Channel to activate the binaural signals.
887  *  \param binaural_active If true binaural signal processing will be active for the bridge.
888  */
889 void ast_bridge_set_binaural_active(struct ast_bridge *bridge, unsigned int binaural_active);
890
891 /*!
892  * \brief Set a bridge to feed a single video source to all participants.
893  */
894 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
895
896 /*!
897  * \brief Set the bridge to pick the strongest talker supporting
898  * video as the single source video feed
899  */
900 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
901
902 /*!
903  * \brief Set the bridge to be a selective forwarding unit
904  */
905 void ast_bridge_set_sfu_video_mode(struct ast_bridge *bridge);
906
907 /*!
908  * \brief Set the amount of time to discard subsequent video updates after a video update has been sent
909  *
910  * \param bridge Bridge to set the minimum video update wait time on
911  * \param video_update_discard Amount of time after sending a video update that others should be discarded
912  */
913 void ast_bridge_set_video_update_discard(struct ast_bridge *bridge, unsigned int video_update_discard);
914
915 /*!
916  * \brief Set the interval at which a combined REMB frame will be sent to video sources
917  *
918  * \param bridge Bridge to set the REMB send interval on
919  * \param remb_send_interval The REMB send interval
920  */
921 void ast_bridge_set_remb_send_interval(struct ast_bridge *bridge, unsigned int remb_send_interval);
922
923 /*!
924  * \brief Update information about talker energy for talker src video mode.
925  */
926 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
927
928 /*!
929  * \brief Returns the number of video sources currently active in the bridge
930  */
931 int ast_bridge_number_video_src(struct ast_bridge *bridge);
932
933 /*!
934  * \brief Determine if a channel is a video src for the bridge
935  *
936  * \retval 0 Not a current video source of the bridge.
937  * \retval None 0, is a video source of the bridge, The number
938  *         returned represents the priority this video stream has
939  *         on the bridge where 1 is the highest priority.
940  */
941 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
942
943 /*!
944  * \brief remove a channel as a source of video for the bridge.
945  */
946 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
947
948 /*!
949  * \brief Converts an enum representation of a bridge video mode to string
950  *
951  * \param video_mode The video mode
952  *
953  * \retval A string representation of \c video_mode
954  */
955 const char *ast_bridge_video_mode_to_string(enum ast_bridge_video_mode_type video_mode);
956
957 enum ast_transfer_result {
958         /*! The transfer completed successfully */
959         AST_BRIDGE_TRANSFER_SUCCESS,
960         /*! A bridge involved does not permit transferring */
961         AST_BRIDGE_TRANSFER_NOT_PERMITTED,
962         /*! The current bridge setup makes transferring an invalid operation */
963         AST_BRIDGE_TRANSFER_INVALID,
964         /*! The transfer operation failed for a miscellaneous reason */
965         AST_BRIDGE_TRANSFER_FAIL,
966 };
967
968 enum ast_transfer_type {
969         /*! Transfer of a single party */
970         AST_BRIDGE_TRANSFER_SINGLE_PARTY,
971         /*! Transfer of multiple parties */
972         AST_BRIDGE_TRANSFER_MULTI_PARTY,
973 };
974
975 /*!
976  * \brief AO2 object that wraps data for transfer_channel_cb
977  */
978 struct transfer_channel_data {
979         void *data;    /*! Data to be used by the transfer_channel_cb -- note that this
980                         *  pointer is going to be pointing to something on the stack, so
981                         *  it must not be used at any point after returning from the
982                         *  transfer_channel_cb. */
983         int completed; /*! Initially 0, This will be set to 1 by either the transfer
984                         *  code or by transfer code hooks (e.g. parking) when the
985                         *  transfer is completed and any remaining actions have taken
986                         *  place (e.g. parking announcements). It will never be reset
987                         *  to 0. This is used for deferring progress for channel
988                         *  drivers that support deferred progress. */
989 };
990
991 /*!
992  * \brief Callback function type called during blind transfers
993  *
994  * A caller of ast_bridge_transfer_blind() may wish to set data on
995  * the channel that ends up running dialplan. For instance, it may
996  * be useful to set channel variables on the channel.
997  *
998  * \param chan The involved channel
999  * \param user_data User-provided data needed in the callback
1000  * \param transfer_type The type of transfer being completed
1001  */
1002 typedef void (*transfer_channel_cb)(struct ast_channel *chan, struct transfer_channel_data *user_data,
1003                 enum ast_transfer_type transfer_type);
1004
1005 /*!
1006  * \brief Blind transfer target to the extension and context provided
1007  *
1008  * The channel given is bridged to one or multiple channels. Depending on
1009  * the bridge and the number of participants, the entire bridge could be
1010  * transferred to the given destination, or a single channel may be redirected.
1011  *
1012  * Callers may also provide a callback to be called on the channel that will
1013  * be running dialplan. The user data passed into ast_bridge_transfer_blind
1014  * will be given as the argument to the callback to be interpreted as desired.
1015  * This callback is guaranteed to be called in the same thread as
1016  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
1017  *
1018  * \note Absolutely _NO_ channel locks should be held before
1019  * calling this function.
1020  *
1021  * \param is_external Indicates that transfer was initiated externally
1022  * \param transferer The channel performing the blind transfer
1023  * \param exten The dialplan extension to send the call to
1024  * \param context The dialplan context to send the call to
1025  * \param new_channel_cb A callback to be called on the channel that will
1026  *        be executing dialplan
1027  * \param user_data Argument for new_channel_cb
1028  * \return The success or failure result of the blind transfer
1029  */
1030 enum ast_transfer_result ast_bridge_transfer_blind(int is_external,
1031                 struct ast_channel *transferer, const char *exten, const char *context,
1032                 transfer_channel_cb new_channel_cb, void *user_data);
1033
1034 /*!
1035  * \brief Attended transfer
1036  *
1037  * The two channels are both transferer channels. The first is the channel
1038  * that is bridged to the transferee (or if unbridged, the 'first' call of
1039  * the transfer). The second is the channel that is bridged to the transfer
1040  * target (or if unbridged, the 'second' call of the transfer).
1041  *
1042  * \note Absolutely _NO_ channel locks should be held before
1043  * calling this function.
1044  *
1045  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
1046  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
1047  * \return The success or failure of the attended transfer
1048  */
1049 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
1050                 struct ast_channel *to_transfer_target);
1051
1052 /*!
1053  * \brief Set the relevant transfer variables for a single channel
1054  *
1055  * Sets either the ATTENDEDTRANSFER or BLINDTRANSFER variable for a channel while clearing
1056  * the opposite.
1057  *
1058  * \param chan Channel the variable is being set for
1059  * \param value Value the variable is being set to
1060  * \param is_attended false  set BLINDTRANSFER and unset ATTENDEDTRANSFER
1061  *                    true   set ATTENDEDTRANSFER and unset BLINDTRANSFER
1062  */
1063 void ast_bridge_set_transfer_variables(struct ast_channel *chan, const char *value, int is_attended);
1064
1065 /*!
1066  * \brief Get a container of all channels in the bridge
1067  * \since 12.0.0
1068  *
1069  * \param bridge The bridge which is already locked.
1070  *
1071  * \retval NULL Failed to create container
1072  * \retval non-NULL Container of channels in the bridge
1073  */
1074 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
1075
1076 /*!
1077  * \brief Get a container of all channels in the bridge
1078  * \since 12.0.0
1079  *
1080  * \param bridge The bridge
1081  *
1082  * \note The returned container is a snapshot of channels in the
1083  * bridge when called.
1084  *
1085  * \retval NULL Failed to create container
1086  * \retval non-NULL Container of channels in the bridge
1087  */
1088 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
1089
1090 /*!
1091  * \brief Get the channel's bridge peer only if the bridge is two-party.
1092  * \since 12.0.0
1093  *
1094  * \param bridge The bridge which is already locked.
1095  * \param chan Channel desiring the bridge peer channel.
1096  *
1097  * \note The returned peer channel is the current peer in the
1098  * bridge when called.
1099  *
1100  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1101  * \retval non-NULL Reffed peer channel at time of calling.
1102  */
1103 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
1104
1105 /*!
1106  * \brief Get the channel's bridge peer only if the bridge is two-party.
1107  * \since 12.0.0
1108  *
1109  * \param bridge The bridge
1110  * \param chan Channel desiring the bridge peer channel.
1111  *
1112  * \note The returned peer channel is the current peer in the
1113  * bridge when called.
1114  *
1115  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1116  * \retval non-NULL Reffed peer channel at time of calling.
1117  */
1118 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
1119
1120 /*!
1121  * \brief Remove marked bridge channel feature hooks.
1122  * \since 12.0.0
1123  *
1124  * \param features Bridge features structure
1125  * \param flags Determinator for whether hook is removed.
1126  *
1127  * \return Nothing
1128  */
1129 void ast_bridge_features_remove(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags flags);
1130
1131 /*!
1132  * \brief Find bridge by id
1133  * \since 12.0.0
1134  *
1135  * \param bridge_id Bridge identifier
1136  *
1137  * \return NULL bridge not found
1138  * \return non-NULL reference to bridge
1139  */
1140 struct ast_bridge *ast_bridge_find_by_id(const char *bridge_id);
1141
1142 #if defined(__cplusplus) || defined(c_plusplus)
1143 }
1144 #endif
1145
1146 #endif  /* _ASTERISK_BRIDGING_H */