bridge: Add a deferred queue.
[asterisk/asterisk.git] / include / asterisk / bridge_channel.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  * Richard Mudgett <rmudgett@digium.com>
8  * Matt Jordan <mjordan@digium.com>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20
21 /*!
22  * \file
23  * \page AstBridgeChannel Bridging Channel API
24  *
25  * An API that act on a channel in a bridge. Note that while the
26  * \ref ast_bridge_channel is owned by a channel, it should only be used
27  * by members of the bridging system. The only places where this API should
28  * be used is:
29  *  \arg \ref AstBridging API itself
30  *  \arg Bridge mixing technologies
31  *  \arg Bridge sub-classes
32  *
33  * In general, anywhere else it is unsafe to use this API. Care should be
34  * taken when using this API to ensure that the locking order remains
35  * correct. The locking order must be:
36  *  \arg The \ref \c ast_bridge
37  *  \arg The \ref \c ast_bridge_channel
38  *  \arg The \ref \c ast_channel
39  *
40  * \author Joshua Colp <jcolp@digium.com>
41  * \author Richard Mudgett <rmudgett@digium.com>
42  * \author Matt Jordan <mjordan@digium.com>
43  *
44  * See Also:
45  * \arg \ref AstBridging
46  * \arg \ref AstCREDITS
47  */
48
49 #ifndef _ASTERISK_BRIDGING_CHANNEL_H
50 #define _ASTERISK_BRIDGING_CHANNEL_H
51
52 #if defined(__cplusplus) || defined(c_plusplus)
53 extern "C" {
54 #endif
55
56 #include "asterisk/bridge_features.h"
57 #include "asterisk/bridge_technology.h"
58
59 /*! \brief State information about a bridged channel */
60 enum bridge_channel_state {
61         /*! Waiting for a signal (Channel in the bridge) */
62         BRIDGE_CHANNEL_STATE_WAIT = 0,
63         /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
64         BRIDGE_CHANNEL_STATE_END,
65         /*! Bridged channel was forced out. Don't dissolve the bridge regardless */
66         BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE,
67 };
68
69 enum bridge_channel_thread_state {
70         /*! Bridge channel thread is idle/waiting. */
71         BRIDGE_CHANNEL_THREAD_IDLE,
72         /*! Bridge channel thread is writing a normal/simple frame. */
73         BRIDGE_CHANNEL_THREAD_SIMPLE,
74         /*! Bridge channel thread is processing a frame. */
75         BRIDGE_CHANNEL_THREAD_FRAME,
76 };
77
78 struct ast_bridge;
79 struct ast_bridge_tech_optimizations;
80
81  /*!
82  * \brief Structure that contains information regarding a channel in a bridge
83  */
84 struct ast_bridge_channel {
85 /* XXX ASTERISK-21271 cond is only here because of external party suspend/unsuspend support. */
86         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
87         ast_cond_t cond;
88         /*! Current bridged channel state */
89         enum bridge_channel_state state;
90         /*! Asterisk channel participating in the bridge */
91         struct ast_channel *chan;
92         /*! Asterisk channel we are swapping with (if swapping) */
93         struct ast_channel *swap;
94         /*!
95          * \brief Bridge this channel is participating in
96          *
97          * \note The bridge pointer cannot change while the bridge or
98          * bridge_channel is locked.
99          */
100         struct ast_bridge *bridge;
101         /*!
102          * \brief Bridge class private channel data.
103          *
104          * \note This information is added when the channel is pushed
105          * into the bridge and removed when it is pulled from the
106          * bridge.
107          */
108         void *bridge_pvt;
109         /*!
110          * \brief Private information unique to the bridge technology.
111          *
112          * \note This information is added when the channel joins the
113          * bridge's technology and removed when it leaves the bridge's
114          * technology.
115          */
116         void *tech_pvt;
117         /*! Thread handling the bridged channel (Needed by ast_bridge_depart) */
118         pthread_t thread;
119         /* v-- These flags change while the bridge is locked or before the channel is in the bridge. */
120         /*! TRUE if the channel is in a bridge. */
121         unsigned int in_bridge:1;
122         /*! TRUE if the channel just joined the bridge. */
123         unsigned int just_joined:1;
124         /*! TRUE if the channel is suspended from the bridge. */
125         unsigned int suspended:1;
126         /*! TRUE if the COLP update on initial join is inhibited. */
127         unsigned int inhibit_colp:1;
128         /*! TRUE if the channel must wait for an ast_bridge_depart to reclaim the channel. */
129         unsigned int depart_wait:1;
130         /* ^-- These flags change while the bridge is locked or before the channel is in the bridge. */
131         /*! Features structure for features that are specific to this channel */
132         struct ast_bridge_features *features;
133         /*! Technology optimization parameters used by bridging technologies capable of
134          *  optimizing based upon talk detection. */
135         struct ast_bridge_tech_optimizations tech_args;
136         /*! Copy of read format used by chan before join */
137         struct ast_format *read_format;
138         /*! Copy of write format used by chan before join */
139         struct ast_format *write_format;
140         /*! Call ID associated with bridge channel */
141         ast_callid callid;
142         /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
143         struct bridge_roles_datastore *bridge_roles;
144         /*! Linked list information */
145         AST_LIST_ENTRY(ast_bridge_channel) entry;
146         /*! Queue of outgoing frames to the channel. */
147         AST_LIST_HEAD_NOLOCK(, ast_frame) wr_queue;
148         /*! Queue of deferred frames, queued onto channel when other party joins. */
149         AST_LIST_HEAD_NOLOCK(, ast_frame) deferred_queue;
150         /*! Pipe to alert thread when frames are put into the wr_queue. */
151         int alert_pipe[2];
152         /*!
153          * \brief The bridge channel thread activity.
154          *
155          * \details Used by local channel optimization to determine if
156          * the thread is in an acceptable state to optimize.
157          *
158          * \note Needs to be atomically settable.
159          */
160         enum bridge_channel_thread_state activity;
161         /*! Owed events to the bridge. */
162         struct {
163                 /*! Time started sending the current digit. (Invalid if owed.dtmf_digit is zero.) */
164                 struct timeval dtmf_tv;
165                 /*! Digit currently sending into the bridge. (zero if not sending) */
166                 char dtmf_digit;
167                 /*! Non-zero if a T.38 session terminate is owed to the bridge. */
168                 char t38_terminate;
169         } owed;
170         /*! DTMF hook sequence state */
171         struct {
172                 /*! Time at which the DTMF hooks should stop waiting for more digits to come. */
173                 struct timeval interdigit_timeout;
174                 /*! Collected DTMF digits for DTMF hooks. */
175                 char collected[MAXIMUM_DTMF_FEATURE_STRING];
176         } dtmf_hook_state;
177         union {
178                 uint32_t raw;
179                 struct {
180                         /*! TRUE if binaural is suspended. */
181                         unsigned int binaural_suspended:1;
182                         /*! TRUE if a change of binaural positions has to be performed. */
183                         unsigned int binaural_pos_change:1;
184                         /*! Padding */
185                         unsigned int padding:30;
186                 };
187         };
188         struct {
189                 /*! An index mapping of where a channel's media needs to be routed */
190                 struct ast_vector_int to_bridge;
191                 /*! An index mapping of where a bridge's media needs to be routed */
192                 struct ast_vector_int to_channel;
193         } stream_map;
194 };
195
196 /*!
197  * \brief Try locking the bridge_channel.
198  *
199  * \param bridge_channel What to try locking
200  *
201  * \retval 0 on success.
202  * \retval non-zero on error.
203  */
204 #define ast_bridge_channel_trylock(bridge_channel)      _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
205 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
206 {
207         return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
208 }
209
210 /*!
211  * \brief Lock the bridge_channel.
212  *
213  * \param bridge_channel What to lock
214  *
215  * \return Nothing
216  */
217 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
218 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
219 {
220         __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
221 }
222
223 /*!
224  * \brief Unlock the bridge_channel.
225  *
226  * \param bridge_channel What to unlock
227  *
228  * \return Nothing
229  */
230 #define ast_bridge_channel_unlock(bridge_channel)       _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
231 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
232 {
233         __ao2_unlock(bridge_channel, file, function, line, var);
234 }
235
236 /*!
237  * \brief Lock the bridge associated with the bridge channel.
238  * \since 12.0.0
239  *
240  * \param bridge_channel Channel that wants to lock the bridge.
241  *
242  * \details
243  * This is an upstream lock operation.  The defined locking
244  * order is bridge then bridge_channel.
245  *
246  * \note On entry, neither the bridge nor bridge_channel is locked.
247  *
248  * \note The bridge_channel->bridge pointer changes because of a
249  * bridge-merge/channel-move operation between bridges.
250  *
251  * \return Nothing
252  */
253 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
254
255 /*!
256  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
257  *
258  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
259  * layer, which in this case is the specific bridging technology being used. Since it
260  * is necessary for the knowledge of which channels are talking to make its way up to the
261  * application, this function has been created to allow the bridging technology to communicate
262  * that information with the bridging core.
263  *
264  * \param bridge_channel The bridge channel that has either started or stopped talking.
265  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
266  * when this indicates the channel has stopped talking.
267  *
268  * \retval 0 on success.
269  * \retval -1 on error.
270  */
271 int ast_bridge_channel_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking);
272
273 /*!
274  * \brief Set bridge channel state to leave bridge (if not leaving already).
275  *
276  * \param bridge_channel Channel to change the state on
277  * \param new_state The new state to place the channel into
278  * \param cause Cause of channel leaving bridge.
279  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
280  *
281  * Example usage:
282  *
283  * \code
284  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
285  * \endcode
286  *
287  * This places the channel pointed to by bridge_channel into the
288  * state BRIDGE_CHANNEL_STATE_END if it was
289  * BRIDGE_CHANNEL_STATE_WAIT before.
290  */
291 void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
292
293 /*!
294  * \brief Set bridge channel state to leave bridge (if not leaving already).
295  *
296  * \param bridge_channel Channel to change the state on
297  * \param new_state The new state to place the channel into
298  * \param cause Cause of channel leaving bridge.
299  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
300  *
301  * Example usage:
302  *
303  * \code
304  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
305  * \endcode
306  *
307  * This places the channel pointed to by bridge_channel into the
308  * state BRIDGE_CHANNEL_STATE_END if it was
309  * BRIDGE_CHANNEL_STATE_WAIT before.
310  */
311 void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
312
313 /*!
314  * \brief Get the peer bridge channel of a two party bridge.
315  * \since 12.0.0
316  *
317  * \param bridge_channel What to get the peer of.
318  *
319  * \note On entry, bridge_channel->bridge is already locked.
320  *
321  * \note This is an internal bridge function.
322  *
323  * \retval peer on success.
324  * \retval NULL no peer channel.
325  */
326 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
327
328 /*!
329  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_join
330  * \since 12.0.0
331  *
332  * \param bridge_channel Channel to restore
333  */
334 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
335
336 /*!
337  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
338  * \since 12.0.0
339  *
340  * \param bridge_channel What to operate on.
341  * \param request Inhibit request increment.
342  *     (Positive to add requests.  Negative to remove requests.)
343  *
344  * \note This API call is meant for internal bridging operations.
345  *
346  * \retval bridge adjusted merge inhibit with reference count.
347  */
348 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
349
350 /*!
351  * \internal
352  * \brief Update the linkedids for all channels in a bridge
353  * \since 12.0.0
354  *
355  * \param bridge_channel The channel joining the bridge
356  * \param swap The channel being swapped out of the bridge. May be NULL.
357  *
358  * \note The bridge must be locked prior to calling this function.
359  * \note This should be called during a \ref bridge_channel_internal_push
360  * operation, typically by a sub-class of a bridge.
361  */
362 void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
363
364 /*!
365  * \internal
366  * \brief Update the accountcodes for channels joining/leaving a bridge
367  * \since 12.0.0
368  *
369  * This function updates the accountcode and peeraccount on channels in two-party
370  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
371  * however accountcode propagation will still occur if the channel joining has an
372  * accountcode.
373  *
374  * \param joining The channel joining the bridge.  May be NULL.
375  * \param leaving The channel leaving or being swapped out of the bridge. May be NULL.
376  *
377  * \note The joining and leaving parameters cannot both be NULL.
378  *
379  * \note The bridge must be locked prior to calling this function.
380  * \note This should be called during a \ref bridge_channel_internal_push
381  * or \ref bridge_channel_internal_pull operation, typically by a
382  * sub-class of a bridge.
383  */
384 void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *joining, struct ast_bridge_channel *leaving);
385
386 /*!
387  * \brief Write a frame to the specified bridge_channel.
388  * \since 12.0.0
389  *
390  * \param bridge_channel Channel to queue the frame.
391  * \param fr Frame to write.
392  *
393  * \retval 0 on success.
394  * \retval -1 on error.
395  */
396 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
397
398 /*!
399  * \brief Queue a control frame onto the bridge channel with data.
400  * \since 12.0.0
401  *
402  * \param bridge_channel Which channel to queue the frame onto.
403  * \param control Type of control frame.
404  * \param data Frame payload data to pass.
405  * \param datalen Frame payload data length to pass.
406  *
407  * \retval 0 on success.
408  * \retval -1 on error.
409  */
410 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);
411
412 /*!
413  * \brief Write a control frame into the bridge with data.
414  * \since 12.0.0
415  *
416  * \param bridge_channel Which channel is putting the frame into the bridge.
417  * \param control Type of control frame.
418  * \param data Frame payload data to pass.
419  * \param datalen Frame payload data length to pass.
420  *
421  * \retval 0 on success.
422  * \retval -1 on error.
423  */
424 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);
425
426 /*!
427  * \brief Write a hold frame into the bridge.
428  * \since 12.0.0
429  *
430  * \param bridge_channel Which channel is putting the hold into the bridge.
431  * \param moh_class The suggested music class for the other end to use.
432  *
433  * \retval 0 on success.
434  * \retval -1 on error.
435  */
436 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
437
438 /*!
439  * \brief Write an unhold frame into the bridge.
440  * \since 12.0.0
441  *
442  * \param bridge_channel Which channel is putting the hold into the bridge.
443  *
444  * \retval 0 on success.
445  * \retval -1 on error.
446  */
447 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
448
449 /*!
450  * \brief Run an application on the bridge channel.
451  * \since 12.0.0
452  *
453  * \param bridge_channel Which channel to run the application on.
454  * \param app_name Dialplan application name.
455  * \param app_args Arguments for the application. (NULL tolerant)
456  * \param moh_class MOH class to request bridge peers to hear while application is running.
457  *     NULL if no MOH.
458  *     Empty if default MOH class.
459  *
460  * \note This is intended to be called by bridge hooks.
461  *
462  * \return Nothing
463  */
464 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
465
466 /*!
467  * \brief Write a bridge action run application frame into the bridge.
468  * \since 12.0.0
469  *
470  * \param bridge_channel Which channel is putting the frame into the bridge
471  * \param app_name Dialplan application name.
472  * \param app_args Arguments for the application. (NULL or empty for no arguments)
473  * \param moh_class MOH class to request bridge peers to hear while application is running.
474  *     NULL if no MOH.
475  *     Empty if default MOH class.
476  *
477  * \note This is intended to be called by bridge hooks.
478  *
479  * \retval 0 on success.
480  * \retval -1 on error.
481  */
482 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
483
484 /*!
485  * \brief Queue a bridge action run application frame onto the bridge channel.
486  * \since 12.0.0
487  *
488  * \param bridge_channel Which channel to put the frame onto
489  * \param app_name Dialplan application name.
490  * \param app_args Arguments for the application. (NULL or empty for no arguments)
491  * \param moh_class MOH class to request bridge peers to hear while application is running.
492  *     NULL if no MOH.
493  *     Empty if default MOH class.
494  *
495  * \note This is intended to be called by bridge hooks.
496  *
497  * \retval 0 on success.
498  * \retval -1 on error.
499  */
500 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
501
502 /*!
503  * \brief Custom interpretation of the playfile name.
504  *
505  * \param bridge_channel Which channel to play the file on
506  * \param playfile Sound filename to play.
507  *
508  * \return Nothing
509  */
510 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
511
512 /*!
513  * \brief Play a file on the bridge channel.
514  * \since 12.0.0
515  *
516  * \param bridge_channel Which channel to play the file on
517  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
518  * \param playfile Sound filename to play.
519  * \param moh_class MOH class to request bridge peers to hear while file is played.
520  *     NULL if no MOH.
521  *     Empty if default MOH class.
522  *
523  * \note This is intended to be called by bridge hooks.
524  *
525  * \return Nothing
526  */
527 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);
528
529 /*!
530  * \brief Write a bridge action play file frame into the bridge.
531  * \since 12.0.0
532  *
533  * \param bridge_channel Which channel is putting the frame into the bridge
534  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
535  * \param playfile Sound filename to play.
536  * \param moh_class MOH class to request bridge peers to hear while file is played.
537  *     NULL if no MOH.
538  *     Empty if default MOH class.
539  *
540  * \note This is intended to be called by bridge hooks.
541  *
542  * \retval 0 on success.
543  * \retval -1 on error.
544  */
545 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);
546
547 /*!
548  * \brief Queue a bridge action play file frame onto the bridge channel.
549  * \since 12.0.0
550  *
551  * \param bridge_channel Which channel to put the frame onto.
552  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
553  * \param playfile Sound filename to play.
554  * \param moh_class MOH class to request bridge peers to hear while file is played.
555  *     NULL if no MOH.
556  *     Empty if default MOH class.
557  *
558  * \note This is intended to be called by bridge hooks.
559  *
560  * \retval 0 on success.
561  * \retval -1 on error.
562  */
563 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);
564
565 /*!
566  * \brief Synchronously queue a bridge action play file frame onto the bridge channel.
567  * \since 12.2.0
568  *
569  * \param bridge_channel Which channel to put the frame onto.
570  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
571  * \param playfile Sound filename to play.
572  * \param moh_class MOH class to request bridge peers to hear while file is played.
573  *     NULL if no MOH.
574  *     Empty if default MOH class.
575  *
576  * This function will block until the queued frame has been destroyed. This will happen
577  * either if an error occurs or if the queued playback finishes.
578  *
579  * \note No locks may be held when calling this function.
580  *
581  * \retval 0 The playback was successfully queued.
582  * \retval -1 The playback could not be queued.
583  */
584 int ast_bridge_channel_queue_playfile_sync(struct ast_bridge_channel *bridge_channel,
585                 ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
586
587 /*!
588  * \brief Custom callback run on a bridge channel.
589  *
590  * \param bridge_channel Which channel to operate on.
591  * \param payload Data to pass to the callback. (NULL if none).
592  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
593  *
594  * \note The payload MUST NOT have any resources that need to be freed.
595  *
596  * \return Nothing
597  */
598 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
599
600 enum ast_bridge_channel_custom_callback_option {
601         /*! The callback temporarily affects media. (Like a custom playfile.) */
602         AST_BRIDGE_CHANNEL_CB_OPTION_MEDIA = (1 << 0),
603 };
604
605 /*!
606  * \brief Write a bridge action custom callback frame into the bridge.
607  * \since 12.0.0
608  *
609  * \param bridge_channel Which channel is putting the frame into the bridge
610  * \param flags Custom callback option flags.
611  * \param callback Custom callback run on a bridge channel.
612  * \param payload Data to pass to the callback. (NULL if none).
613  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
614  *
615  * \note The payload MUST NOT have any resources that need to be freed.
616  *
617  * \note This is intended to be called by bridge hooks.
618  *
619  * \retval 0 on success.
620  * \retval -1 on error.
621  */
622 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel,
623         enum ast_bridge_channel_custom_callback_option flags,
624         ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
625
626 /*!
627  * \brief Queue a bridge action custom callback frame onto the bridge channel.
628  * \since 12.0.0
629  *
630  * \param bridge_channel Which channel to put the frame onto.
631  * \param flags Custom callback option flags.
632  * \param callback Custom callback run on a bridge channel.
633  * \param payload Data to pass to the callback. (NULL if none).
634  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
635  *
636  * \note The payload MUST NOT have any resources that need to be freed.
637  *
638  * \note This is intended to be called by bridge hooks.
639  *
640  * \retval 0 on success.
641  * \retval -1 on error.
642  */
643 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel,
644         enum ast_bridge_channel_custom_callback_option flags,
645         ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
646
647 /*!
648  * \brief Have a bridge channel park a channel in the bridge
649  * \since 12.0.0
650  *
651  * \param bridge_channel Bridge channel performing the parking
652  * \param parkee_uuid Unique id of the channel we want to park
653  * \param parker_uuid Unique id of the channel parking the call
654  * \param app_data string indicating data used for park application (NULL allowed)
655  *
656  * \note This is intended to be called by bridge hooks.
657  *
658  * \retval 0 on success.
659  * \retval -1 on error.
660  */
661 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
662         const char *parker_uuid, const char *app_data);
663
664 /*!
665  * \brief Kick the channel out of the bridge.
666  * \since 12.0.0
667  *
668  * \param bridge_channel Which channel is being kicked or hungup.
669  * \param cause Cause of channel being kicked.
670  *   If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
671  *
672  * \note This is intended to be called by bridge hooks and the
673  * bridge channel thread.
674  *
675  * \return Nothing
676  */
677 void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause);
678
679 /*!
680  * \brief Add a DTMF digit to the collected digits.
681  * \since 13.3.0
682  *
683  * \param bridge_channel Channel that received a DTMF digit.
684  * \param digit DTMF digit to add to collected digits
685  *
686  * \note Neither the bridge nor the bridge_channel locks should be held
687  * when entering this function.
688  *
689  * \note This is can only be called from within DTMF bridge hooks.
690  */
691 void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit);
692
693 /*!
694  * \brief Add a DTMF digit to the collected digits to match against DTMF features.
695  * \since 12.8.0
696  *
697  * \param bridge_channel Channel that received a DTMF digit.
698  * \param digit DTMF digit to add to collected digits or 0 for timeout event.
699  * \param clear_digits clear the digits array prior to calling hooks
700  *
701  * \note Neither the bridge nor the bridge_channel locks should be held
702  * when entering this function.
703  *
704  * \note This is intended to be called by bridge hooks and the
705  * bridge channel thread.
706  *
707  * \note This is intended to be called by non-DTMF bridge hooks and the bridge
708  * channel thread.  Calling from a DTMF bridge hook can potentially cause
709  * unbounded recursion.
710  *
711  * \return Nothing
712  */
713 void ast_bridge_channel_feature_digit(struct ast_bridge_channel *bridge_channel, int digit);
714
715 /*!
716  * \brief Maps a channel's stream topology to and from the bridge
717  * \since 15.0.0
718  *
719  * When a channel joins a bridge or its associated stream topology is updated, each stream
720  * in the topology needs to be mapped according to its media type to the bridge. Calling
721  * this method creates a mapping of each stream on the channel indexed to the bridge's
722  * supported media types and vice versa (i.e. bridge's media types indexed to channel
723  * streams).
724  *
725  * The first channel to join the bridge creates the initial order for the bridge's media
726  * types (e.g. a one to one mapping is made). Subsequently added channels are mapped to
727  * that order adding more media types if/when the newly added channel has more streams
728  * and/or media types specified by the bridge.
729  *
730  * \param bridge_channel Channel to map
731  *
732  * \return Nothing
733  */
734 void ast_bridge_channel_stream_map(struct ast_bridge_channel *bridge_channel);
735
736 #if defined(__cplusplus) || defined(c_plusplus)
737 }
738 #endif
739
740 #endif  /* _ASTERISK_BRIDGING_CHANNEL_H */