Unset BRIDGEPEER when leaving a bridge
[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 };
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         /*! Peek at swap channel before it can hang up, prior to push. */
245         ast_bridge_push_channel_fn push_peek;
246 };
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         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  * \param id Unique ID given to the bridge by its creator (optional)
337  *
338  * \retval a pointer to a new bridge on success
339  * \retval NULL on failure
340  *
341  * Example usage:
342  *
343  * \code
344  * struct ast_bridge *bridge;
345  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
346  * \endcode
347  *
348  * This creates a no frills two party bridge that will be
349  * destroyed once one of the channels hangs up.
350  */
351 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
352
353 /*!
354  * \brief Try locking the bridge.
355  *
356  * \param bridge Bridge to try locking
357  *
358  * \retval 0 on success.
359  * \retval non-zero on error.
360  */
361 #define ast_bridge_trylock(bridge)      _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
362 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
363 {
364         return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
365 }
366
367 /*!
368  * \brief Lock the bridge.
369  *
370  * \param bridge Bridge to lock
371  *
372  * \return Nothing
373  */
374 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
375 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
376 {
377         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
378 }
379
380 /*!
381  * \brief Unlock the bridge.
382  *
383  * \param bridge Bridge to unlock
384  *
385  * \return Nothing
386  */
387 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
388 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
389 {
390         __ao2_unlock(bridge, file, function, line, var);
391 }
392
393 /*! \brief Lock two bridges. */
394 #define ast_bridge_lock_both(bridge1, bridge2)          \
395         do {                                                                                    \
396                 for (;;) {                                                                      \
397                         ast_bridge_lock(bridge1);                               \
398                         if (!ast_bridge_trylock(bridge2)) {             \
399                                 break;                                                          \
400                         }                                                                               \
401                         ast_bridge_unlock(bridge1);                             \
402                         sched_yield();                                                  \
403                 }                                                                                       \
404         } while (0)
405
406 /*!
407  * \brief Destroy a bridge
408  *
409  * \param bridge Bridge to destroy
410  * \param cause Cause of bridge being destroyed.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
411  *
412  * \retval 0 on success
413  * \retval -1 on failure
414  *
415  * Example usage:
416  *
417  * \code
418  * ast_bridge_destroy(bridge, AST_CAUSE_NORMAL_CLEARING);
419  * \endcode
420  *
421  * This destroys a bridge that was previously created.
422  *
423  * \note
424  * While this function will kick all channels out of the bridge, channels that
425  * were added to the bridge using ast_bridge_impart() with the flag
426  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE set must have ast_bridge_depart() called
427  * on them.
428  */
429 int ast_bridge_destroy(struct ast_bridge *bridge, int cause);
430
431 /*!
432  * \brief Notify bridging that this channel was just masqueraded.
433  * \since 12.0.0
434  *
435  * \param chan Channel just involved in a masquerade
436  *
437  * \return Nothing
438  */
439 void ast_bridge_notify_masquerade(struct ast_channel *chan);
440
441 enum ast_bridge_join_flags {
442         /*! The bridge reference is being passed by the caller. */
443         AST_BRIDGE_JOIN_PASS_REFERENCE = (1 << 0),
444         /*! The initial bridge join does not cause a COLP exchange. */
445         AST_BRIDGE_JOIN_INHIBIT_JOIN_COLP = (1 << 1),
446 };
447
448 /*!
449  * \brief Join a channel to a bridge (blocking)
450  *
451  * \param bridge Bridge to join
452  * \param chan Channel to join
453  * \param swap Channel to swap out if swapping (A channel reference is stolen.)
454  * \param features Bridge features structure
455  * \param tech_args Optional Bridging tech optimization parameters for this channel.
456  * \param flags defined by enum ast_bridge_join_flags.
457  *
458  * \note The passed in swap channel is always unreffed on return.  It is not a
459  * good idea to access the swap channel on return or for the caller to keep a
460  * reference to it.
461  *
462  * \note Absolutely _NO_ locks should be held before calling
463  * this function since it blocks.
464  *
465  * \retval 0 if the channel successfully joined the bridge before it exited.
466  * \retval -1 if the channel failed to join the bridge
467  *
468  * Example usage:
469  *
470  * \code
471  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, AST_BRIDGE_JOIN_PASS_REFERENCE);
472  * \endcode
473  *
474  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
475  * the bridge pointer. This function will not return until the channel has been
476  * removed from the bridge, swapped out for another channel, or has hung up.
477  *
478  * If this channel will be replacing another channel the other channel can be specified
479  * in the swap parameter. The other channel will be thrown out of the bridge in an
480  * atomic fashion.
481  *
482  * If channel specific features are enabled a pointer to the features structure
483  * can be specified in the features parameter.
484  */
485 int ast_bridge_join(struct ast_bridge *bridge,
486         struct ast_channel *chan,
487         struct ast_channel *swap,
488         struct ast_bridge_features *features,
489         struct ast_bridge_tech_optimizations *tech_args,
490         enum ast_bridge_join_flags flags);
491
492 enum ast_bridge_impart_flags {
493         /*! Field describing what the caller can do with the channel after it is imparted. */
494         AST_BRIDGE_IMPART_CHAN_MASK = (1 << 0),
495         /*! The caller wants to reclaim the channel using ast_bridge_depart(). */
496         AST_BRIDGE_IMPART_CHAN_DEPARTABLE = (0 << 0),
497         /*! The caller is passing channel control entirely to the bridging system. */
498         AST_BRIDGE_IMPART_CHAN_INDEPENDENT = (1 << 0),
499         /*! The initial bridge join does not cause a COLP exchange. */
500         AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP = (1 << 1),
501 };
502
503 /*!
504  * \brief Impart a channel to a bridge (non-blocking)
505  *
506  * \param bridge Bridge to impart on
507  * \param chan Channel to impart (The channel reference is stolen if impart successful.)
508  * \param swap Channel to swap out if swapping.  NULL if not swapping.
509  * \param features Bridge features structure.
510  * \param flags defined by enum ast_bridge_impart_flags.
511  *
512  * \note The given bridge must be unlocked when calling this function.
513  *
514  * \note The features parameter must be NULL or obtained by
515  * ast_bridge_features_new().  You must not dereference features
516  * after calling even if the call fails.
517  *
518  * \note chan is locked by this function.
519  *
520  * \retval 0 on success
521  * \retval -1 on failure (Caller still has ownership of chan)
522  *
523  * Example usage:
524  *
525  * \code
526  * ast_bridge_impart(bridge, chan, NULL, NULL, AST_BRIDGE_IMPART_CHAN_INDEPENDENT);
527  * \endcode
528  *
529  * \details
530  * This adds a channel pointed to by the chan pointer to the
531  * bridge pointed to by the bridge pointer.  This function will
532  * return immediately and will not wait until the channel is no
533  * longer part of the bridge.
534  *
535  * If this channel will be replacing another channel the other
536  * channel can be specified in the swap parameter.  The other
537  * channel will be thrown out of the bridge in an atomic
538  * fashion.
539  *
540  * If channel specific features are enabled, a pointer to the
541  * features structure can be specified in the features
542  * parameter.
543  *
544  * \note If you impart a channel with
545  * AST_BRIDGE_IMPART_CHAN_DEPARTABLE you MUST
546  * ast_bridge_depart() the channel if this call succeeds.  The
547  * bridge channel thread is created join-able.  The implication
548  * is that the channel is special and will not behave like a
549  * normal channel.
550  *
551  * \note If you impart a channel with
552  * AST_BRIDGE_IMPART_CHAN_INDEPENDENT you must not
553  * ast_bridge_depart() the channel.  The bridge channel thread
554  * is created non-join-able.  The channel must be treated as if
555  * it were placed into the bridge by ast_bridge_join().
556  * Channels placed into a bridge by ast_bridge_join() are
557  * removed by a third party using ast_bridge_remove().
558  */
559 int ast_bridge_impart(struct ast_bridge *bridge,
560         struct ast_channel *chan,
561         struct ast_channel *swap,
562         struct ast_bridge_features *features,
563         enum ast_bridge_impart_flags flags) attribute_warn_unused_result;
564
565 /*!
566  * \brief Depart a channel from a bridge
567  *
568  * \param chan Channel to depart
569  *
570  * \note chan is locked by this function.
571  *
572  * \retval 0 on success
573  * \retval -1 on failure
574  *
575  * Example usage:
576  *
577  * \code
578  * ast_bridge_depart(chan);
579  * \endcode
580  *
581  * This removes the channel pointed to by the chan pointer from any bridge
582  * it may be in and gives control to the calling thread.
583  * This does not hang up the channel.
584  *
585  * \note This API call can only be used on channels that were added to the bridge
586  *       using the ast_bridge_impart API call with the AST_BRIDGE_IMPART_CHAN_DEPARTABLE
587  *       flag.
588  */
589 int ast_bridge_depart(struct ast_channel *chan);
590
591 /*!
592  * \brief Remove a channel from a bridge
593  *
594  * \param bridge Bridge that the channel is to be removed from
595  * \param chan Channel to remove
596  *
597  * \retval 0 on success
598  * \retval -1 on failure
599  *
600  * Example usage:
601  *
602  * \code
603  * ast_bridge_remove(bridge, chan);
604  * \endcode
605  *
606  * This removes the channel pointed to by the chan pointer from the bridge
607  * pointed to by the bridge pointer and requests that it be hung up. Control
608  * over the channel will NOT be given to the calling thread.
609  *
610  * \note This API call can be used on channels that were added to the bridge
611  *       using both ast_bridge_join and ast_bridge_impart.
612  */
613 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
614
615 /*!
616  * \brief Kick a channel from a bridge
617  *
618  * \param bridge Bridge that the channel is to be kicked from
619  * \param chan Channel to kick
620  *
621  * \retval 0 on success
622  * \retval -1 on failure
623  *
624  * Example usage:
625  *
626  * \code
627  * ast_bridge_kick(bridge, chan);
628  * \endcode
629  *
630  * \details
631  * This kicks the channel pointed to by the chan pointer from
632  * the bridge pointed to by the bridge pointer and requests that
633  * it be hung up.  Control over the channel will NOT be given to
634  * the calling thread.
635  *
636  * \note The functional difference between ast_bridge_kick() and
637  * ast_bridge_remove() is that the bridge may dissolve as a
638  * result of the channel being kicked.
639  *
640  * \note This API call can be used on channels that were added
641  * to the bridge using both ast_bridge_join and
642  * ast_bridge_impart.
643  */
644 int ast_bridge_kick(struct ast_bridge *bridge, struct ast_channel *chan);
645
646 /*!
647  * \brief Merge two bridges together
648  *
649  * \param dst_bridge Destination bridge of merge.
650  * \param src_bridge Source bridge of merge.
651  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
652  * \param kick_me Array of channels to kick from the bridges.
653  * \param num_kick Number of channels in the kick_me array.
654  *
655  * \note Absolutely _NO_ bridge or channel locks should be held
656  * before calling this function.
657  *
658  * \retval 0 on success
659  * \retval -1 on failure
660  *
661  * Example usage:
662  *
663  * \code
664  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
665  * \endcode
666  *
667  * This moves the channels in src_bridge into the bridge pointed
668  * to by dst_bridge.
669  */
670 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);
671
672 /*!
673  * \brief Move a channel from one bridge to another.
674  * \since 12.0.0
675  *
676  * \param dst_bridge Destination bridge of bridge channel move.
677  * \param src_bridge Source bridge of bridge channel move.
678  * \param chan Channel to move.
679  * \param swap Channel to replace in dst_bridge.
680  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
681  *
682  * \note Absolutely _NO_ bridge or channel locks should be held
683  * before calling this function.
684  *
685  * \retval 0 on success.
686  * \retval -1 on failure.
687  */
688 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);
689
690 /*!
691  * \brief Adjust the bridge merge inhibit request count.
692  * \since 12.0.0
693  *
694  * \param bridge What to operate on.
695  * \param request Inhibit request increment.
696  *     (Positive to add requests.  Negative to remove requests.)
697  *
698  * \return Nothing
699  */
700 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
701
702 /*!
703  * \brief Suspend a channel temporarily from a bridge
704  *
705  * \param bridge Bridge to suspend the channel from
706  * \param chan Channel to suspend
707  *
708  * \retval 0 on success
709  * \retval -1 on failure
710  *
711  * Example usage:
712  *
713  * \code
714  * ast_bridge_suspend(bridge, chan);
715  * \endcode
716  *
717  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
718  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
719  * the channel will not be removed from the bridge.
720  *
721  * \note This API call can be used on channels that were added to the bridge
722  *       using both ast_bridge_join and ast_bridge_impart.
723  */
724 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
725
726 /*!
727  * \brief Unsuspend a channel from a bridge
728  *
729  * \param bridge Bridge to unsuspend the channel from
730  * \param chan Channel to unsuspend
731  *
732  * \retval 0 on success
733  * \retval -1 on failure
734  *
735  * Example usage:
736  *
737  * \code
738  * ast_bridge_unsuspend(bridge, chan);
739  * \endcode
740  *
741  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
742  * The bridge will go back to handling the channel once this function returns.
743  *
744  * \note You must not mess with the channel once this function returns.
745  *       Doing so may result in bad things happening.
746  */
747 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
748
749 /*!
750  * \brief Sets BRIDGECHANNEL and BRIDGEPVTCALLID for a channel
751  *
752  * \pre chan must be locked before calling
753  *
754  * \param name channel name of the bridged peer
755  * \param pvtid Private CallID of the bridged peer
756  *
757  * \return nothing
758  */
759 void ast_bridge_vars_set(struct ast_channel *chan, const char *name, const char *pvtid);
760
761 struct ast_unreal_pvt;
762
763 /*!
764  * \brief Check and optimize out the unreal channels between bridges.
765  * \since 12.0.0
766  *
767  * \param chan Unreal channel writing a frame into the channel driver.
768  * \param peer Other unreal channel in the pair.
769  * \param pvt Private data provided by an implementation of the unreal driver that
770  * contains the callbacks that should be called when optimization begins/ends
771  *
772  * \note It is assumed that chan is already locked.
773  *
774  * \retval 0 if unreal channels were not optimized out.
775  * \retval non-zero if unreal channels were optimized out.
776  */
777 int ast_bridge_unreal_optimize_out(struct ast_channel *chan, struct ast_channel *peer, struct ast_unreal_pvt *pvt);
778
779 /*!
780  * \brief Tells, if optimization is allowed, how the optimization would be performed
781  */
782 enum ast_bridge_optimization {
783         /*! Optimization would swap peer into the chan_bridge */
784         AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
785         /*! Optimization would swap chan into the peer_bridge */
786         AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
787         /*! Optimization would merge peer_bridge into chan_bridge */
788         AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
789         /*! Optimization would merge chan_bridge into peer_bridge */
790         AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
791         /*! Optimization is not permitted on one or both bridges */
792         AST_BRIDGE_OPTIMIZE_PROHIBITED,
793 };
794
795 /*!
796  * \brief Determine if bridges allow for optimization to occur betweem them
797  * \since 12.0.0
798  *
799  * \param chan_bridge First bridge being tested
800  * \param peer_bridge Second bridge being tested
801  *
802  * This determines if two bridges allow for unreal channel optimization
803  * to occur between them. The function does not require for unreal channels
804  * to already be in the bridges when called.
805  *
806  * \note It is assumed that both bridges are locked prior to calling this function
807  *
808  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
809  * that an optimization attempt will succeed. However, a return of
810  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
811  * never succeed.
812  *
813  * \returns Optimization allowability for the bridges
814  */
815 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
816                 struct ast_bridge *peer_bridge);
817
818 /*!
819  * \brief Put an action onto the specified bridge.
820  * \since 12.0.0
821  *
822  * \param bridge What to queue the action on.
823  * \param action What to do.
824  *
825  * \retval 0 on success.
826  * \retval -1 on error.
827  *
828  * \note This API call is meant for internal bridging operations.
829  */
830 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
831
832 /*!
833  * \brief Queue the given frame to everyone else.
834  * \since 12.0.0
835  *
836  * \param bridge What bridge to distribute frame.
837  * \param bridge_channel Channel to optionally not pass frame to. (NULL to pass to everyone)
838  * \param frame Frame to pass.
839  *
840  * \note This is intended to be called by bridge hooks and
841  * bridge technologies.
842  *
843  * \retval 0 Frame written to at least one channel.
844  * \retval -1 Frame written to no channels.
845  */
846 int ast_bridge_queue_everyone_else(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
847
848 /*!
849  * \brief Adjust the internal mixing sample rate of a bridge
850  * used during multimix mode.
851  *
852  * \param bridge Channel to change the sample rate on.
853  * \param sample_rate the sample rate to change to. If a
854  *        value of 0 is passed here, the bridge will be free to pick
855  *        what ever sample rate it chooses.
856  *
857  */
858 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
859
860 /*!
861  * \brief Adjust the internal mixing interval of a bridge used
862  * during multimix mode.
863  *
864  * \param bridge Channel to change the sample rate on.
865  * \param mixing_interval the sample rate to change to.  If 0 is set
866  * the bridge tech is free to choose any mixing interval it uses by default.
867  */
868 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
869
870 /*!
871  * \brief Set a bridge to feed a single video source to all participants.
872  */
873 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
874
875 /*!
876  * \brief Set the bridge to pick the strongest talker supporting
877  * video as the single source video feed
878  */
879 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
880
881 /*!
882  * \brief Update information about talker energy for talker src video mode.
883  */
884 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
885
886 /*!
887  * \brief Returns the number of video sources currently active in the bridge
888  */
889 int ast_bridge_number_video_src(struct ast_bridge *bridge);
890
891 /*!
892  * \brief Determine if a channel is a video src for the bridge
893  *
894  * \retval 0 Not a current video source of the bridge.
895  * \retval None 0, is a video source of the bridge, The number
896  *         returned represents the priority this video stream has
897  *         on the bridge where 1 is the highest priority.
898  */
899 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
900
901 /*!
902  * \brief remove a channel as a source of video for the bridge.
903  */
904 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
905
906 enum ast_transfer_result {
907         /*! The transfer completed successfully */
908         AST_BRIDGE_TRANSFER_SUCCESS,
909         /*! A bridge involved does not permit transferring */
910         AST_BRIDGE_TRANSFER_NOT_PERMITTED,
911         /*! The current bridge setup makes transferring an invalid operation */
912         AST_BRIDGE_TRANSFER_INVALID,
913         /*! The transfer operation failed for a miscellaneous reason */
914         AST_BRIDGE_TRANSFER_FAIL,
915 };
916
917 enum ast_transfer_type {
918         /*! Transfer of a single party */
919         AST_BRIDGE_TRANSFER_SINGLE_PARTY,
920         /*! Transfer of multiple parties */
921         AST_BRIDGE_TRANSFER_MULTI_PARTY,
922 };
923
924 /*!
925  * \brief AO2 object that wraps data for transfer_channel_cb
926  */
927 struct transfer_channel_data {
928         void *data;    /*! Data to be used by the transfer_channel_cb -- note that this
929                         *  pointer is going to be pointing to something on the stack, so
930                         *  it must not be used at any point after returning from the
931                         *  transfer_channel_cb. */
932         int completed; /*! Initially 0, This will be set to 1 by either the transfer
933                         *  code or by transfer code hooks (e.g. parking) when the
934                         *  transfer is completed and any remaining actions have taken
935                         *  place (e.g. parking announcements). It will never be reset
936                         *  to 0. This is used for deferring progress for channel
937                         *  drivers that support deferred progress. */
938 };
939
940 /*!
941  * \brief Callback function type called during blind transfers
942  *
943  * A caller of ast_bridge_transfer_blind() may wish to set data on
944  * the channel that ends up running dialplan. For instance, it may
945  * be useful to set channel variables on the channel.
946  *
947  * \param chan The involved channel
948  * \param user_data User-provided data needed in the callback
949  * \param transfer_type The type of transfer being completed
950  */
951 typedef void (*transfer_channel_cb)(struct ast_channel *chan, struct transfer_channel_data *user_data,
952                 enum ast_transfer_type transfer_type);
953
954 /*!
955  * \brief Blind transfer target to the extension and context provided
956  *
957  * The channel given is bridged to one or multiple channels. Depending on
958  * the bridge and the number of participants, the entire bridge could be
959  * transferred to the given destination, or a single channel may be redirected.
960  *
961  * Callers may also provide a callback to be called on the channel that will
962  * be running dialplan. The user data passed into ast_bridge_transfer_blind
963  * will be given as the argument to the callback to be interpreted as desired.
964  * This callback is guaranteed to be called in the same thread as
965  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
966  *
967  * \note Absolutely _NO_ channel locks should be held before
968  * calling this function.
969  *
970  * \param is_external Indicates that transfer was initiated externally
971  * \param transferer The channel performing the blind transfer
972  * \param exten The dialplan extension to send the call to
973  * \param context The dialplan context to send the call to
974  * \param new_channel_cb A callback to be called on the channel that will
975  *        be executing dialplan
976  * \param user_data Argument for new_channel_cb
977  * \return The success or failure result of the blind transfer
978  */
979 enum ast_transfer_result ast_bridge_transfer_blind(int is_external,
980                 struct ast_channel *transferer, const char *exten, const char *context,
981                 transfer_channel_cb new_channel_cb, void *user_data);
982
983 /*!
984  * \brief Attended transfer
985  *
986  * The two channels are both transferer channels. The first is the channel
987  * that is bridged to the transferee (or if unbridged, the 'first' call of
988  * the transfer). The second is the channel that is bridged to the transfer
989  * target (or if unbridged, the 'second' call of the transfer).
990  *
991  * \note Absolutely _NO_ channel locks should be held before
992  * calling this function.
993  *
994  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
995  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
996  * \return The success or failure of the attended transfer
997  */
998 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
999                 struct ast_channel *to_transfer_target);
1000
1001 /*!
1002  * \brief Set the relevant transfer variables for a single channel
1003  *
1004  * Sets either the ATTENDEDTRANSFER or BLINDTRANSFER variable for a channel while clearing
1005  * the opposite.
1006  *
1007  * \param chan Channel the variable is being set for
1008  * \param value Value the variable is being set to
1009  * \param is_attended false  set BLINDTRANSFER and unset ATTENDEDTRANSFER
1010  *                    true   set ATTENDEDTRANSFER and unset BLINDTRANSFER
1011  */
1012 void ast_bridge_set_transfer_variables(struct ast_channel *chan, const char *value, int is_attended);
1013
1014 /*!
1015  * \brief Get a container of all channels in the bridge
1016  * \since 12.0.0
1017  *
1018  * \param bridge The bridge which is already locked.
1019  *
1020  * \retval NULL Failed to create container
1021  * \retval non-NULL Container of channels in the bridge
1022  */
1023 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
1024
1025 /*!
1026  * \brief Get a container of all channels in the bridge
1027  * \since 12.0.0
1028  *
1029  * \param bridge The bridge
1030  *
1031  * \note The returned container is a snapshot of channels in the
1032  * bridge when called.
1033  *
1034  * \retval NULL Failed to create container
1035  * \retval non-NULL Container of channels in the bridge
1036  */
1037 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
1038
1039 /*!
1040  * \brief Get the channel's bridge peer only if the bridge is two-party.
1041  * \since 12.0.0
1042  *
1043  * \param bridge The bridge which is already locked.
1044  * \param chan Channel desiring the bridge peer channel.
1045  *
1046  * \note The returned peer channel is the current peer in the
1047  * bridge when called.
1048  *
1049  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1050  * \retval non-NULL Reffed peer channel at time of calling.
1051  */
1052 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
1053
1054 /*!
1055  * \brief Get the channel's bridge peer only if the bridge is two-party.
1056  * \since 12.0.0
1057  *
1058  * \param bridge The bridge
1059  * \param chan Channel desiring the bridge peer channel.
1060  *
1061  * \note The returned peer channel is the current peer in the
1062  * bridge when called.
1063  *
1064  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1065  * \retval non-NULL Reffed peer channel at time of calling.
1066  */
1067 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
1068
1069 /*!
1070  * \brief Remove marked bridge channel feature hooks.
1071  * \since 12.0.0
1072  *
1073  * \param features Bridge features structure
1074  * \param flags Determinator for whether hook is removed.
1075  *
1076  * \return Nothing
1077  */
1078 void ast_bridge_features_remove(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags flags);
1079
1080 /*!
1081  * \brief Find bridge by id
1082  * \since 12.0.0
1083  *
1084  * \param bridge_id Bridge identifier
1085  *
1086  * \return NULL bridge not found
1087  * \return non-NULL reference to bridge
1088  */
1089 struct ast_bridge *ast_bridge_find_by_id(const char *bridge_id);
1090
1091 #if defined(__cplusplus) || defined(c_plusplus)
1092 }
1093 #endif
1094
1095 #endif  /* _ASTERISK_BRIDGING_H */