Asterisk - The Open Source Telephony Project  GIT-master-b91fb3c
bridge_channel.h
Go to the documentation of this file.
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 
58 
59 /*! \brief State information about a bridged channel */
61  /*! Waiting for a signal (Channel in the bridge) */
63  /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
65  /*! Bridged channel was forced out. Don't dissolve the bridge regardless */
67 };
68 
70  /*! Bridge channel thread is idle/waiting. */
72  /*! Bridge channel thread is writing a normal/simple frame. */
74  /*! Bridge channel thread is processing a frame. */
76 };
77 
78 struct ast_bridge;
80 
81  /*!
82  * \brief Structure that contains information regarding a channel in a bridge
83  */
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 */
88  /*! Current bridged channel 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  */
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 */
133  /*! Technology optimization parameters used by bridging technologies capable of
134  * optimizing based upon talk detection. */
136  /*! Copy of read format used by chan before join */
138  /*! Copy of write format used by chan before join */
140  /*! Call ID associated with bridge channel */
142  /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
144  /*! Linked list information */
146  /*! Queue of outgoing frames to the channel. */
148  /*! Queue of deferred frames, queued onto channel when other party joins. */
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  */
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) */
167  /*! Non-zero if a T.38 session terminate is owed to the bridge. */
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. */
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 Get a ref to the bridge_channel's ast_channel
198  *
199  * \param bridge_channel The bridge channel
200  *
201  * \note The returned channel NEEDS to be unref'd once you are done with it. In general, this
202  * function is best used when accessing the bridge_channel chan from outside of a bridging
203  * thread.
204  *
205  * \retval ref'd ast_channel on success
206  * \retval NULL otherwise
207  */
208 struct ast_channel *ast_bridge_channel_get_chan(struct ast_bridge_channel *bridge_channel);
209 
210 /*!
211  * \brief Try locking the bridge_channel.
212  *
213  * \param bridge_channel What to try locking
214  *
215  * \retval 0 on success.
216  * \retval non-zero on error.
217  */
218 #define ast_bridge_channel_trylock(bridge_channel) _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
219 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
220 {
221  return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
222 }
223 
224 /*!
225  * \brief Lock the bridge_channel.
226  *
227  * \param bridge_channel What to lock
228  *
229  * \return Nothing
230  */
231 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
232 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
233 {
234  __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
235 }
236 
237 /*!
238  * \brief Unlock the bridge_channel.
239  *
240  * \param bridge_channel What to unlock
241  *
242  * \return Nothing
243  */
244 #define ast_bridge_channel_unlock(bridge_channel) _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
245 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
246 {
247  __ao2_unlock(bridge_channel, file, function, line, var);
248 }
249 
250 /*!
251  * \brief Lock the bridge associated with the bridge channel.
252  * \since 12.0.0
253  *
254  * \param bridge_channel Channel that wants to lock the bridge.
255  *
256  * \details
257  * This is an upstream lock operation. The defined locking
258  * order is bridge then bridge_channel.
259  *
260  * \note On entry, neither the bridge nor bridge_channel is locked.
261  *
262  * \note The bridge_channel->bridge pointer changes because of a
263  * bridge-merge/channel-move operation between bridges.
264  *
265  * \return Nothing
266  */
267 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
268 
269 /*!
270  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
271  *
272  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
273  * layer, which in this case is the specific bridging technology being used. Since it
274  * is necessary for the knowledge of which channels are talking to make its way up to the
275  * application, this function has been created to allow the bridging technology to communicate
276  * that information with the bridging core.
277  *
278  * \param bridge_channel The bridge channel that has either started or stopped talking.
279  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
280  * when this indicates the channel has stopped talking.
281  *
282  * \retval 0 on success.
283  * \retval -1 on error.
284  */
285 int ast_bridge_channel_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking);
286 
287 /*!
288  * \brief Set bridge channel state to leave bridge (if not leaving already).
289  *
290  * \param bridge_channel Channel to change the state on
291  * \param new_state The new state to place the channel into
292  * \param cause Cause of channel leaving bridge.
293  * If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
294  *
295  * Example usage:
296  *
297  * \code
298  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
299  * \endcode
300  *
301  * This places the channel pointed to by bridge_channel into the
302  * state BRIDGE_CHANNEL_STATE_END if it was
303  * BRIDGE_CHANNEL_STATE_WAIT before.
304  */
305 void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
306 
307 /*!
308  * \brief Set bridge channel state to leave bridge (if not leaving already).
309  *
310  * \param bridge_channel Channel to change the state on
311  * \param new_state The new state to place the channel into
312  * \param cause Cause of channel leaving bridge.
313  * If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
314  *
315  * Example usage:
316  *
317  * \code
318  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
319  * \endcode
320  *
321  * This places the channel pointed to by bridge_channel into the
322  * state BRIDGE_CHANNEL_STATE_END if it was
323  * BRIDGE_CHANNEL_STATE_WAIT before.
324  */
325 void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause);
326 
327 /*!
328  * \brief Get the peer bridge channel of a two party bridge.
329  * \since 12.0.0
330  *
331  * \param bridge_channel What to get the peer of.
332  *
333  * \note On entry, bridge_channel->bridge is already locked.
334  *
335  * \note This is an internal bridge function.
336  *
337  * \retval peer on success.
338  * \retval NULL no peer channel.
339  */
340 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
341 
342 /*!
343  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_join
344  * \since 12.0.0
345  *
346  * \param bridge_channel Channel to restore
347  */
348 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
349 
350 /*!
351  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
352  * \since 12.0.0
353  *
354  * \param bridge_channel What to operate on.
355  * \param request Inhibit request increment.
356  * (Positive to add requests. Negative to remove requests.)
357  *
358  * \note This API call is meant for internal bridging operations.
359  *
360  * \retval bridge adjusted merge inhibit with reference count.
361  */
362 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
363 
364 /*!
365  * \internal
366  * \brief Update the linkedids for all channels in a bridge
367  * \since 12.0.0
368  *
369  * \param bridge_channel The channel joining the bridge
370  * \param swap The channel being swapped out of the bridge. May be NULL.
371  *
372  * \note The bridge must be locked prior to calling this function.
373  * \note This should be called during a \ref bridge_channel_internal_push
374  * operation, typically by a sub-class of a bridge.
375  */
377 
378 /*!
379  * \internal
380  * \brief Update the accountcodes for channels joining/leaving a bridge
381  * \since 12.0.0
382  *
383  * This function updates the accountcode and peeraccount on channels in two-party
384  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
385  * however accountcode propagation will still occur if the channel joining has an
386  * accountcode.
387  *
388  * \param joining The channel joining the bridge. May be NULL.
389  * \param leaving The channel leaving or being swapped out of the bridge. May be NULL.
390  *
391  * \note The joining and leaving parameters cannot both be NULL.
392  *
393  * \note The bridge must be locked prior to calling this function.
394  * \note This should be called during a \ref bridge_channel_internal_push
395  * or \ref bridge_channel_internal_pull operation, typically by a
396  * sub-class of a bridge.
397  */
399 
400 /*!
401  * \brief Write a frame to the specified bridge_channel.
402  * \since 12.0.0
403  *
404  * \param bridge_channel Channel to queue the frame.
405  * \param fr Frame to write.
406  *
407  * \retval 0 on success.
408  * \retval -1 on error.
409  */
410 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
411 
412 /*!
413  * \brief Queue a control frame onto the bridge channel with data.
414  * \since 12.0.0
415  *
416  * \param bridge_channel Which channel to queue the frame onto.
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_queue_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 control frame into the bridge with data.
428  * \since 12.0.0
429  *
430  * \param bridge_channel Which channel is putting the frame into the bridge.
431  * \param control Type of control frame.
432  * \param data Frame payload data to pass.
433  * \param datalen Frame payload data length to pass.
434  *
435  * \retval 0 on success.
436  * \retval -1 on error.
437  */
438 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);
439 
440 /*!
441  * \brief Write a hold frame into the bridge.
442  * \since 12.0.0
443  *
444  * \param bridge_channel Which channel is putting the hold into the bridge.
445  * \param moh_class The suggested music class for the other end to use.
446  *
447  * \retval 0 on success.
448  * \retval -1 on error.
449  */
450 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
451 
452 /*!
453  * \brief Write an unhold frame into the bridge.
454  * \since 12.0.0
455  *
456  * \param bridge_channel Which channel is putting the hold into the bridge.
457  *
458  * \retval 0 on success.
459  * \retval -1 on error.
460  */
461 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
462 
463 /*!
464  * \brief Run an application on the bridge channel.
465  * \since 12.0.0
466  *
467  * \param bridge_channel Which channel to run the application on.
468  * \param app_name Dialplan application name.
469  * \param app_args Arguments for the application. (NULL tolerant)
470  * \param moh_class MOH class to request bridge peers to hear while application is running.
471  * NULL if no MOH.
472  * Empty if default MOH class.
473  *
474  * \note This is intended to be called by bridge hooks.
475  *
476  * \return Nothing
477  */
478 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
479 
480 /*!
481  * \brief Write a bridge action run application frame into the bridge.
482  * \since 12.0.0
483  *
484  * \param bridge_channel Which channel is putting the frame into the bridge
485  * \param app_name Dialplan application name.
486  * \param app_args Arguments for the application. (NULL or empty for no arguments)
487  * \param moh_class MOH class to request bridge peers to hear while application is running.
488  * NULL if no MOH.
489  * Empty if default MOH class.
490  *
491  * \note This is intended to be called by bridge hooks.
492  *
493  * \retval 0 on success.
494  * \retval -1 on error.
495  */
496 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
497 
498 /*!
499  * \brief Queue a bridge action run application frame onto the bridge channel.
500  * \since 12.0.0
501  *
502  * \param bridge_channel Which channel to put the frame onto
503  * \param app_name Dialplan application name.
504  * \param app_args Arguments for the application. (NULL or empty for no arguments)
505  * \param moh_class MOH class to request bridge peers to hear while application is running.
506  * NULL if no MOH.
507  * Empty if default MOH class.
508  *
509  * \note This is intended to be called by bridge hooks.
510  *
511  * \retval 0 on success.
512  * \retval -1 on error.
513  */
514 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
515 
516 /*!
517  * \brief Custom interpretation of the playfile name.
518  *
519  * \param bridge_channel Which channel to play the file on
520  * \param playfile Sound filename to play.
521  *
522  * \return Nothing
523  */
524 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
525 
526 /*!
527  * \brief Play a file on the bridge channel.
528  * \since 12.0.0
529  *
530  * \param bridge_channel Which channel to play the file on
531  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
532  * \param playfile Sound filename to play.
533  * \param moh_class MOH class to request bridge peers to hear while file is played.
534  * NULL if no MOH.
535  * Empty if default MOH class.
536  *
537  * \note This is intended to be called by bridge hooks.
538  *
539  * \return Nothing
540  */
541 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);
542 
543 /*!
544  * \brief Write a bridge action play file frame into the bridge.
545  * \since 12.0.0
546  *
547  * \param bridge_channel Which channel is putting the frame into the bridge
548  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
549  * \param playfile Sound filename to play.
550  * \param moh_class MOH class to request bridge peers to hear while file is played.
551  * NULL if no MOH.
552  * Empty if default MOH class.
553  *
554  * \note This is intended to be called by bridge hooks.
555  *
556  * \retval 0 on success.
557  * \retval -1 on error.
558  */
559 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);
560 
561 /*!
562  * \brief Queue a bridge action play file frame onto the bridge channel.
563  * \since 12.0.0
564  *
565  * \param bridge_channel Which channel to put the frame onto.
566  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
567  * \param playfile Sound filename to play.
568  * \param moh_class MOH class to request bridge peers to hear while file is played.
569  * NULL if no MOH.
570  * Empty if default MOH class.
571  *
572  * \note This is intended to be called by bridge hooks.
573  *
574  * \retval 0 on success.
575  * \retval -1 on error.
576  */
577 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);
578 
579 /*!
580  * \brief Synchronously queue a bridge action play file frame onto the bridge channel.
581  * \since 12.2.0
582  *
583  * \param bridge_channel Which channel to put the frame onto.
584  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
585  * \param playfile Sound filename to play.
586  * \param moh_class MOH class to request bridge peers to hear while file is played.
587  * NULL if no MOH.
588  * Empty if default MOH class.
589  *
590  * This function will block until the queued frame has been destroyed. This will happen
591  * either if an error occurs or if the queued playback finishes.
592  *
593  * \note No locks may be held when calling this function.
594  *
595  * \retval 0 The playback was successfully queued.
596  * \retval -1 The playback could not be queued.
597  */
599  ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
600 
601 /*!
602  * \brief Custom callback run on a bridge channel.
603  *
604  * \param bridge_channel Which channel to operate on.
605  * \param payload Data to pass to the callback. (NULL if none).
606  * \param payload_size Size of the payload if payload is non-NULL. A number otherwise.
607  *
608  * \note The payload MUST NOT have any resources that need to be freed.
609  *
610  * \return Nothing
611  */
612 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
613 
615  /*! The callback temporarily affects media. (Like a custom playfile.) */
617 };
618 
619 /*!
620  * \brief Write a bridge action custom callback frame into the bridge.
621  * \since 12.0.0
622  *
623  * \param bridge_channel Which channel is putting the frame into the bridge
624  * \param flags Custom callback option flags.
625  * \param callback Custom callback run on a bridge channel.
626  * \param payload Data to pass to the callback. (NULL if none).
627  * \param payload_size Size of the payload if payload is non-NULL. A number otherwise.
628  *
629  * \note The payload MUST NOT have any resources that need to be freed.
630  *
631  * \note This is intended to be called by bridge hooks.
632  *
633  * \retval 0 on success.
634  * \retval -1 on error.
635  */
636 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel,
638  ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
639 
640 /*!
641  * \brief Queue a bridge action custom callback frame onto the bridge channel.
642  * \since 12.0.0
643  *
644  * \param bridge_channel Which channel to put the frame onto.
645  * \param flags Custom callback option flags.
646  * \param callback Custom callback run on a bridge channel.
647  * \param payload Data to pass to the callback. (NULL if none).
648  * \param payload_size Size of the payload if payload is non-NULL. A number otherwise.
649  *
650  * \note The payload MUST NOT have any resources that need to be freed.
651  *
652  * \note This is intended to be called by bridge hooks.
653  *
654  * \retval 0 on success.
655  * \retval -1 on error.
656  */
657 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel,
659  ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
660 
661 /*!
662  * \brief Have a bridge channel park a channel in the bridge
663  * \since 12.0.0
664  *
665  * \param bridge_channel Bridge channel performing the parking
666  * \param parkee_uuid Unique id of the channel we want to park
667  * \param parker_uuid Unique id of the channel parking the call
668  * \param app_data string indicating data used for park application (NULL allowed)
669  *
670  * \note This is intended to be called by bridge hooks.
671  *
672  * \retval 0 on success.
673  * \retval -1 on error.
674  */
675 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
676  const char *parker_uuid, const char *app_data);
677 
678 /*!
679  * \brief Kick the channel out of the bridge.
680  * \since 12.0.0
681  *
682  * \param bridge_channel Which channel is being kicked or hungup.
683  * \param cause Cause of channel being kicked.
684  * If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
685  *
686  * \note This is intended to be called by bridge hooks and the
687  * bridge channel thread.
688  *
689  * \return Nothing
690  */
691 void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause);
692 
693 /*!
694  * \brief Add a DTMF digit to the collected digits.
695  * \since 13.3.0
696  *
697  * \param bridge_channel Channel that received a DTMF digit.
698  * \param digit DTMF digit to add to collected digits
699  *
700  * \note Neither the bridge nor the bridge_channel locks should be held
701  * when entering this function.
702  *
703  * \note This is can only be called from within DTMF bridge hooks.
704  */
705 void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit);
706 
707 /*!
708  * \brief Add a DTMF digit to the collected digits to match against DTMF features.
709  * \since 12.8.0
710  *
711  * \param bridge_channel Channel that received a DTMF digit.
712  * \param digit DTMF digit to add to collected digits or 0 for timeout event.
713  * \param clear_digits clear the digits array prior to calling hooks
714  *
715  * \note Neither the bridge nor the bridge_channel locks should be held
716  * when entering this function.
717  *
718  * \note This is intended to be called by bridge hooks and the
719  * bridge channel thread.
720  *
721  * \note This is intended to be called by non-DTMF bridge hooks and the bridge
722  * channel thread. Calling from a DTMF bridge hook can potentially cause
723  * unbounded recursion.
724  *
725  * \return Nothing
726  */
727 void ast_bridge_channel_feature_digit(struct ast_bridge_channel *bridge_channel, int digit);
728 
729 /*!
730  * \brief Maps a channel's stream topology to and from the bridge
731  * \since 15.0.0
732  *
733  * \details
734  * When a channel joins a bridge or its associated stream topology is
735  * updated, each stream in the topology needs to be mapped according
736  * to its media type to the bridge. Calling this method creates a
737  * mapping of each stream on the channel indexed to the bridge's
738  * supported media types and vice versa (i.e. bridge's media types
739  * indexed to channel streams).
740  *
741  * The first channel to join the bridge creates the initial order for
742  * the bridge's media types (e.g. a one to one mapping is made).
743  * Subsequently added channels are mapped to that order adding more
744  * media types if/when the newly added channel has more streams and/or
745  * media types specified by the bridge.
746  *
747  * \param bridge_channel Channel to map
748  *
749  * \note The bridge_channel's bridge must be locked prior to calling this function.
750  *
751  * \return Nothing
752  */
753 void ast_bridge_channel_stream_map(struct ast_bridge_channel *bridge_channel);
754 
755 #if defined(__cplusplus) || defined(c_plusplus)
756 }
757 #endif
758 
759 #endif /* _ASTERISK_BRIDGING_CHANNEL_H */
char digit
Main Channel structure associated with a channel.
enum bridge_channel_thread_state activity
The bridge channel thread activity.
struct ast_bridge * ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request)
Adjust the bridge_channel&#39;s bridge merge inhibit request count.
struct ast_bridge_features * features
struct ast_channel * ast_bridge_channel_get_chan(struct ast_bridge_channel *bridge_channel)
Get a ref to the bridge_channel&#39;s ast_channel.
bridge_channel_state
State information about a bridged channel.
void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause)
Set bridge channel state to leave bridge (if not leaving already).
Structure that contains features information.
struct ast_bridge_channel::@224 wr_queue
void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause)
Kick the channel out of the bridge.
struct ast_bridge_channel * ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel)
Get the peer bridge channel of a two party bridge.
int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
Lock an object.
Definition: astobj2.c:222
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)
Write a control frame into the bridge with data.
int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class)
Write a bridge action run application frame into the bridge.
void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class)
Run an application on the bridge channel.
int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid, const char *parker_uuid, const char *app_data)
Have a bridge channel park a channel in the bridge.
#define var
Definition: ast_expr2f.c:614
enum bridge_channel_state state
unsigned int suspended
void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit)
Add a DTMF digit to the collected digits.
int __ao2_unlock(void *a, const char *file, const char *func, int line, const char *var)
Unlock an object.
Definition: astobj2.c:288
void(* ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size)
Custom callback run on a bridge channel.
Definition of a media format.
Definition: format.c:43
int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class)
Queue a bridge action run application frame onto the bridge channel.
ast_control_frame_type
Internal control frame subtype field values.
unsigned int ast_callid
Definition: logger.h:87
int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_custom_callback_option flags, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size)
Write a bridge action custom callback frame into the bridge.
unsigned int binaural_suspended
void ast_bridge_channel_feature_digit(struct ast_bridge_channel *bridge_channel, int digit)
Add a DTMF digit to the collected digits to match against DTMF features.
char collected[MAXIMUM_DTMF_FEATURE_STRING]
struct timeval dtmf_tv
struct ast_vector_int to_bridge
struct ast_bridge * bridge
Bridge this channel is participating in.
pthread_cond_t ast_cond_t
Definition: lock.h:176
static void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap)
void(* ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile)
Custom interpretation of the playfile name.
int ast_bridge_channel_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking)
Lets the bridging indicate when a bridge channel has stopped or started talking.
Channel Bridging API.
#define MAXIMUM_DTMF_FEATURE_STRING
Maximum length of a DTMF feature string.
struct timeval interdigit_timeout
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
unsigned int just_joined
struct ast_format * write_format
struct ast_vector_int to_channel
Structure that contains information about a bridge.
Definition: bridge.h:357
struct bridge_roles_datastore * bridge_roles
static int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
struct ast_bridge_channel::@225 deferred_queue
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)
Write a bridge action play file frame into the bridge.
int __ao2_trylock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var)
Try locking– (don&#39;t block if fail)
Definition: astobj2.c:342
struct ast_bridge_tech_optimizations tech_args
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
struct ast_format * read_format
void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel, enum bridge_channel_state new_state, int cause)
Set bridge channel state to leave bridge (if not leaving already).
int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_custom_callback_option flags, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size)
Queue a bridge action custom callback frame onto the bridge channel.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
unsigned int in_bridge
unsigned int inhibit_colp
bridge_channel_thread_state
struct ast_bridge_channel::@223 entry
static int request(void *obj)
Definition: chan_pjsip.c:2641
void * tech_pvt
Private information unique to the bridge technology.
static void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
struct ast_channel * swap
unsigned int padding
int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class)
Write a hold frame into the bridge.
int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr)
Write a frame to the specified bridge_channel.
void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *joining, struct ast_bridge_channel *leaving)
struct ast_channel * chan
Structure that contains information regarding a channel in a bridge.
void * bridge_pvt
Bridge class private channel data.
void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel)
Lock the bridge associated with the bridge channel.
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)
Queue a bridge action play file frame onto the bridge channel.
void ast_bridge_channel_stream_map(struct ast_bridge_channel *bridge_channel)
Maps a channel&#39;s stream topology to and from the bridge.
Data structure associated with a single frame of data.
struct ast_bridge_channel::@230 stream_map
unsigned int binaural_pos_change
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)
Queue a control frame onto the bridge channel with data.
int ast_bridge_channel_queue_playfile_sync(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class)
Synchronously queue a bridge action play file frame onto the bridge channel.
unsigned int depart_wait
void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel)
Restore the formats of a bridge channel&#39;s channel to how they were before bridge_channel_internal_joi...
struct ast_bridge_channel::@227 dtmf_hook_state
int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel)
Write an unhold frame into the bridge.
ast_bridge_channel_custom_callback_option
Structure specific to bridge technologies capable of performing talking optimizations.
struct ast_bridge_channel::@226 owed
Channel Bridging API.
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)
Play a file on the bridge channel.