e03bfd0cdbb65e4d74b5dac237915aa27196d050
[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         /*! TRUE if the bridge construction was completed. */
440         unsigned int construction_completed:1;
441 };
442
443 /*!
444  * \brief Register the new bridge with the system.
445  * \since 12.0.0
446  *
447  * \param bridge What to register. (Tolerates a NULL pointer)
448  *
449  * \code
450  * struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
451  * {
452  *     void *bridge;
453  *
454  *     bridge = ast_bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
455  *     bridge = ast_bridge_base_init(bridge, capabilities, flags);
456  *     bridge = ast_bridge_basic_init(bridge, dtmf_features);
457  *     bridge = ast_bridge_register(bridge);
458  *     return bridge;
459  * }
460  * \endcode
461  *
462  * \note This must be done after a bridge constructor has
463  * completed setting up the new bridge but before it returns.
464  *
465  * \note After a bridge is registered, ast_bridge_destroy() must
466  * eventually be called to get rid of the bridge.
467  *
468  * \retval bridge on success.
469  * \retval NULL on error.
470  */
471 struct ast_bridge *ast_bridge_register(struct ast_bridge *bridge);
472
473 /*!
474  * \internal
475  * \brief Allocate the bridge class object memory.
476  * \since 12.0.0
477  *
478  * \param size Size of the bridge class structure to allocate.
479  * \param v_table Bridge class virtual method table.
480  *
481  * \retval bridge on success.
482  * \retval NULL on error.
483  */
484 struct ast_bridge *ast_bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
485
486 /*! \brief Bridge base class virtual method table. */
487 extern struct ast_bridge_methods ast_bridge_base_v_table;
488
489 /*!
490  * \brief Initialize the base class of the bridge.
491  *
492  * \param self Bridge to operate upon. (Tolerates a NULL pointer)
493  * \param capabilities The capabilities that we require to be used on the bridge
494  * \param flags Flags that will alter the behavior of the bridge
495  *
496  * \retval self on success
497  * \retval NULL on failure, self is already destroyed
498  *
499  * Example usage:
500  *
501  * \code
502  * struct ast_bridge *bridge;
503  * bridge = ast_bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
504  * bridge = ast_bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
505  * \endcode
506  *
507  * This creates a no frills two party bridge that will be
508  * destroyed once one of the channels hangs up.
509  */
510 struct ast_bridge *ast_bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags);
511
512 /*!
513  * \brief Create a new base class bridge
514  *
515  * \param capabilities The capabilities that we require to be used on the bridge
516  * \param flags Flags that will alter the behavior of the bridge
517  *
518  * \retval a pointer to a new bridge on success
519  * \retval NULL on failure
520  *
521  * Example usage:
522  *
523  * \code
524  * struct ast_bridge *bridge;
525  * bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
526  * \endcode
527  *
528  * This creates a no frills two party bridge that will be
529  * destroyed once one of the channels hangs up.
530  */
531 struct ast_bridge *ast_bridge_base_new(uint32_t capabilities, unsigned int flags);
532
533 /*!
534  * \brief Try locking the bridge.
535  *
536  * \param bridge Bridge to try locking
537  *
538  * \retval 0 on success.
539  * \retval non-zero on error.
540  */
541 #define ast_bridge_trylock(bridge)      _ast_bridge_trylock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
542 static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
543 {
544         return __ao2_trylock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
545 }
546
547 /*!
548  * \brief Lock the bridge.
549  *
550  * \param bridge Bridge to lock
551  *
552  * \return Nothing
553  */
554 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
555 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
556 {
557         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
558 }
559
560 /*!
561  * \brief Unlock the bridge.
562  *
563  * \param bridge Bridge to unlock
564  *
565  * \return Nothing
566  */
567 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
568 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
569 {
570         __ao2_unlock(bridge, file, function, line, var);
571 }
572
573 /*! \brief Lock two bridges. */
574 #define ast_bridge_lock_both(bridge1, bridge2)          \
575         do {                                                                                    \
576                 for (;;) {                                                                      \
577                         ast_bridge_lock(bridge1);                               \
578                         if (!ast_bridge_trylock(bridge2)) {             \
579                                 break;                                                          \
580                         }                                                                               \
581                         ast_bridge_unlock(bridge1);                             \
582                         sched_yield();                                                  \
583                 }                                                                                       \
584         } while (0)
585
586 /*!
587  * \brief Destroy a bridge
588  *
589  * \param bridge Bridge to destroy
590  *
591  * \retval 0 on success
592  * \retval -1 on failure
593  *
594  * Example usage:
595  *
596  * \code
597  * ast_bridge_destroy(bridge);
598  * \endcode
599  *
600  * This destroys a bridge that was previously created.
601  */
602 int ast_bridge_destroy(struct ast_bridge *bridge);
603
604 /*!
605  * \brief Notify bridging that this channel was just masqueraded.
606  * \since 12.0.0
607  *
608  * \param chan Channel just involved in a masquerade
609  *
610  * \return Nothing
611  */
612 void ast_bridge_notify_masquerade(struct ast_channel *chan);
613
614 /*!
615  * \brief Join (blocking) a channel to a bridge
616  *
617  * \param bridge Bridge to join
618  * \param chan Channel to join
619  * \param swap Channel to swap out if swapping
620  * \param features Bridge features structure
621  * \param tech_args Optional Bridging tech optimization parameters for this channel.
622  * \param pass_reference TRUE if the bridge reference is being passed by the caller.
623  *
624  * \note Absolutely _NO_ locks should be held before calling
625  * this function since it blocks.
626  *
627  * \retval state that channel exited the bridge with
628  *
629  * Example usage:
630  *
631  * \code
632  * ast_bridge_join(bridge, chan, NULL, NULL, NULL, 0);
633  * \endcode
634  *
635  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
636  * the bridge pointer. This function will not return until the channel has been
637  * removed from the bridge, swapped out for another channel, or has hung up.
638  *
639  * If this channel will be replacing another channel the other channel can be specified
640  * in the swap parameter. The other channel will be thrown out of the bridge in an
641  * atomic fashion.
642  *
643  * If channel specific features are enabled a pointer to the features structure
644  * can be specified in the features parameter.
645  */
646 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
647         struct ast_channel *chan,
648         struct ast_channel *swap,
649         struct ast_bridge_features *features,
650         struct ast_bridge_tech_optimizations *tech_args,
651         int pass_reference);
652
653 /*!
654  * \brief Impart (non-blocking) a channel onto a bridge
655  *
656  * \param bridge Bridge to impart on
657  * \param chan Channel to impart (The channel reference is stolen if impart successful.)
658  * \param swap Channel to swap out if swapping.  NULL if not swapping.
659  * \param features Bridge features structure.
660  * \param independent TRUE if caller does not want to reclaim the channel using ast_bridge_depart().
661  *
662  * \note The features parameter must be NULL or obtained by
663  * ast_bridge_features_new().  You must not dereference features
664  * after calling even if the call fails.
665  *
666  * \note chan is locked by this function.
667  *
668  * \retval 0 on success
669  * \retval -1 on failure
670  *
671  * Example usage:
672  *
673  * \code
674  * ast_bridge_impart(bridge, chan, NULL, NULL, 0);
675  * \endcode
676  *
677  * \details
678  * This adds a channel pointed to by the chan pointer to the
679  * bridge pointed to by the bridge pointer.  This function will
680  * return immediately and will not wait until the channel is no
681  * longer part of the bridge.
682  *
683  * If this channel will be replacing another channel the other
684  * channel can be specified in the swap parameter.  The other
685  * channel will be thrown out of the bridge in an atomic
686  * fashion.
687  *
688  * If channel specific features are enabled, a pointer to the
689  * features structure can be specified in the features
690  * parameter.
691  *
692  * \note If you impart a channel as not independent you MUST
693  * ast_bridge_depart() the channel if this call succeeds.  The
694  * bridge channel thread is created join-able.  The implication
695  * is that the channel is special and will not behave like a
696  * normal channel.
697  *
698  * \note If you impart a channel as independent you must not
699  * ast_bridge_depart() the channel.  The bridge channel thread
700  * is created non-join-able.  The channel must be treated as if
701  * it were placed into the bridge by ast_bridge_join().
702  * Channels placed into a bridge by ast_bridge_join() are
703  * removed by a third party using ast_bridge_remove().
704  */
705 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features, int independent);
706
707 /*!
708  * \brief Depart a channel from a bridge
709  *
710  * \param chan Channel to depart
711  *
712  * \note chan is locked by this function.
713  *
714  * \retval 0 on success
715  * \retval -1 on failure
716  *
717  * Example usage:
718  *
719  * \code
720  * ast_bridge_depart(chan);
721  * \endcode
722  *
723  * This removes the channel pointed to by the chan pointer from any bridge
724  * it may be in and gives control to the calling thread.
725  * This does not hang up the channel.
726  *
727  * \note This API call can only be used on channels that were added to the bridge
728  *       using the ast_bridge_impart API call with the independent flag FALSE.
729  */
730 int ast_bridge_depart(struct ast_channel *chan);
731
732 /*!
733  * \brief Remove a channel from a bridge
734  *
735  * \param bridge Bridge that the channel is to be removed from
736  * \param chan Channel to remove
737  *
738  * \retval 0 on success
739  * \retval -1 on failure
740  *
741  * Example usage:
742  *
743  * \code
744  * ast_bridge_remove(bridge, chan);
745  * \endcode
746  *
747  * This removes the channel pointed to by the chan pointer from the bridge
748  * pointed to by the bridge pointer and requests that it be hung up. Control
749  * over the channel will NOT be given to the calling thread.
750  *
751  * \note This API call can be used on channels that were added to the bridge
752  *       using both ast_bridge_join and ast_bridge_impart.
753  */
754 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
755
756 /*!
757  * \brief Merge two bridges together
758  *
759  * \param dst_bridge Destination bridge of merge.
760  * \param src_bridge Source bridge of merge.
761  * \param merge_best_direction TRUE if don't care about which bridge merges into the other.
762  * \param kick_me Array of channels to kick from the bridges.
763  * \param num_kick Number of channels in the kick_me array.
764  *
765  * \note Absolutely _NO_ bridge or channel locks should be held
766  * before calling this function.
767  *
768  * \retval 0 on success
769  * \retval -1 on failure
770  *
771  * Example usage:
772  *
773  * \code
774  * ast_bridge_merge(dst_bridge, src_bridge, 0, NULL, 0);
775  * \endcode
776  *
777  * This moves the channels in src_bridge into the bridge pointed
778  * to by dst_bridge.
779  */
780 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);
781
782 /*!
783  * \brief Move a channel from one bridge to another.
784  * \since 12.0.0
785  *
786  * \param dst_bridge Destination bridge of bridge channel move.
787  * \param src_bridge Source bridge of bridge channel move.
788  * \param chan Channel to move.
789  * \param swap Channel to replace in dst_bridge.
790  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
791  *
792  * \note Absolutely _NO_ bridge or channel locks should be held
793  * before calling this function.
794  *
795  * \retval 0 on success.
796  * \retval -1 on failure.
797  */
798 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);
799
800 /*!
801  * \brief Adjust the bridge merge inhibit request count.
802  * \since 12.0.0
803  *
804  * \param bridge What to operate on.
805  * \param request Inhibit request increment.
806  *     (Positive to add requests.  Negative to remove requests.)
807  *
808  * \return Nothing
809  */
810 void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
811
812 /*!
813  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
814  * \since 12.0.0
815  *
816  * \param bridge_channel What to operate on.
817  * \param request Inhibit request increment.
818  *     (Positive to add requests.  Negative to remove requests.)
819  *
820  * \note This API call is meant for internal bridging operations.
821  *
822  * \retval bridge adjusted merge inhibit with reference count.
823  */
824 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
825
826 /*!
827  * \brief Suspend a channel temporarily from a bridge
828  *
829  * \param bridge Bridge to suspend the channel from
830  * \param chan Channel to suspend
831  *
832  * \retval 0 on success
833  * \retval -1 on failure
834  *
835  * Example usage:
836  *
837  * \code
838  * ast_bridge_suspend(bridge, chan);
839  * \endcode
840  *
841  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
842  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
843  * the channel will not be removed from the bridge.
844  *
845  * \note This API call can be used on channels that were added to the bridge
846  *       using both ast_bridge_join and ast_bridge_impart.
847  */
848 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
849
850 /*!
851  * \brief Unsuspend a channel from a bridge
852  *
853  * \param bridge Bridge to unsuspend the channel from
854  * \param chan Channel to unsuspend
855  *
856  * \retval 0 on success
857  * \retval -1 on failure
858  *
859  * Example usage:
860  *
861  * \code
862  * ast_bridge_unsuspend(bridge, chan);
863  * \endcode
864  *
865  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
866  * The bridge will go back to handling the channel once this function returns.
867  *
868  * \note You must not mess with the channel once this function returns.
869  *       Doing so may result in bad things happening.
870  */
871 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
872
873 /*!
874  * \brief Check and optimize out the unreal channels between bridges.
875  * \since 12.0.0
876  *
877  * \param chan Unreal channel writing a frame into the channel driver.
878  * \param peer Other unreal channel in the pair.
879  *
880  * \note It is assumed that chan is already locked.
881  *
882  * \retval 0 if unreal channels were not optimized out.
883  * \retval non-zero if unreal channels were optimized out.
884  */
885 int ast_bridge_unreal_optimized_out(struct ast_channel *chan, struct ast_channel *peer);
886
887 /*!
888  * \brief Tells, if optimization is allowed, how the optimization would be performed
889  */
890 enum ast_bridge_optimization {
891         /*! Optimization would swap peer into the chan_bridge */
892         AST_BRIDGE_OPTIMIZE_SWAP_TO_CHAN_BRIDGE,
893         /*! Optimization would swap chan into the peer_bridge */
894         AST_BRIDGE_OPTIMIZE_SWAP_TO_PEER_BRIDGE,
895         /*! Optimization would merge peer_bridge into chan_bridge */
896         AST_BRIDGE_OPTIMIZE_MERGE_TO_CHAN_BRIDGE,
897         /*! Optimization would merge chan_bridge into peer_bridge */
898         AST_BRIDGE_OPTIMIZE_MERGE_TO_PEER_BRIDGE,
899         /*! Optimization is not permitted on one or both bridges */
900         AST_BRIDGE_OPTIMIZE_PROHIBITED,
901 };
902
903 /*!
904  * \brief Determine if bridges allow for optimization to occur betweem them
905  * \since 12.0.0
906  *
907  * \param chan_bridge First bridge being tested
908  * \param peer_bridge Second bridge being tested
909  *
910  * This determines if two bridges allow for unreal channel optimization
911  * to occur between them. The function does not require for unreal channels
912  * to already be in the bridges when called.
913  *
914  * \note It is assumed that both bridges are locked prior to calling this function
915  *
916  * \note A return other than AST_BRIDGE_OPTIMIZE_PROHIBITED does not guarantee
917  * that an optimization attempt will succeed. However, a return of
918  * AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
919  * never succeed.
920  *
921  * \returns Optimization allowability for the bridges
922  */
923 enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
924                 struct ast_bridge *peer_bridge);
925
926 /*!
927  * \brief Try locking the bridge_channel.
928  *
929  * \param bridge_channel What to try locking
930  *
931  * \retval 0 on success.
932  * \retval non-zero on error.
933  */
934 #define ast_bridge_channel_trylock(bridge_channel)      _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
935 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
936 {
937         return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
938 }
939
940 /*!
941  * \brief Lock the bridge_channel.
942  *
943  * \param bridge_channel What to lock
944  *
945  * \return Nothing
946  */
947 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
948 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
949 {
950         __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
951 }
952
953 /*!
954  * \brief Unlock the bridge_channel.
955  *
956  * \param bridge_channel What to unlock
957  *
958  * \return Nothing
959  */
960 #define ast_bridge_channel_unlock(bridge_channel)       _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
961 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
962 {
963         __ao2_unlock(bridge_channel, file, function, line, var);
964 }
965
966 /*!
967  * \brief Lock the bridge associated with the bridge channel.
968  * \since 12.0.0
969  *
970  * \param bridge_channel Channel that wants to lock the bridge.
971  *
972  * \details
973  * This is an upstream lock operation.  The defined locking
974  * order is bridge then bridge_channel.
975  *
976  * \note On entry, neither the bridge nor bridge_channel is locked.
977  *
978  * \note The bridge_channel->bridge pointer changes because of a
979  * bridge-merge/channel-move operation between bridges.
980  *
981  * \return Nothing
982  */
983 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
984
985 /*!
986  * \brief Set bridge channel state to leave bridge (if not leaving already) with no lock.
987  *
988  * \param bridge_channel Channel to change the state on
989  * \param new_state The new state to place the channel into
990  *
991  * \note This API call is only meant to be used within the
992  * bridging module and hook callbacks to request the channel
993  * exit the bridge.
994  *
995  * \note This function assumes the bridge_channel is locked.
996  */
997 void ast_bridge_change_state_nolock(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
998
999 /*!
1000  * \brief Set bridge channel state to leave bridge (if not leaving already).
1001  *
1002  * \param bridge_channel Channel to change the state on
1003  * \param new_state The new state to place the channel into
1004  *
1005  * Example usage:
1006  *
1007  * \code
1008  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_HANGUP);
1009  * \endcode
1010  *
1011  * This places the channel pointed to by bridge_channel into the
1012  * state AST_BRIDGE_CHANNEL_STATE_HANGUP if it was
1013  * AST_BRIDGE_CHANNEL_STATE_WAIT before.
1014  *
1015  * \note This API call is only meant to be used within the
1016  * bridging module and hook callbacks to request the channel
1017  * exit the bridge.
1018  */
1019 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
1020
1021 /*!
1022  * \brief Put an action onto the specified bridge.
1023  * \since 12.0.0
1024  *
1025  * \param bridge What to queue the action on.
1026  * \param action What to do.
1027  *
1028  * \retval 0 on success.
1029  * \retval -1 on error.
1030  *
1031  * \note This API call is meant for internal bridging operations.
1032  * \note BUGBUG This may get moved.
1033  */
1034 int ast_bridge_queue_action(struct ast_bridge *bridge, struct ast_frame *action);
1035
1036 /*!
1037  * \brief Update the linkedid for all channels in a bridge
1038  * \since 12.0.0
1039  *
1040  * \param bridge The bridge to update the linkedids on
1041  * \param bridge_channel The channel joining the bridge
1042  * \param swap The channel being swapped out of the bridge. May be NULL.
1043  *
1044  * \note The bridge must be locked prior to calling this function.
1045  * \note This API call is meant for internal bridging operations.
1046  */
1047 void ast_bridge_update_linkedids(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
1048
1049 /*!
1050  * \brief Update the accountcodes for a channel entering a bridge
1051  * \since 12.0.0
1052  *
1053  * This function updates the accountcode and peeraccount on channels in two-party
1054  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
1055  * however accountcode propagation will still occur if the channel joining has an
1056  * accountcode.
1057  *
1058  * \param bridge The bridge to update the accountcodes in
1059  * \param bridge_channel The channel joining the bridge
1060  * \param swap The channel being swapped out of the bridge. May be NULL.
1061  *
1062  * \note The bridge must be locked prior to calling this function.
1063  * \note This API call is meant for internal bridging operations.
1064  */
1065 void ast_bridge_update_accountcodes(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
1066
1067 /*!
1068  * \brief Queue the given frame to everyone else.
1069  * \since 12.0.0
1070  *
1071  * \param bridge What bridge to distribute frame.
1072  * \param bridge_channel Channel to optionally not pass frame to. (NULL to pass to everyone)
1073  * \param frame Frame to pass.
1074  *
1075  * \note This is intended to be called by bridge hooks and
1076  * bridge technologies.
1077  *
1078  * \retval 0 Frame written to at least one channel.
1079  * \retval -1 Frame written to no channels.
1080  */
1081 int ast_bridge_queue_everyone_else(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
1082
1083 /*!
1084  * \brief Write a frame to the specified bridge_channel.
1085  * \since 12.0.0
1086  *
1087  * \param bridge_channel Channel to queue the frame.
1088  * \param fr Frame to write.
1089  *
1090  * \retval 0 on success.
1091  * \retval -1 on error.
1092  *
1093  * \note This API call is meant for internal bridging operations.
1094  * \note BUGBUG This may get moved.
1095  */
1096 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
1097
1098 /*!
1099  * \brief Used to queue an action frame onto a bridge channel and write an action frame into a bridge.
1100  * \since 12.0.0
1101  *
1102  * \param bridge_channel Which channel work with.
1103  * \param action Type of bridge action frame.
1104  * \param data Frame payload data to pass.
1105  * \param datalen Frame payload data length to pass.
1106  *
1107  * \retval 0 on success.
1108  * \retval -1 on error.
1109  */
1110 typedef int (*ast_bridge_channel_post_action_data)(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1111
1112 /*!
1113  * \brief Queue an action frame onto the bridge channel with data.
1114  * \since 12.0.0
1115  *
1116  * \param bridge_channel Which channel to queue the frame onto.
1117  * \param action Type of bridge action frame.
1118  * \param data Frame payload data to pass.
1119  * \param datalen Frame payload data length to pass.
1120  *
1121  * \retval 0 on success.
1122  * \retval -1 on error.
1123  */
1124 int ast_bridge_channel_queue_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1125
1126 /*!
1127  * \brief Write an action frame into the bridge with data.
1128  * \since 12.0.0
1129  *
1130  * \param bridge_channel Which channel is putting the frame into the bridge.
1131  * \param action Type of bridge action frame.
1132  * \param data Frame payload data to pass.
1133  * \param datalen Frame payload data length to pass.
1134  *
1135  * \retval 0 on success.
1136  * \retval -1 on error.
1137  */
1138 int ast_bridge_channel_write_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
1139
1140 /*!
1141  * \brief Queue a control frame onto the bridge channel with data.
1142  * \since 12.0.0
1143  *
1144  * \param bridge_channel Which channel to queue the frame onto.
1145  * \param control Type of control frame.
1146  * \param data Frame payload data to pass.
1147  * \param datalen Frame payload data length to pass.
1148  *
1149  * \retval 0 on success.
1150  * \retval -1 on error.
1151  */
1152 int ast_bridge_channel_queue_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
1153
1154 /*!
1155  * \brief Write a control frame into the bridge with data.
1156  * \since 12.0.0
1157  *
1158  * \param bridge_channel Which channel is putting the frame into the bridge.
1159  * \param control Type of control frame.
1160  * \param data Frame payload data to pass.
1161  * \param datalen Frame payload data length to pass.
1162  *
1163  * \retval 0 on success.
1164  * \retval -1 on error.
1165  */
1166 int ast_bridge_channel_write_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
1167
1168 /*!
1169  * \brief Write a hold frame into the bridge.
1170  * \since 12.0.0
1171  *
1172  * \param bridge_channel Which channel is putting the hold into the bridge.
1173  * \param moh_class The suggested music class for the other end to use.
1174  *
1175  * \retval 0 on success.
1176  * \retval -1 on error.
1177  */
1178 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
1179
1180 /*!
1181  * \brief Write an unhold frame into the bridge.
1182  * \since 12.0.0
1183  *
1184  * \param bridge_channel Which channel is putting the hold into the bridge.
1185  *
1186  * \retval 0 on success.
1187  * \retval -1 on error.
1188  */
1189 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
1190
1191 /*!
1192  * \brief Run an application on the bridge channel.
1193  * \since 12.0.0
1194  *
1195  * \param bridge_channel Which channel to run the application on.
1196  * \param app_name Dialplan application name.
1197  * \param app_args Arguments for the application. (NULL tolerant)
1198  * \param moh_class MOH class to request bridge peers to hear while application is running.
1199  *     NULL if no MOH.
1200  *     Empty if default MOH class.
1201  *
1202  * \note This is intended to be called by bridge hooks.
1203  *
1204  * \return Nothing
1205  */
1206 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1207
1208 /*!
1209  * \brief Write a bridge action run application frame into the bridge.
1210  * \since 12.0.0
1211  *
1212  * \param bridge_channel Which channel is putting the frame into the bridge
1213  * \param app_name Dialplan application name.
1214  * \param app_args Arguments for the application. (NULL or empty for no arguments)
1215  * \param moh_class MOH class to request bridge peers to hear while application is running.
1216  *     NULL if no MOH.
1217  *     Empty if default MOH class.
1218  *
1219  * \note This is intended to be called by bridge hooks.
1220  *
1221  * \retval 0 on success.
1222  * \retval -1 on error.
1223  */
1224 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1225
1226 /*!
1227  * \brief Queue a bridge action run application frame onto the bridge channel.
1228  * \since 12.0.0
1229  *
1230  * \param bridge_channel Which channel to put the frame onto
1231  * \param app_name Dialplan application name.
1232  * \param app_args Arguments for the application. (NULL or empty for no arguments)
1233  * \param moh_class MOH class to request bridge peers to hear while application is running.
1234  *     NULL if no MOH.
1235  *     Empty if default MOH class.
1236  *
1237  * \note This is intended to be called by bridge hooks.
1238  *
1239  * \retval 0 on success.
1240  * \retval -1 on error.
1241  */
1242 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
1243
1244 /*!
1245  * \brief Custom interpretation of the playfile name.
1246  *
1247  * \param bridge_channel Which channel to play the file on
1248  * \param playfile Sound filename to play.
1249  *
1250  * \return Nothing
1251  */
1252 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
1253
1254 /*!
1255  * \brief Play a file on the bridge channel.
1256  * \since 12.0.0
1257  *
1258  * \param bridge_channel Which channel to play the file on
1259  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1260  * \param playfile Sound filename to play.
1261  * \param moh_class MOH class to request bridge peers to hear while file is played.
1262  *     NULL if no MOH.
1263  *     Empty if default MOH class.
1264  *
1265  * \note This is intended to be called by bridge hooks.
1266  *
1267  * \return Nothing
1268  */
1269 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);
1270
1271 /*!
1272  * \brief Write a bridge action play file frame into the bridge.
1273  * \since 12.0.0
1274  *
1275  * \param bridge_channel Which channel is putting the frame into the bridge
1276  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1277  * \param playfile Sound filename to play.
1278  * \param moh_class MOH class to request bridge peers to hear while file is played.
1279  *     NULL if no MOH.
1280  *     Empty if default MOH class.
1281  *
1282  * \note This is intended to be called by bridge hooks.
1283  *
1284  * \retval 0 on success.
1285  * \retval -1 on error.
1286  */
1287 int 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);
1288
1289 /*!
1290  * \brief Queue a bridge action play file frame onto the bridge channel.
1291  * \since 12.0.0
1292  *
1293  * \param bridge_channel Which channel to put the frame onto.
1294  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
1295  * \param playfile Sound filename to play.
1296  * \param moh_class MOH class to request bridge peers to hear while file is played.
1297  *     NULL if no MOH.
1298  *     Empty if default MOH class.
1299  *
1300  * \note This is intended to be called by bridge hooks.
1301  *
1302  * \retval 0 on success.
1303  * \retval -1 on error.
1304  */
1305 int 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);
1306
1307 /*!
1308  * \brief Custom callback run on a bridge channel.
1309  *
1310  * \param bridge_channel Which channel to operate on.
1311  * \param payload Data to pass to the callback. (NULL if none).
1312  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1313  *
1314  * \note The payload MUST NOT have any resources that need to be freed.
1315  *
1316  * \return Nothing
1317  */
1318 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
1319
1320 /*!
1321  * \brief Write a bridge action custom callback frame into the bridge.
1322  * \since 12.0.0
1323  *
1324  * \param bridge_channel Which channel is putting the frame into the bridge
1325  * \param callback Custom callback run on a bridge channel.
1326  * \param payload Data to pass to the callback. (NULL if none).
1327  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1328  *
1329  * \note The payload MUST NOT have any resources that need to be freed.
1330  *
1331  * \note This is intended to be called by bridge hooks.
1332  *
1333  * \retval 0 on success.
1334  * \retval -1 on error.
1335  */
1336 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
1337
1338 /*!
1339  * \brief Queue a bridge action custom callback frame onto the bridge channel.
1340  * \since 12.0.0
1341  *
1342  * \param bridge_channel Which channel to put the frame onto.
1343  * \param callback Custom callback run on a bridge channel.
1344  * \param payload Data to pass to the callback. (NULL if none).
1345  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
1346  *
1347  * \note The payload MUST NOT have any resources that need to be freed.
1348  *
1349  * \note This is intended to be called by bridge hooks.
1350  *
1351  * \retval 0 on success.
1352  * \retval -1 on error.
1353  */
1354 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
1355
1356 /*!
1357  * \brief Have a bridge channel park a channel in the bridge
1358  * \since 12.0.0
1359  *
1360  * \param bridge_channel Bridge channel performing the parking
1361  * \param parkee_uuid Unique id of the channel we want to park
1362  * \param parker_uuid Unique id of the channel parking the call
1363  * \param app_data string indicating data used for park application (NULL allowed)
1364  *
1365  * \note This is intended to be called by bridge hooks.
1366  *
1367  * \retval 0 on success.
1368  * \retval -1 on error.
1369  */
1370 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
1371         const char *parker_uuid, const char *app_data);
1372
1373 /*!
1374  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_join
1375  * \since 12.0.0
1376  *
1377  * \param bridge_channel Channel to restore
1378  */
1379 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
1380
1381 /*!
1382  * \brief Get the peer bridge channel of a two party bridge.
1383  * \since 12.0.0
1384  *
1385  * \param bridge_channel What to get the peer of.
1386  *
1387  * \note On entry, bridge_channel->bridge is already locked.
1388  *
1389  * \note This is an internal bridge function.
1390  *
1391  * \retval peer on success.
1392  * \retval NULL no peer channel.
1393  */
1394 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
1395
1396 /*!
1397  * \brief Adjust the internal mixing sample rate of a bridge
1398  * used during multimix mode.
1399  *
1400  * \param bridge Channel to change the sample rate on.
1401  * \param sample_rate the sample rate to change to. If a
1402  *        value of 0 is passed here, the bridge will be free to pick
1403  *        what ever sample rate it chooses.
1404  *
1405  */
1406 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
1407
1408 /*!
1409  * \brief Adjust the internal mixing interval of a bridge used
1410  * during multimix mode.
1411  *
1412  * \param bridge Channel to change the sample rate on.
1413  * \param mixing_interval the sample rate to change to.  If 0 is set
1414  * the bridge tech is free to choose any mixing interval it uses by default.
1415  */
1416 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
1417
1418 /*!
1419  * \brief Set a bridge to feed a single video source to all participants.
1420  */
1421 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
1422
1423 /*!
1424  * \brief Set the bridge to pick the strongest talker supporting
1425  * video as the single source video feed
1426  */
1427 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
1428
1429 /*!
1430  * \brief Update information about talker energy for talker src video mode.
1431  */
1432 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
1433
1434 /*!
1435  * \brief Returns the number of video sources currently active in the bridge
1436  */
1437 int ast_bridge_number_video_src(struct ast_bridge *bridge);
1438
1439 /*!
1440  * \brief Determine if a channel is a video src for the bridge
1441  *
1442  * \retval 0 Not a current video source of the bridge.
1443  * \retval None 0, is a video source of the bridge, The number
1444  *         returned represents the priority this video stream has
1445  *         on the bridge where 1 is the highest priority.
1446  */
1447 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
1448
1449 /*!
1450  * \brief remove a channel as a source of video for the bridge.
1451  */
1452 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
1453
1454 enum ast_transfer_result {
1455         /*! The transfer completed successfully */
1456         AST_BRIDGE_TRANSFER_SUCCESS,
1457         /*! A bridge involved does not permit transferring */
1458         AST_BRIDGE_TRANSFER_NOT_PERMITTED,
1459         /*! The current bridge setup makes transferring an invalid operation */
1460         AST_BRIDGE_TRANSFER_INVALID,
1461         /*! The transfer operation failed for a miscellaneous reason */
1462         AST_BRIDGE_TRANSFER_FAIL,
1463 };
1464
1465 enum ast_transfer_type {
1466         /*! Transfer of a single party */
1467         AST_BRIDGE_TRANSFER_SINGLE_PARTY,
1468         /*! Transfer of multiple parties */
1469         AST_BRIDGE_TRANSFER_MULTI_PARTY,
1470 };
1471
1472 /*!
1473  * \brief Callback function type called during blind transfers
1474  *
1475  * A caller of ast_bridge_transfer_blind() may wish to set data on
1476  * the channel that ends up running dialplan. For instance, it may
1477  * be useful to set channel variables on the channel.
1478  *
1479  * \param chan The involved channel
1480  * \param user_data User-provided data needed in the callback
1481  * \param transfer_type The type of transfer being completed
1482  */
1483 typedef void (*transfer_channel_cb)(struct ast_channel *chan, void *user_data,
1484                 enum ast_transfer_type transfer_type);
1485
1486 /*!
1487  * \brief Blind transfer target to the extension and context provided
1488  *
1489  * The channel given is bridged to one or multiple channels. Depending on
1490  * the bridge and the number of participants, the entire bridge could be
1491  * transferred to the given destination, or a single channel may be redirected.
1492  *
1493  * Callers may also provide a callback to be called on the channel that will
1494  * be running dialplan. The user data passed into ast_bridge_transfer_blind
1495  * will be given as the argument to the callback to be interpreted as desired.
1496  * This callback is guaranteed to be called in the same thread as
1497  * ast_bridge_transfer_blind() and before ast_bridge_transfer_blind() returns.
1498  *
1499  * \note Absolutely _NO_ channel locks should be held before
1500  * calling this function.
1501  *
1502  * \param is_external Indicates that transfer was initiated externally
1503  * \param transferer The channel performing the blind transfer
1504  * \param exten The dialplan extension to send the call to
1505  * \param context The dialplan context to send the call to
1506  * \param new_channel_cb A callback to be called on the channel that will
1507  *        be executing dialplan
1508  * \param user_data Argument for new_channel_cb
1509  * \return The success or failure result of the blind transfer
1510  */
1511 enum ast_transfer_result ast_bridge_transfer_blind(int is_external,
1512                 struct ast_channel *transferer, const char *exten, const char *context,
1513                 transfer_channel_cb new_channel_cb, void *user_data);
1514
1515 /*!
1516  * \brief Attended transfer
1517  *
1518  * The two channels are both transferer channels. The first is the channel
1519  * that is bridged to the transferee (or if unbridged, the 'first' call of
1520  * the transfer). The second is the channel that is bridged to the transfer
1521  * target (or if unbridged, the 'second' call of the transfer).
1522  *
1523  * \note Absolutely _NO_ channel locks should be held before
1524  * calling this function.
1525  *
1526  * \param to_transferee Transferer channel on initial call (presumably bridged to transferee)
1527  * \param to_transfer_target Transferer channel on consultation call (presumably bridged to transfer target)
1528  * \return The success or failure of the attended transfer
1529  */
1530 enum ast_transfer_result ast_bridge_transfer_attended(struct ast_channel *to_transferee,
1531                 struct ast_channel *to_transfer_target);
1532 /*!
1533  * \brief Set channel to goto specific location after the bridge.
1534  * \since 12.0.0
1535  *
1536  * \param chan Channel to setup after bridge goto location.
1537  * \param context Context to goto after bridge.
1538  * \param exten Exten to goto after bridge.
1539  * \param priority Priority to goto after bridge.
1540  *
1541  * \note chan is locked by this function.
1542  *
1543  * \details Add a channel datastore to setup the goto location
1544  * when the channel leaves the bridge and run a PBX from there.
1545  *
1546  * \return Nothing
1547  */
1548 void ast_after_bridge_set_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1549
1550 /*!
1551  * \brief Set channel to run the h exten after the bridge.
1552  * \since 12.0.0
1553  *
1554  * \param chan Channel to setup after bridge goto location.
1555  * \param context Context to goto after bridge.
1556  *
1557  * \note chan is locked by this function.
1558  *
1559  * \details Add a channel datastore to setup the goto location
1560  * when the channel leaves the bridge and run a PBX from there.
1561  *
1562  * \return Nothing
1563  */
1564 void ast_after_bridge_set_h(struct ast_channel *chan, const char *context);
1565
1566 /*!
1567  * \brief Set channel to go on in the dialplan after the bridge.
1568  * \since 12.0.0
1569  *
1570  * \param chan Channel to setup after bridge goto location.
1571  * \param context Current context of the caller channel.
1572  * \param exten Current exten of the caller channel.
1573  * \param priority Current priority of the caller channel
1574  * \param parseable_goto User specified goto string from dialplan.
1575  *
1576  * \note chan is locked by this function.
1577  *
1578  * \details Add a channel datastore to setup the goto location
1579  * when the channel leaves the bridge and run a PBX from there.
1580  *
1581  * If parseable_goto then use the given context/exten/priority
1582  *   as the relative position for the parseable_goto.
1583  * Else goto the given context/exten/priority+1.
1584  *
1585  * \return Nothing
1586  */
1587 void ast_after_bridge_set_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto);
1588
1589 /*!
1590  * \brief Setup any after bridge goto location to begin execution.
1591  * \since 12.0.0
1592  *
1593  * \param chan Channel to setup after bridge goto location.
1594  *
1595  * \note chan is locked by this function.
1596  *
1597  * \details Pull off any after bridge goto location datastore and
1598  * setup for dialplan execution there.
1599  *
1600  * \retval 0 on success.  The goto location is set for a PBX to run it.
1601  * \retval non-zero on error or no goto location.
1602  *
1603  * \note If the after bridge goto is set to run an h exten it is
1604  * run here immediately.
1605  */
1606 int ast_after_bridge_goto_setup(struct ast_channel *chan);
1607
1608 /*!
1609  * \brief Run a PBX on any after bridge goto location.
1610  * \since 12.0.0
1611  *
1612  * \param chan Channel to execute after bridge goto location.
1613  *
1614  * \note chan is locked by this function.
1615  *
1616  * \details Pull off any after bridge goto location datastore
1617  * and run a PBX at that location.
1618  *
1619  * \note On return, the chan pointer is no longer valid because
1620  * the channel has hung up.
1621  *
1622  * \return Nothing
1623  */
1624 void ast_after_bridge_goto_run(struct ast_channel *chan);
1625
1626 /*!
1627  * \brief Discard channel after bridge goto location.
1628  * \since 12.0.0
1629  *
1630  * \param chan Channel to discard after bridge goto location.
1631  *
1632  * \note chan is locked by this function.
1633  *
1634  * \return Nothing
1635  */
1636 void ast_after_bridge_goto_discard(struct ast_channel *chan);
1637
1638 /*!
1639  * \brief Read after bridge goto if it exists
1640  * \since 12.0.0
1641  *
1642  * \param chan Channel to read the after bridge goto parseable goto string from
1643  * \param buffer Buffer to write the after bridge goto data to
1644  * \param buf_size size of the buffer being written to
1645  */
1646 void ast_after_bridge_goto_read(struct ast_channel *chan, char *buffer, size_t buf_size);
1647
1648 /*! Reason the the after bridge callback will not be called. */
1649 enum ast_after_bridge_cb_reason {
1650         /*! The datastore is being destroyed.  Likely due to hangup. */
1651         AST_AFTER_BRIDGE_CB_REASON_DESTROY,
1652         /*! Something else replaced the callback with another. */
1653         AST_AFTER_BRIDGE_CB_REASON_REPLACED,
1654         /*! The callback was removed because of a masquerade. (fixup) */
1655         AST_AFTER_BRIDGE_CB_REASON_MASQUERADE,
1656         /*! The channel was departed from the bridge. */
1657         AST_AFTER_BRIDGE_CB_REASON_DEPART,
1658         /*! Was explicitly removed by external code. */
1659         AST_AFTER_BRIDGE_CB_REASON_REMOVED,
1660 };
1661
1662 /*!
1663  * \brief After bridge callback failed.
1664  * \since 12.0.0
1665  *
1666  * \param reason Reason callback is failing.
1667  * \param data Extra data what setup the callback wanted to pass.
1668  *
1669  * \return Nothing
1670  */
1671 typedef void (*ast_after_bridge_cb_failed)(enum ast_after_bridge_cb_reason reason, void *data);
1672
1673 /*!
1674  * \brief After bridge callback function.
1675  * \since 12.0.0
1676  *
1677  * \param chan Channel just leaving bridging system.
1678  * \param data Extra data what setup the callback wanted to pass.
1679  *
1680  * \return Nothing
1681  */
1682 typedef void (*ast_after_bridge_cb)(struct ast_channel *chan, void *data);
1683
1684 /*!
1685  * \brief Discard channel after bridge callback.
1686  * \since 12.0.0
1687  *
1688  * \param chan Channel to discard after bridge callback.
1689  * \param reason Why are we doing this.
1690  *
1691  * \note chan is locked by this function.
1692  *
1693  * \return Nothing
1694  */
1695 void ast_after_bridge_callback_discard(struct ast_channel *chan, enum ast_after_bridge_cb_reason reason);
1696
1697 /*!
1698  * \brief Setup an after bridge callback for when the channel leaves the bridging system.
1699  * \since 12.0.0
1700  *
1701  * \param chan Channel to setup an after bridge callback on.
1702  * \param callback Function to call when the channel leaves the bridging system.
1703  * \param failed Function to call when it will not be calling the callback.
1704  * \param data Extra data to pass with the callback.
1705  *
1706  * \note chan is locked by this function.
1707  *
1708  * \retval 0 on success.
1709  * \retval -1 on error.
1710  */
1711 int ast_after_bridge_callback_set(struct ast_channel *chan, ast_after_bridge_cb callback, ast_after_bridge_cb_failed failed, void *data);
1712
1713 /*!
1714  * \brief Get a string representation of an after bridge callback reason
1715  * \since 12.0.0
1716  *
1717  * \param reason The reason to interpret to a string
1718  * \retval NULL Unrecognized reason
1719  * \retval non-NULL String representation of reason
1720  */
1721 const char *ast_after_bridge_cb_reason_string(enum ast_after_bridge_cb_reason reason);
1722
1723 /*!
1724  * \brief Get a container of all channels in the bridge
1725  * \since 12.0.0
1726  *
1727  * \param bridge The bridge which is already locked.
1728  *
1729  * \retval NULL Failed to create container
1730  * \retval non-NULL Container of channels in the bridge
1731  */
1732 struct ao2_container *ast_bridge_peers_nolock(struct ast_bridge *bridge);
1733
1734 /*!
1735  * \brief Get a container of all channels in the bridge
1736  * \since 12.0.0
1737  *
1738  * \param bridge The bridge
1739  *
1740  * \note The returned container is a snapshot of channels in the
1741  * bridge when called.
1742  *
1743  * \retval NULL Failed to create container
1744  * \retval non-NULL Container of channels in the bridge
1745  */
1746 struct ao2_container *ast_bridge_peers(struct ast_bridge *bridge);
1747
1748 /*!
1749  * \brief Get the channel's bridge peer only if the bridge is two-party.
1750  * \since 12.0.0
1751  *
1752  * \param bridge The bridge which is already locked.
1753  * \param chan Channel desiring the bridge peer channel.
1754  *
1755  * \note The returned peer channel is the current peer in the
1756  * bridge when called.
1757  *
1758  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1759  * \retval non-NULL Reffed peer channel at time of calling.
1760  */
1761 struct ast_channel *ast_bridge_peer_nolock(struct ast_bridge *bridge, struct ast_channel *chan);
1762
1763 /*!
1764  * \brief Get the channel's bridge peer only if the bridge is two-party.
1765  * \since 12.0.0
1766  *
1767  * \param bridge The bridge
1768  * \param chan Channel desiring the bridge peer channel.
1769  *
1770  * \note The returned peer channel is the current peer in the
1771  * bridge when called.
1772  *
1773  * \retval NULL Channel not in a bridge or the bridge is not two-party.
1774  * \retval non-NULL Reffed peer channel at time of calling.
1775  */
1776 struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channel *chan);
1777
1778 #if defined(__cplusplus) || defined(c_plusplus)
1779 }
1780 #endif
1781
1782 #endif  /* _ASTERISK_BRIDGING_H */