Reimplement bridging and DTMF features related channel variables in the bridging...
[asterisk/asterisk.git] / include / asterisk / bridging.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 Channel 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 Channel 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/bridging_features.h"
73 #include "asterisk/bridging_roles.h"
74 #include "asterisk/dsp.h"
75 #include "asterisk/uuid.h"
76
77 /*! \brief Capabilities for a bridge technology */
78 enum ast_bridge_capability {
79         /*! Bridge technology can service calls on hold. */
80         AST_BRIDGE_CAPABILITY_HOLDING = (1 << 0),
81         /*! Bridge waits for channel to answer.  Passes early media. (XXX Not supported yet) */
82         AST_BRIDGE_CAPABILITY_EARLY = (1 << 1),
83         /*! Bridge is capable of natively bridging two channels. (Smart bridge only) */
84         AST_BRIDGE_CAPABILITY_NATIVE = (1 << 2),
85         /*! Bridge is capable of mixing at most two channels. (Smart bridgeable) */
86         AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 3),
87         /*! Bridge is capable of mixing an arbitrary number of channels. (Smart bridgeable) */
88         AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 4),
89 };
90
91 /*! \brief State information about a bridged channel */
92 enum ast_bridge_channel_state {
93         /*! Waiting for a signal (Channel in the bridge) */
94         AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
95         /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
96         AST_BRIDGE_CHANNEL_STATE_END,
97         /*! Bridged channel was forced out and should be hung up */
98         AST_BRIDGE_CHANNEL_STATE_HANGUP,
99 };
100
101 enum ast_bridge_channel_thread_state {
102         /*! Bridge channel thread is idle/waiting. */
103         AST_BRIDGE_CHANNEL_THREAD_IDLE,
104         /*! Bridge channel thread is writing a normal/simple frame. */
105         AST_BRIDGE_CHANNEL_THREAD_SIMPLE,
106         /*! Bridge channel thread is processing a frame. */
107         AST_BRIDGE_CHANNEL_THREAD_FRAME,
108 };
109
110 struct ast_bridge_technology;
111 struct ast_bridge;
112
113 /*!
114  * \brief Structure specific to bridge technologies capable of
115  * performing talking optimizations.
116  */
117 struct ast_bridge_tech_optimizations {
118         /*! The amount of time in ms that talking must be detected before
119          *  the dsp determines that talking has occurred */
120         unsigned int talking_threshold;
121         /*! The amount of time in ms that silence must be detected before
122          *  the dsp determines that talking has stopped */
123         unsigned int silence_threshold;
124         /*! Whether or not the bridging technology should drop audio
125          *  detected as silence from the mix. */
126         unsigned int drop_silence:1;
127 };
128
129 /*!
130  * \brief Structure that contains information regarding a channel in a bridge
131  */
132 struct ast_bridge_channel {
133 /* BUGBUG cond is only here because of external party suspend/unsuspend support. */
134         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
135         ast_cond_t cond;
136         /*! Current bridged channel state */
137         enum ast_bridge_channel_state state;
138         /*! Asterisk channel participating in the bridge */
139         struct ast_channel *chan;
140         /*! Asterisk channel we are swapping with (if swapping) */
141         struct ast_channel *swap;
142         /*!
143          * \brief Bridge this channel is participating in
144          *
145          * \note The bridge pointer cannot change while the bridge or
146          * bridge_channel is locked.
147          */
148         struct ast_bridge *bridge;
149         /*!
150          * \brief Bridge class private channel data.
151          *
152          * \note This information is added when the channel is pushed
153          * into the bridge and removed when it is pulled from the
154          * bridge.
155          */
156         void *bridge_pvt;
157         /*!
158          * \brief Private information unique to the bridge technology.
159          *
160          * \note This information is added when the channel joins the
161          * bridge's technology and removed when it leaves the bridge's
162          * technology.
163          */
164         void *tech_pvt;
165         /*! Thread handling the bridged channel (Needed by ast_bridge_depart) */
166         pthread_t thread;
167         /* v-- These flags change while the bridge is locked or before the channel is in the bridge. */
168         /*! TRUE if the channel is in a bridge. */
169         unsigned int in_bridge:1;
170         /*! TRUE if the channel just joined the bridge. */
171         unsigned int just_joined:1;
172         /*! TRUE if the channel is suspended from the bridge. */
173         unsigned int suspended:1;
174         /*! TRUE if the channel must wait for an ast_bridge_depart to reclaim the channel. */
175         unsigned int depart_wait:1;
176         /* ^-- These flags change while the bridge is locked or before the channel is in the bridge. */
177         /*! Features structure for features that are specific to this channel */
178         struct ast_bridge_features *features;
179         /*! Technology optimization parameters used by bridging technologies capable of
180          *  optimizing based upon talk detection. */
181         struct ast_bridge_tech_optimizations tech_args;
182         /*! Copy of read format used by chan before join */
183         struct ast_format read_format;
184         /*! Copy of write format used by chan before join */
185         struct ast_format write_format;
186         /*! Call ID associated with bridge channel */
187         struct ast_callid *callid;
188         /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
189         struct bridge_roles_datastore *bridge_roles;
190         /*! Linked list information */
191         AST_LIST_ENTRY(ast_bridge_channel) entry;
192         /*! Queue of outgoing frames to the channel. */
193         AST_LIST_HEAD_NOLOCK(, ast_frame) wr_queue;
194         /*! Pipe to alert thread when frames are put into the wr_queue. */
195         int alert_pipe[2];
196         /*! TRUE if the bridge channel thread is waiting on channels (needs to be atomically settable) */
197         int waiting;
198         /*!
199          * \brief The bridge channel thread activity.
200          *
201          * \details Used by local channel optimization to determine if
202          * the thread is in an acceptable state to optimize.
203          *
204          * \note Needs to be atomically settable.
205          */
206         enum ast_bridge_channel_thread_state activity;
207 };
208
209 enum ast_bridge_action_type {
210         /*! Bridged channel is to detect a feature hook */
211         AST_BRIDGE_ACTION_FEATURE,
212         /*! Bridged channel is to act on an interval hook */
213         AST_BRIDGE_ACTION_INTERVAL,
214         /*! Bridged channel is to send a DTMF stream out */
215         AST_BRIDGE_ACTION_DTMF_STREAM,
216         /*! Bridged channel is to indicate talking start */
217         AST_BRIDGE_ACTION_TALKING_START,
218         /*! Bridged channel is to indicate talking stop */
219         AST_BRIDGE_ACTION_TALKING_STOP,
220         /*! Bridge channel is to play the indicated sound file. */
221         AST_BRIDGE_ACTION_PLAY_FILE,
222         /*! Bridge channel is to run the indicated application. */
223         AST_BRIDGE_ACTION_RUN_APP,
224         /*! Bridge channel is to run the custom callback routine. */
225         AST_BRIDGE_ACTION_CALLBACK,
226         /*! Bridge channel is to get parked. */
227         AST_BRIDGE_ACTION_PARK,
228         /*! Bridge channel is to execute a blind transfer. */
229         AST_BRIDGE_ACTION_BLIND_TRANSFER,
230         /*! Bridge channel is to execute an attended transfer */
231         AST_BRIDGE_ACTION_ATTENDED_TRANSFER,
232
233         /*
234          * Bridge actions put after this comment must never be put onto
235          * the bridge_channel wr_queue because they have other resources
236          * that must be freed.
237          */
238
239         /*! Bridge reconfiguration deferred technology destruction. */
240         AST_BRIDGE_ACTION_DEFERRED_TECH_DESTROY = 1000,
241         /*! Bridge deferred dissolving. */
242         AST_BRIDGE_ACTION_DEFERRED_DISSOLVING,
243 };
244
245 enum ast_bridge_video_mode_type {
246         /*! Video is not allowed in the bridge */
247         AST_BRIDGE_VIDEO_MODE_NONE = 0,
248         /*! A single user is picked as the only distributed of video across the bridge */
249         AST_BRIDGE_VIDEO_MODE_SINGLE_SRC,
250         /*! A single user's video feed is distributed to all bridge channels, but
251          *  that feed is automatically picked based on who is talking the most. */
252         AST_BRIDGE_VIDEO_MODE_TALKER_SRC,
253 };
254
255 /*! This is used for both SINGLE_SRC mode to set what channel
256  *  should be the current single video feed */
257 struct ast_bridge_video_single_src_data {
258         /*! Only accept video coming from this channel */
259         struct ast_channel *chan_vsrc;
260 };
261
262 /*! This is used for both SINGLE_SRC_TALKER mode to set what channel
263  *  should be the current single video feed */
264 struct ast_bridge_video_talker_src_data {
265         /*! Only accept video coming from this channel */
266         struct ast_channel *chan_vsrc;
267         int average_talking_energy;
268
269         /*! Current talker see's this person */
270         struct ast_channel *chan_old_vsrc;
271 };
272
273 struct ast_bridge_video_mode {
274         enum ast_bridge_video_mode_type mode;
275         /* Add data for all the video modes here. */
276         union {
277                 struct ast_bridge_video_single_src_data single_src_data;
278                 struct ast_bridge_video_talker_src_data talker_src_data;
279         } mode_data;
280 };
281
282 /*!
283  * \brief Destroy the bridge.
284  *
285  * \param self Bridge to operate upon.
286  *
287  * \return Nothing
288  */
289 typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
290
291 /*!
292  * \brief The bridge is being dissolved.
293  *
294  * \param self Bridge to operate upon.
295  *
296  * \details
297  * The bridge is being dissolved.  Remove any external
298  * references to the bridge so it can be destroyed.
299  *
300  * \note On entry, self must NOT be locked.
301  *
302  * \return Nothing
303  */
304 typedef void (*ast_bridge_dissolving_fn)(struct ast_bridge *self);
305
306 /*!
307  * \brief Push this channel into the bridge.
308  *
309  * \param self Bridge to operate upon.
310  * \param bridge_channel Bridge channel to push.
311  * \param swap Bridge channel to swap places with if not NULL.
312  *
313  * \details
314  * Setup any channel hooks controlled by the bridge.  Allocate
315  * bridge_channel->bridge_pvt and initialize any resources put
316  * in bridge_channel->bridge_pvt if needed.  If there is a swap
317  * channel, use it as a guide to setting up the bridge_channel.
318  *
319  * \note On entry, self is already locked.
320  *
321  * \retval 0 on success.
322  * \retval -1 on failure.  The channel did not get pushed.
323  */
324 typedef int (*ast_bridge_push_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
325
326 /*!
327  * \brief Pull this channel from the bridge.
328  *
329  * \param self Bridge to operate upon.
330  * \param bridge_channel Bridge channel to pull.
331  *
332  * \details
333  * Remove any channel hooks controlled by the bridge.  Release
334  * any resources held by bridge_channel->bridge_pvt and release
335  * bridge_channel->bridge_pvt.
336  *
337  * \note On entry, self is already locked.
338  *
339  * \return Nothing
340  */
341 typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
342
343 /*!
344  * \brief Notify the bridge that this channel was just masqueraded.
345  *
346  * \param self Bridge to operate upon.
347  * \param bridge_channel Bridge channel that was masqueraded.
348  *
349  * \details
350  * A masquerade just happened to this channel.  The bridge needs
351  * to re-evaluate this a channel in the bridge.
352  *
353  * \note On entry, self is already locked.
354  *
355  * \return Nothing
356  */
357 typedef void (*ast_bridge_notify_masquerade_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
358
359 /*!
360  * \brief Get the merge priority of this bridge.
361  *
362  * \param self Bridge to operate upon.
363  *
364  * \note On entry, self is already locked.
365  *
366  * \return Merge priority
367  */
368 typedef int (*ast_bridge_merge_priority_fn)(struct ast_bridge *self);
369
370 /*!
371  * \brief Bridge virtual methods table definition.
372  *
373  * \note Any changes to this struct must be reflected in
374  * ast_bridge_alloc() validity checking.
375  */
376 struct ast_bridge_methods {
377         /*! Bridge class name for log messages. */
378         const char *name;
379         /*! Destroy the bridge. */
380         ast_bridge_destructor_fn destroy;
381         /*! The bridge is being dissolved.  Remove any references to the bridge. */
382         ast_bridge_dissolving_fn dissolving;
383         /*! Push the bridge channel into the bridge. */
384         ast_bridge_push_channel_fn push;
385         /*! Pull the bridge channel from the bridge. */
386         ast_bridge_pull_channel_fn pull;
387         /*! Notify the bridge of a masquerade with the channel. */
388         ast_bridge_notify_masquerade_fn notify_masquerade;
389         /*! Get the bridge merge priority. */
390         ast_bridge_merge_priority_fn get_merge_priority;
391 };
392
393 /*!
394  * \brief Structure that contains information about a bridge
395  */
396 struct ast_bridge {
397         /*! Bridge virtual method table. */
398         const struct ast_bridge_methods *v_table;
399         /*! Immutable bridge UUID. */
400         char uniqueid[AST_UUID_STR_LEN];
401         /*! Bridge technology that is handling the bridge */
402         struct ast_bridge_technology *technology;
403         /*! Private information unique to the bridge technology */
404         void *tech_pvt;
405         /*! Call ID associated with the bridge */
406         struct ast_callid *callid;
407         /*! Linked list of channels participating in the bridge */
408         AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
409         /*! Queue of actions to perform on the bridge. */
410         AST_LIST_HEAD_NOLOCK(, ast_frame) action_queue;
411         /*! The video mode this bridge is using */
412         struct ast_bridge_video_mode video_mode;
413         /*! Bridge flags to tweak behavior */
414         struct ast_flags feature_flags;
415         /*! Allowed bridge technology capabilities when AST_BRIDGE_FLAG_SMART enabled. */
416         uint32_t allowed_capabilities;
417         /*! Number of channels participating in the bridge */
418         unsigned int num_channels;
419         /*! Number of active channels in the bridge. */
420         unsigned int num_active;
421         /*!
422          * \brief Count of the active temporary requests to inhibit bridge merges.
423          * Zero if merges are allowed.
424          *
425          * \note Temporary as in try again in a moment.
426          */
427         unsigned int inhibit_merge;
428         /*! The internal sample rate this bridge is mixed at when multiple channels are being mixed.
429          *  If this value is 0, the bridge technology may auto adjust the internal mixing rate. */
430         unsigned int internal_sample_rate;
431         /*! The mixing interval indicates how quickly the bridges internal mixing should occur
432          * for bridge technologies that mix audio. When set to 0, the bridge tech must choose a
433          * default interval for itself. */
434         unsigned int internal_mixing_interval;
435         /*! TRUE if the bridge was reconfigured. */
436         unsigned int reconfigured:1;
437         /*! TRUE if the bridge has been dissolved.  Any channel that now tries to join is immediately ejected. */
438         unsigned int dissolved:1;
439 };
440
441 /*!
442  * \brief Register the new bridge with the system.
443  * \since 12.0.0
444  *
445  * \param bridge What to register. (Tolerates a NULL pointer)
446  *
447  * \code
448  * struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
449  * {
450  *     void *bridge;
451  *
452  *     bridge = ast_bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
453  *     bridge = ast_bridge_base_init(bridge, capabilities, flags);
454  *     bridge = ast_bridge_basic_init(bridge, dtmf_features);
455  *     bridge = ast_bridge_register(bridge);
456  *     return bridge;
457  * }
458  * \endcode
459  *
460  * \note This must be done after a bridge constructor has
461  * completed setting up the new bridge but before it returns.
462  *
463  * \note After a bridge is registered, ast_bridge_destroy() must
464  * eventually be called to get rid of the bridge.
465  *
466  * \retval bridge on success.
467  * \retval NULL on error.
468  */
469 struct ast_bridge *ast_bridge_register(struct ast_bridge *bridge);
470
471 /*!
472  * \internal
473  * \brief Allocate the bridge class object memory.
474  * \since 12.0.0
475  *
476  * \param size Size of the bridge class structure to allocate.
477  * \param v_table Bridge class virtual method table.
478  *
479  * \retval bridge on success.
480  * \retval NULL on error.
481  */
482 struct ast_bridge *ast_bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
483
484 /*! \brief Bridge base class virtual method table. */
485 extern struct ast_bridge_methods ast_bridge_base_v_table;
486
487 /*!
488  * \brief Initialize the base class of the bridge.
489  *
490  * \param self Bridge to operate upon. (Tolerates a NULL pointer)
491  * \param capabilities The capabilities that we require to be used on the bridge
492  * \param flags Flags that will alter the behavior of the bridge
493  *
494  * \retval self on success
495  * \retval NULL on failure, self is already destroyed
496  *
497  * Example usage:
498  *
499  * \code
500  * struct ast_bridge *bridge;
501  * bridge = ast_bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
502  * bridge = ast_bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
503  * \endcode
504  *
505  * This creates a no frills two party bridge that will be
506  * destroyed once one of the channels hangs up.
507  */
508 struct ast_bridge *ast_bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags);
509
510 /*!
511  * \brief Create a new base class bridge
512  *
513  * \param capabilities The capabilities that we require to be used on the bridge
514  * \param flags Flags that will alter the behavior of the bridge
515  *
516  * \retval a pointer to a new bridge on success
517  * \retval NULL on failure
518  *
519  * Example usage:
520  *
521  * \code
522  * struct ast_bridge *bridge;
523  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
524  * \endcode
525  *
526  * This creates a no frills two party bridge that will be
527  * destroyed once one of the channels hangs up.
528  */
529 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags);
530
531 /*!
532  * \brief Try locking the bridge.
533  *
534  * \param bridge Bridge to try locking
535  *
536  * \retval 0 on success.
537  * \retval non-zero on error.
538  */
539 #define ast_bridge_trylock(bridge)      _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
540 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
541 {
542         return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
543 }
544
545 /*!
546  * \brief Lock the bridge.
547  *
548  * \param bridge Bridge to lock
549  *
550  * \return Nothing
551  */
552 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
553 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
554 {
555         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
556 }
557
558 /*!
559  * \brief Unlock the bridge.
560  *
561  * \param bridge Bridge to unlock
562  *
563  * \return Nothing
564  */
565 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
566 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
567 {
568         __ao2_unlock(bridge, file, function, line, var);
569 }
570
571 /*! \brief Lock two bridges. */
572 #define ast_bridge_lock_both(bridge1, bridge2)          \
573         do {                                                                                    \
574                 for (;;) {                                                                      \
575                         ast_bridge_lock(bridge1);                               \
576                         if (!ast_bridge_trylock(bridge2)) {             \
577                                 break;                                                          \
578                         }                                                                               \
579                         ast_bridge_unlock(bridge1);                             \
580                         sched_yield();                                                  \
581                 }                                                                                       \
582         } while (0)
583
584 /*!
585  * \brief Destroy a bridge
586  *
587  * \param bridge Bridge to destroy
588  *
589  * \retval 0 on success
590  * \retval -1 on failure
591  *
592  * Example usage:
593  *
594  * \code
595  * ast_bridge_destroy(bridge);
596  * \endcode
597  *
598  * This destroys a bridge that was previously created.
599  */
600 int ast_bridge_destroy(struct ast_bridge *bridge);
601
602 /*!
603  * \brief Notify bridging that this channel was just masqueraded.
604  * \since 12.0.0
605  *
606  * \param chan Channel just involved in a masquerade
607  *
608  * \return Nothing
609  */
610 void ast_bridge_notify_masquerade(struct ast_channel *chan);
611
612 /*!
613  * \brief Join (blocking) a channel to a bridge
614  *
615  * \param bridge Bridge to join
616  * \param chan Channel to join
617  * \param swap Channel to swap out if swapping
618  * \param features Bridge features structure
619  * \param tech_args Optional Bridging tech optimization parameters for this channel.
620  * \param pass_reference TRUE if the bridge reference is being passed by the caller.
621  *
622  * \note Absolutely _NO_ locks should be held before calling
623  * this function since it blocks.
624  *
625  * \retval state that channel exited the bridge with
626  *
627  * Example usage:
628  *
629  * \code
630  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, 0);
631  * \endcode
632  *
633  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
634  * the bridge pointer. This function will not return until the channel has been
635  * removed from the bridge, swapped out for another channel, or has hung up.
636  *
637  * If this channel will be replacing another channel the other channel can be specified
638  * in the swap parameter. The other channel will be thrown out of the bridge in an
639  * atomic fashion.
640  *
641  * If channel specific features are enabled a pointer to the features structure
642  * can be specified in the features parameter.
643  */
644 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
645         struct ast_channel *chan,
646         struct ast_channel *swap,
647         struct ast_bridge_features *features,
648         struct ast_bridge_tech_optimizations *tech_args,
649         int pass_reference);
650
651 /*!
652  * \brief Impart (non-blocking) a channel onto a bridge
653  *
654  * \param bridge Bridge to impart on
655  * \param chan Channel to impart
656  * \param swap Channel to swap out if swapping.  NULL if not swapping.
657  * \param features Bridge features structure.
658  * \param independent TRUE if caller does not want to reclaim the channel using ast_bridge_depart().
659  *
660  * \note The features parameter must be NULL or obtained by
661  * ast_bridge_features_new().  You must not dereference features
662  * after calling even if the call fails.
663  *
664  * \note chan is locked by this function.
665  *
666  * \retval 0 on success
667  * \retval -1 on failure
668  *
669  * Example usage:
670  *
671  * \code
672  * ast_bridge_impart(bridge, chan, NULL, NULL, 0);
673  * \endcode
674  *
675  * \details
676  * This adds a channel pointed to by the chan pointer to the
677  * bridge pointed to by the bridge pointer.  This function will
678  * return immediately and will not wait until the channel is no
679  * longer part of the bridge.
680  *
681  * If this channel will be replacing another channel the other
682  * channel can be specified in the swap parameter.  The other
683  * channel will be thrown out of the bridge in an atomic
684  * fashion.
685  *
686  * If channel specific features are enabled, a pointer to the
687  * features structure can be specified in the features
688  * parameter.
689  *
690  * \note If you impart a channel as not independent you MUST
691  * ast_bridge_depart() the channel if this call succeeds.  The
692  * bridge channel thread is created join-able.  The implication
693  * is that the channel is special and will not behave like a
694  * normal channel.
695  *
696  * \note If you impart a channel as independent you must not
697  * ast_bridge_depart() the channel.  The bridge channel thread
698  * is created non-join-able.  The channel must be treated as if
699  * it were placed into the bridge by ast_bridge_join().
700  * Channels placed into a bridge by ast_bridge_join() are
701  * removed by a third party using ast_bridge_remove().
702  */
703 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features, int independent);
704
705 /*!
706  * \brief Depart a channel from a bridge
707  *
708  * \param chan Channel to depart
709  *
710  * \note chan is locked by this function.
711  *
712  * \retval 0 on success
713  * \retval -1 on failure
714  *
715  * Example usage:
716  *
717  * \code
718  * ast_bridge_depart(chan);
719  * \endcode
720  *
721  * This removes the channel pointed to by the chan pointer from any bridge
722  * it may be in and gives control to the calling thread.
723  * This does not hang up the channel.
724  *
725  * \note This API call can only be used on channels that were added to the bridge
726  *       using the ast_bridge_impart API call with the independent flag FALSE.
727  */
728 int ast_bridge_depart(struct ast_channel *chan);
729
730 /*!
731  * \brief Remove a channel from a bridge
732  *
733  * \param bridge Bridge that the channel is to be removed from
734  * \param chan Channel to remove
735  *
736  * \retval 0 on success
737  * \retval -1 on failure
738  *
739  * Example usage:
740  *
741  * \code
742  * ast_bridge_remove(bridge, chan);
743  * \endcode
744  *
745  * This removes the channel pointed to by the chan pointer from the bridge
746  * pointed to by the bridge pointer and requests that it be hung up. Control
747  * over the channel will NOT be given to the calling thread.
748  *
749  * \note This API call can be used on channels that were added to the bridge
750  *       using both ast_bridge_join and ast_bridge_impart.
751  */
752 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
753
754 /*!
755  * \brief Merge two bridges together
756  *
757  * \param dst_bridge Destination bridge of merge.
758  * \param src_bridge Source bridge of merge.
759  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
760  * \param kick_me Array of channels to kick from the bridges.
761  * \param num_kick Number of channels in the kick_me array.
762  *
763  * \note Absolutely _NO_ bridge or channel locks should be held
764  * before calling this function.
765  *
766  * \retval 0 on success
767  * \retval -1 on failure
768  *
769  * Example usage:
770  *
771  * \code
772  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
773  * \endcode
774  *
775  * This moves the channels in src_bridge into the bridge pointed
776  * to by dst_bridge.
777  */
778 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);
779
780 /*!
781  * \brief Move a channel from one bridge to another.
782  * \since 12.0.0
783  *
784  * \param dst_bridge Destination bridge of bridge channel move.
785  * \param src_bridge Source bridge of bridge channel move.
786  * \param chan Channel to move.
787  * \param swap Channel to replace in dst_bridge.
788  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
789  *
790  * \note Absolutely _NO_ bridge or channel locks should be held
791  * before calling this function.
792  *
793  * \retval 0 on success.
794  * \retval -1 on failure.
795  */
796 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);
797
798 /*!
799  * \brief Adjust the bridge merge inhibit request count.
800  * \since 12.0.0
801  *
802  * \param bridge What to operate on.
803  * \param request Inhibit request increment.
804  *     (Positive to add requests.  Negative to remove requests.)
805  *
806  * \return Nothing
807  */
808 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
809
810 /*!
811  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
812  * \since 12.0.0
813  *
814  * \param bridge_channel What to operate on.
815  * \param request Inhibit request increment.
816  *     (Positive to add requests.  Negative to remove requests.)
817  *
818  * \note This API call is meant for internal bridging operations.
819  *
820  * \retval bridge adjusted merge inhibit with reference count.
821  */
822 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
823
824 /*!
825  * \brief Suspend a channel temporarily from a bridge
826  *
827  * \param bridge Bridge to suspend the channel from
828  * \param chan Channel to suspend
829  *
830  * \retval 0 on success
831  * \retval -1 on failure
832  *
833  * Example usage:
834  *
835  * \code
836  * ast_bridge_suspend(bridge, chan);
837  * \endcode
838  *
839  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
840  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
841  * the channel will not be removed from the bridge.
842  *
843  * \note This API call can be used on channels that were added to the bridge
844  *       using both ast_bridge_join and ast_bridge_impart.
845  */
846 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
847
848 /*!
849  * \brief Unsuspend a channel from a bridge
850  *
851  * \param bridge Bridge to unsuspend the channel from
852  * \param chan Channel to unsuspend
853  *
854  * \retval 0 on success
855  * \retval -1 on failure
856  *
857  * Example usage:
858  *
859  * \code
860  * ast_bridge_unsuspend(bridge, chan);
861  * \endcode
862  *
863  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
864  * The bridge will go back to handling the channel once this function returns.
865  *
866  * \note You must not mess with the channel once this function returns.
867  *       Doing so may result in bad things happening.
868  */
869 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
870
871 /*!
872  * \brief Check and optimize out the unreal channels between bridges.
873  * \since 12.0.0
874  *
875  * \param chan Unreal channel writing a frame into the channel driver.
876  * \param peer Other unreal channel in the pair.
877  *
878  * \note It is assumed that chan is already locked.
879  *
880  * \retval 0 if unreal channels were not optimized out.
881  * \retval non-zero if unreal channels were optimized out.
882  */
883 int ast_bridge_unreal_optimized_out(struct ast_channel *chan, struct ast_channel *peer);
884
885 /*!
886  * \brief Tells, if optimization is allowed, how the optimization would be performed
887  */
888 enum ast_bridge_optimization {
889         /*! Optimization would swap peer into the chan_bridge */
890         AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
891         /*! Optimization would swap chan into the peer_bridge */
892         AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
893         /*! Optimization would merge peer_bridge into chan_bridge */
894         AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
895         /*! Optimization would merge chan_bridge into peer_bridge */
896         AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
897         /*! Optimization is not permitted on one or both bridges */
898         AST_BRIDGE_OPTIMIZE_PROHIBITED,
899 };
900
901 /*!
902  * \brief Determine if bridges allow for optimization to occur betweem them
903  * \since 12.0.0
904  *
905  * \param chan_bridge First bridge being tested
906  * \param peer_bridge Second bridge being tested
907  *
908  * This determines if two bridges allow for unreal channel optimization
909  * to occur between them. The function does not require for unreal channels
910  * to already be in the bridges when called.
911  *
912  * \note It is assumed that both bridges are locked prior to calling this function
913  *
914  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
915  * that an optimization attempt will succeed. However, a return of
916  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
917  * never succeed.
918  *
919  * \returns Optimization allowability for the bridges
920  */
921 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
922                 struct ast_bridge *peer_bridge);
923
924 /*!
925  * \brief Try locking the bridge_channel.
926  *
927  * \param bridge_channel What to try locking
928  *
929  * \retval 0 on success.
930  * \retval non-zero on error.
931  */
932 #define ast_bridge_channel_trylock(bridge_channel)      _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
933 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
934 {
935         return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
936 }
937
938 /*!
939  * \brief Lock the bridge_channel.
940  *
941  * \param bridge_channel What to lock
942  *
943  * \return Nothing
944  */
945 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
946 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
947 {
948         __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
949 }
950
951 /*!
952  * \brief Unlock the bridge_channel.
953  *
954  * \param bridge_channel What to unlock
955  *
956  * \return Nothing
957  */
958 #define ast_bridge_channel_unlock(bridge_channel)       _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
959 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
960 {
961         __ao2_unlock(bridge_channel, file, function, line, var);
962 }
963
964 /*!
965  * \brief Lock the bridge associated with the bridge channel.
966  * \since 12.0.0
967  *
968  * \param bridge_channel Channel that wants to lock the bridge.
969  *
970  * \details
971  * This is an upstream lock operation.  The defined locking
972  * order is bridge then bridge_channel.
973  *
974  * \note On entry, neither the bridge nor bridge_channel is locked.
975  *
976  * \note The bridge_channel->bridge pointer changes because of a
977  * bridge-merge/channel-move operation between bridges.
978  *
979  * \return Nothing
980  */
981 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
982
983 /*!
984  * \brief Set bridge channel state to leave bridge (if not leaving already) with no lock.
985  *
986  * \param bridge_channel Channel to change the state on
987  * \param new_state The new state to place the channel into
988  *
989  * \note This API call is only meant to be used within the
990  * bridging module and hook callbacks to request the channel
991  * exit the bridge.
992  *
993  * \note This function assumes the bridge_channel is locked.
994  */
995 void ast_bridge_change_state_nolock(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
996
997 /*!
998  * \brief Set bridge channel state to leave bridge (if not leaving already).
999  *
1000  * \param bridge_channel Channel to change the state on
1001  * \param new_state The new state to place the channel into
1002  *
1003  * Example usage:
1004  *
1005  * \code
1006  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);
1007  * \endcode
1008  *
1009  * This places the channel pointed to by bridge_channel into the
1010  * state AST_BRIDGE_CHANNEL_STATE_HANGUP if it was
1011  * AST_BRIDGE_CHANNEL_STATE_WAIT before.
1012  *
1013  * \note This API call is only meant to be used within the
1014  * bridging module and hook callbacks to request the channel
1015  * exit the bridge.
1016  */
1017 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
1018
1019 /*!
1020  * \brief Put an action onto the specified bridge.
1021  * \since 12.0.0
1022  *
1023  * \param bridge What to queue the action on.
1024  * \param action What to do.
1025  *
1026  * \retval 0 on success.
1027  * \retval -1 on error.
1028  *
1029  * \note This API call is meant for internal bridging operations.
1030  * \note BUGBUG This may get moved.
1031  */
1032 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
1033
1034 /*!
1035  * \brief Write a frame to the specified bridge_channel.
1036  * \since 12.0.0
1037  *
1038  * \param bridge_channel Channel to queue the frame.
1039  * \param fr Frame to write.
1040  *
1041  * \retval 0 on success.
1042  * \retval -1 on error.
1043  *
1044  * \note This API call is meant for internal bridging operations.
1045  * \note BUGBUG This may get moved.
1046  */
1047 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
1048
1049 /*!
1050  * \brief Used to queue an action frame onto a bridge channel and write an action frame into a bridge.
1051  * \since 12.0.0
1052  *
1053  * \param bridge_channel Which channel work with.
1054  * \param action Type of bridge action frame.
1055  * \param data Frame payload data to pass.
1056  * \param datalen Frame payload data length to pass.
1057  *
1058  * \return Nothing
1059  */
1060 typedef void (*ast_bridge_channel_post_action_data)(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1061
1062 /*!
1063  * \brief Queue an action frame onto the bridge channel with data.
1064  * \since 12.0.0
1065  *
1066  * \param bridge_channel Which channel to queue the frame onto.
1067  * \param action Type of bridge action frame.
1068  * \param data Frame payload data to pass.
1069  * \param datalen Frame payload data length to pass.
1070  *
1071  * \return Nothing
1072  */
1073 void ast_bridge_channel_queue_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1074
1075 /*!
1076  * \brief Write an action frame into the bridge with data.
1077  * \since 12.0.0
1078  *
1079  * \param bridge_channel Which channel is putting the frame into the bridge.
1080  * \param action Type of bridge action frame.
1081  * \param data Frame payload data to pass.
1082  * \param datalen Frame payload data length to pass.
1083  *
1084  * \return Nothing
1085  */
1086 void ast_bridge_channel_write_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1087
1088 /*!
1089  * \brief Queue a control frame onto the bridge channel with data.
1090  * \since 12.0.0
1091  *
1092  * \param bridge_channel Which channel to queue the frame onto.
1093  * \param control Type of control frame.
1094  * \param data Frame payload data to pass.
1095  * \param datalen Frame payload data length to pass.
1096  *
1097  * \return Nothing
1098  */
1099 void ast_bridge_channel_queue_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
1100
1101 /*!
1102  * \brief Write a control frame into the bridge with data.
1103  * \since 12.0.0
1104  *
1105  * \param bridge_channel Which channel is putting the frame into the bridge.
1106  * \param control Type of control frame.
1107  * \param data Frame payload data to pass.
1108  * \param datalen Frame payload data length to pass.
1109  *
1110  * \return Nothing
1111  */
1112 void ast_bridge_channel_write_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
1113
1114 /*!
1115  * \brief Write a hold frame into the bridge.
1116  * \since 12.0.0
1117  *
1118  * \param bridge_channel Which channel is putting the hold into the bridge.
1119  * \param moh_class The suggested music class for the other end to use.
1120  *
1121  * \return Nothing
1122  */
1123 void ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
1124
1125 /*!
1126  * \brief Write an unhold frame into the bridge.
1127  * \since 12.0.0
1128  *
1129  * \param bridge_channel Which channel is putting the hold into the bridge.
1130  *
1131  * \return Nothing
1132  */
1133 void ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
1134
1135 /*!
1136  * \brief Run an application on the bridge channel.
1137  * \since 12.0.0
1138  *
1139  * \param bridge_channel Which channel to run the application on.
1140  * \param app_name Dialplan application name.
1141  * \param app_args Arguments for the application. (NULL tolerant)
1142  * \param moh_class MOH class to request bridge peers to hear while application is running.
1143  *     NULL if no MOH.
1144  *     Empty if default MOH class.
1145  *
1146  * \note This is intended to be called by bridge hooks.
1147  *
1148  * \return Nothing
1149  */
1150 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1151
1152 /*!
1153  * \brief Write a bridge action run application frame into the bridge.
1154  * \since 12.0.0
1155  *
1156  * \param bridge_channel Which channel is putting the frame into the bridge
1157  * \param app_name Dialplan application name.
1158  * \param app_args Arguments for the application. (NULL or empty for no arguments)
1159  * \param moh_class MOH class to request bridge peers to hear while application is running.
1160  *     NULL if no MOH.
1161  *     Empty if default MOH class.
1162  *
1163  * \note This is intended to be called by bridge hooks.
1164  *
1165  * \return Nothing
1166  */
1167 void ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1168
1169 /*!
1170  * \brief Queue a bridge action run application frame onto the bridge channel.
1171  * \since 12.0.0
1172  *
1173  * \param bridge_channel Which channel to put the frame onto
1174  * \param app_name Dialplan application name.
1175  * \param app_args Arguments for the application. (NULL or empty for no arguments)
1176  * \param moh_class MOH class to request bridge peers to hear while application is running.
1177  *     NULL if no MOH.
1178  *     Empty if default MOH class.
1179  *
1180  * \note This is intended to be called by bridge hooks.
1181  *
1182  * \return Nothing
1183  */
1184 void ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1185
1186 /*!
1187  * \brief Custom interpretation of the playfile name.
1188  *
1189  * \param bridge_channel Which channel to play the file on
1190  * \param playfile Sound filename to play.
1191  *
1192  * \return Nothing
1193  */
1194 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
1195
1196 /*!
1197  * \brief Play a file on the bridge channel.
1198  * \since 12.0.0
1199  *
1200  * \param bridge_channel Which channel to play the file on
1201  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1202  * \param playfile Sound filename to play.
1203  * \param moh_class MOH class to request bridge peers to hear while file is played.
1204  *     NULL if no MOH.
1205  *     Empty if default MOH class.
1206  *
1207  * \note This is intended to be called by bridge hooks.
1208  *
1209  * \return Nothing
1210  */
1211 void ast_bridge_channel_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
1212
1213 /*!
1214  * \brief Write a bridge action play file frame into the bridge.
1215  * \since 12.0.0
1216  *
1217  * \param bridge_channel Which channel is putting the frame into the bridge
1218  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1219  * \param playfile Sound filename to play.
1220  * \param moh_class MOH class to request bridge peers to hear while file is played.
1221  *     NULL if no MOH.
1222  *     Empty if default MOH class.
1223  *
1224  * \note This is intended to be called by bridge hooks.
1225  *
1226  * \return Nothing
1227  */
1228 void ast_bridge_channel_write_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
1229
1230 /*!
1231  * \brief Queue a bridge action play file frame onto the bridge channel.
1232  * \since 12.0.0
1233  *
1234  * \param bridge_channel Which channel to put the frame onto.
1235  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1236  * \param playfile Sound filename to play.
1237  * \param moh_class MOH class to request bridge peers to hear while file is played.
1238  *     NULL if no MOH.
1239  *     Empty if default MOH class.
1240  *
1241  * \note This is intended to be called by bridge hooks.
1242  *
1243  * \return Nothing
1244  */
1245 void ast_bridge_channel_queue_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
1246
1247 /*!
1248  * \brief Custom callback run on a bridge channel.
1249  *
1250  * \param bridge_channel Which channel to operate on.
1251  * \param payload Data to pass to the callback. (NULL if none).
1252  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1253  *
1254  * \note The payload MUST NOT have any resources that need to be freed.
1255  *
1256  * \return Nothing
1257  */
1258 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
1259
1260 /*!
1261  * \brief Write a bridge action custom callback frame into the bridge.
1262  * \since 12.0.0
1263  *
1264  * \param bridge_channel Which channel is putting the frame into the bridge
1265  * \param callback Custom callback run on a bridge channel.
1266  * \param payload Data to pass to the callback. (NULL if none).
1267  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1268  *
1269  * \note The payload MUST NOT have any resources that need to be freed.
1270  *
1271  * \note This is intended to be called by bridge hooks.
1272  *
1273  * \return Nothing
1274  */
1275 void ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
1276
1277 /*!
1278  * \brief Queue a bridge action custom callback frame onto the bridge channel.
1279  * \since 12.0.0
1280  *
1281  * \param bridge_channel Which channel to put the frame onto.
1282  * \param callback Custom callback run on a bridge channel.
1283  * \param payload Data to pass to the callback. (NULL if none).
1284  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1285  *
1286  * \note The payload MUST NOT have any resources that need to be freed.
1287  *
1288  * \note This is intended to be called by bridge hooks.
1289  *
1290  * \return Nothing
1291  */
1292 void ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
1293
1294 /*!
1295  * \brief Have a bridge channel park a channel in the bridge
1296  * \since 12.0.0
1297  *
1298  * \param bridge_channel Bridge channel performing the parking
1299  * \param parkee_uuid Unique id of the channel we want to park
1300  * \param parker_uuid Unique id of the channel parking the call
1301  * \param app_data string indicating data used for park application (NULL allowed)
1302  *
1303  * \note This is intended to be called by bridge hooks.
1304  *
1305  * \return Nothing
1306  */
1307 void ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
1308         const char *parker_uuid, const char *app_data);
1309
1310 /*!
1311  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_join
1312  * \since 12.0.0
1313  *
1314  * \param bridge_channel Channel to restore
1315  */
1316 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
1317
1318 /*!
1319  * \brief Get the peer bridge channel of a two party bridge.
1320  * \since 12.0.0
1321  *
1322  * \param bridge_channel What to get the peer of.
1323  *
1324  * \note On entry, bridge_channel->bridge is already locked.
1325  *
1326  * \note This is an internal bridge function.
1327  *
1328  * \retval peer on success.
1329  * \retval NULL no peer channel.
1330  */
1331 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
1332
1333 /*!
1334  * \brief Adjust the internal mixing sample rate of a bridge
1335  * used during multimix mode.
1336  *
1337  * \param bridge Channel to change the sample rate on.
1338  * \param sample_rate the sample rate to change to. If a
1339  *        value of 0 is passed here, the bridge will be free to pick
1340  *        what ever sample rate it chooses.
1341  *
1342  */
1343 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
1344
1345 /*!
1346  * \brief Adjust the internal mixing interval of a bridge used
1347  * during multimix mode.
1348  *
1349  * \param bridge Channel to change the sample rate on.
1350  * \param mixing_interval the sample rate to change to.  If 0 is set
1351  * the bridge tech is free to choose any mixing interval it uses by default.
1352  */
1353 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
1354
1355 /*!
1356  * \brief Set a bridge to feed a single video source to all participants.
1357  */
1358 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
1359
1360 /*!
1361  * \brief Set the bridge to pick the strongest talker supporting
1362  * video as the single source video feed
1363  */
1364 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
1365
1366 /*!
1367  * \brief Update information about talker energy for talker src video mode.
1368  */
1369 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
1370
1371 /*!
1372  * \brief Returns the number of video sources currently active in the bridge
1373  */
1374 int ast_bridge_number_video_src(struct ast_bridge *bridge);
1375
1376 /*!
1377  * \brief Determine if a channel is a video src for the bridge
1378  *
1379  * \retval 0 Not a current video source of the bridge.
1380  * \retval None 0, is a video source of the bridge, The number
1381  *         returned represents the priority this video stream has
1382  *         on the bridge where 1 is the highest priority.
1383  */
1384 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
1385
1386 /*!
1387  * \brief remove a channel as a source of video for the bridge.
1388  */
1389 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
1390
1391 enum ast_transfer_result {
1392         /*! The transfer completed successfully */
1393         AST_BRIDGE_TRANSFER_SUCCESS,
1394         /*! A bridge involved does not permit transferring */
1395         AST_BRIDGE_TRANSFER_NOT_PERMITTED,
1396         /*! The current bridge setup makes transferring an invalid operation */
1397         AST_BRIDGE_TRANSFER_INVALID,
1398         /*! The transfer operation failed for a miscellaneous reason */
1399         AST_BRIDGE_TRANSFER_FAIL,
1400 };
1401
1402 enum ast_transfer_type {
1403         /*! Transfer of a single party */
1404         AST_BRIDGE_TRANSFER_SINGLE_PARTY,
1405         /*! Transfer of multiple parties */
1406         AST_BRIDGE_TRANSFER_MULTI_PARTY,
1407 };
1408
1409 /*!
1410  * \brief Callback function type called during blind transfers
1411  *
1412  * A caller of ast_bridge_transfer_blind() may wish to set data on
1413  * the channel that ends up running dialplan. For instance, it may
1414  * be useful to set channel variables on the channel.
1415  *
1416  * \param chan The involved channel
1417  * \param user_data User-provided data needed in the callback
1418  * \param transfer_type The type of transfer being completed
1419  */
1420 typedef void (*transfer_channel_cb)(struct ast_channel *chan, void *user_data,
1421                 enum ast_transfer_type transfer_type);
1422
1423 /*!
1424  * \brief Blind transfer target to the extension and context provided
1425  *
1426  * The channel given is bridged to one or multiple channels. Depending on
1427  * the bridge and the number of participants, the entire bridge could be
1428  * transferred to the given destination, or a single channel may be redirected.
1429  *
1430  * Callers may also provide a callback to be called on the channel that will
1431  * be running dialplan. The user data passed into ast_bridge_transfer_blind
1432  * will be given as the argument to the callback to be interpreted as desired.
1433  * This callback is guaranteed to be called in the same thread as
1434  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
1435  *
1436  * \note Absolutely _NO_ channel locks should be held before
1437  * calling this function.
1438  *
1439  * \param transferer The channel performing the blind transfer
1440  * \param exten The dialplan extension to send the call to
1441  * \param context The dialplan context to send the call to
1442  * \param new_channel_cb A callback to be called on the channel that will
1443  *        be executing dialplan
1444  * \param user_data Argument for new_channel_cb
1445  * \return The success or failure result of the blind transfer
1446  */
1447 enum ast_transfer_result ast_bridge_transfer_blind(struct ast_channel *transferer,
1448                 const char *exten, const char *context,
1449                 transfer_channel_cb new_channel_cb, void *user_data);
1450
1451 /*!
1452  * \brief Attended transfer
1453  *
1454  * The two channels are both transferer channels. The first is the channel
1455  * that is bridged to the transferee (or if unbridged, the 'first' call of
1456  * the transfer). The second is the channel that is bridged to the transfer
1457  * target (or if unbridged, the 'second' call of the transfer).
1458  *
1459  * \note Absolutely _NO_ channel locks should be held before
1460  * calling this function.
1461  *
1462  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
1463  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
1464  * \return The success or failure of the attended transfer
1465  */
1466 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
1467                 struct ast_channel *to_transfer_target);
1468 /*!
1469  * \brief Set channel to goto specific location after the bridge.
1470  * \since 12.0.0
1471  *
1472  * \param chan Channel to setup after bridge goto location.
1473  * \param context Context to goto after bridge.
1474  * \param exten Exten to goto after bridge.
1475  * \param priority Priority to goto after bridge.
1476  *
1477  * \note chan is locked by this function.
1478  *
1479  * \details Add a channel datastore to setup the goto location
1480  * when the channel leaves the bridge and run a PBX from there.
1481  *
1482  * \return Nothing
1483  */
1484 void ast_after_bridge_set_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1485
1486 /*!
1487  * \brief Set channel to run the h exten after the bridge.
1488  * \since 12.0.0
1489  *
1490  * \param chan Channel to setup after bridge goto location.
1491  * \param context Context to goto after bridge.
1492  *
1493  * \note chan is locked by this function.
1494  *
1495  * \details Add a channel datastore to setup the goto location
1496  * when the channel leaves the bridge and run a PBX from there.
1497  *
1498  * \return Nothing
1499  */
1500 void ast_after_bridge_set_h(struct ast_channel *chan, const char *context);
1501
1502 /*!
1503  * \brief Set channel to go on in the dialplan after the bridge.
1504  * \since 12.0.0
1505  *
1506  * \param chan Channel to setup after bridge goto location.
1507  * \param context Current context of the caller channel.
1508  * \param exten Current exten of the caller channel.
1509  * \param priority Current priority of the caller channel
1510  * \param parseable_goto User specified goto string from dialplan.
1511  *
1512  * \note chan is locked by this function.
1513  *
1514  * \details Add a channel datastore to setup the goto location
1515  * when the channel leaves the bridge and run a PBX from there.
1516  *
1517  * If parseable_goto then use the given context/exten/priority
1518  *   as the relative position for the parseable_goto.
1519  * Else goto the given context/exten/priority+1.
1520  *
1521  * \return Nothing
1522  */
1523 void ast_after_bridge_set_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto);
1524
1525 /*!
1526  * \brief Setup any after bridge goto location to begin execution.
1527  * \since 12.0.0
1528  *
1529  * \param chan Channel to setup after bridge goto location.
1530  *
1531  * \note chan is locked by this function.
1532  *
1533  * \details Pull off any after bridge goto location datastore and
1534  * setup for dialplan execution there.
1535  *
1536  * \retval 0 on success.  The goto location is set for a PBX to run it.
1537  * \retval non-zero on error or no goto location.
1538  *
1539  * \note If the after bridge goto is set to run an h exten it is
1540  * run here immediately.
1541  */
1542 int ast_after_bridge_goto_setup(struct ast_channel *chan);
1543
1544 /*!
1545  * \brief Run a PBX on any after bridge goto location.
1546  * \since 12.0.0
1547  *
1548  * \param chan Channel to execute after bridge goto location.
1549  *
1550  * \note chan is locked by this function.
1551  *
1552  * \details Pull off any after bridge goto location datastore
1553  * and run a PBX at that location.
1554  *
1555  * \note On return, the chan pointer is no longer valid because
1556  * the channel has hung up.
1557  *
1558  * \return Nothing
1559  */
1560 void ast_after_bridge_goto_run(struct ast_channel *chan);
1561
1562 /*!
1563  * \brief Discard channel after bridge goto location.
1564  * \since 12.0.0
1565  *
1566  * \param chan Channel to discard after bridge goto location.
1567  *
1568  * \note chan is locked by this function.
1569  *
1570  * \return Nothing
1571  */
1572 void ast_after_bridge_goto_discard(struct ast_channel *chan);
1573
1574 /*! Reason the the after bridge callback will not be called. */
1575 enum ast_after_bridge_cb_reason {
1576         /*! The datastore is being destroyed.  Likely due to hangup. */
1577         AST_AFTER_BRIDGE_CB_REASON_DESTROY,
1578         /*! Something else replaced the callback with another. */
1579         AST_AFTER_BRIDGE_CB_REASON_REPLACED,
1580         /*! The callback was removed because of a masquerade. (fixup) */
1581         AST_AFTER_BRIDGE_CB_REASON_MASQUERADE,
1582         /*! The channel departed bridge. */
1583         AST_AFTER_BRIDGE_CB_REASON_DEPART,
1584         /*! Was explicitly removed by external code. */
1585         AST_AFTER_BRIDGE_CB_REASON_REMOVED,
1586 };
1587
1588 /*!
1589  * \brief After bridge callback failed.
1590  * \since 12.0.0
1591  *
1592  * \param reason Reason callback is failing.
1593  * \param data Extra data what setup the callback wanted to pass.
1594  *
1595  * \return Nothing
1596  */
1597 typedef void (*ast_after_bridge_cb_failed)(enum ast_after_bridge_cb_reason reason, void *data);
1598
1599 /*!
1600  * \brief After bridge callback function.
1601  * \since 12.0.0
1602  *
1603  * \param chan Channel just leaving bridging system.
1604  * \param data Extra data what setup the callback wanted to pass.
1605  *
1606  * \return Nothing
1607  */
1608 typedef void (*ast_after_bridge_cb)(struct ast_channel *chan, void *data);
1609
1610 /*!
1611  * \brief Discard channel after bridge callback.
1612  * \since 12.0.0
1613  *
1614  * \param chan Channel to discard after bridge callback.
1615  * \param reason Why are we doing this.
1616  *
1617  * \note chan is locked by this function.
1618  *
1619  * \return Nothing
1620  */
1621 void ast_after_bridge_callback_discard(struct ast_channel *chan, enum ast_after_bridge_cb_reason reason);
1622
1623 /*!
1624  * \brief Setup an after bridge callback for when the channel leaves the bridging system.
1625  * \since 12.0.0
1626  *
1627  * \param chan Channel to setup an after bridge callback on.
1628  * \param callback Function to call when the channel leaves the bridging system.
1629  * \param failed Function to call when it will not be calling the callback.
1630  * \param data Extra data to pass with the callback.
1631  *
1632  * \note chan is locked by this function.
1633  *
1634  * \retval 0 on success.
1635  * \retval -1 on error.
1636  */
1637 int ast_after_bridge_callback_set(struct ast_channel *chan, ast_after_bridge_cb callback, ast_after_bridge_cb_failed failed, void *data);
1638
1639 /*!
1640  * \brief Get a string representation of an after bridge callback reason
1641  * \since 12.0.0
1642  *
1643  * \param reason The reason to interpret to a string
1644  * \retval NULL Unrecognized reason
1645  * \retval non-NULL String representation of reason
1646  */
1647 const char *ast_after_bridge_cb_reason_string(enum ast_after_bridge_cb_reason reason);
1648
1649 /*!
1650  * \brief Get a container of all channels in the bridge
1651  * \since 12.0.0
1652  *
1653  * \param bridge The bridge which is already locked.
1654  *
1655  * \retval NULL Failed to create container
1656  * \retval non-NULL Container of channels in the bridge
1657  */
1658 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
1659
1660 /*!
1661  * \brief Get a container of all channels in the bridge
1662  * \since 12.0.0
1663  *
1664  * \param bridge The bridge
1665  *
1666  * \note The returned container is a snapshot of channels in the
1667  * bridge when called.
1668  *
1669  * \retval NULL Failed to create container
1670  * \retval non-NULL Container of channels in the bridge
1671  */
1672 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
1673
1674 /*!
1675  * \brief Get the channel's bridge peer only if the bridge is two-party.
1676  * \since 12.0.0
1677  *
1678  * \param bridge The bridge which is already locked.
1679  * \param chan Channel desiring the bridge peer channel.
1680  *
1681  * \note The returned peer channel is the current peer in the
1682  * bridge when called.
1683  *
1684  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1685  * \retval non-NULL Reffed peer channel at time of calling.
1686  */
1687 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
1688
1689 /*!
1690  * \brief Get the channel's bridge peer only if the bridge is two-party.
1691  * \since 12.0.0
1692  *
1693  * \param bridge The bridge
1694  * \param chan Channel desiring the bridge peer channel.
1695  *
1696  * \note The returned peer channel is the current peer in the
1697  * bridge when called.
1698  *
1699  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1700  * \retval non-NULL Reffed peer channel at time of calling.
1701  */
1702 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
1703
1704 #if defined(__cplusplus) || defined(c_plusplus)
1705 }
1706 #endif
1707
1708 #endif  /* _ASTERISK_BRIDGING_H */