Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 ast_bridge "\c ast_bridge"
37  * \arg The \ref ast_bridge_channel "\c ast_bridge_channel"
38  * \arg The \ref ast_channel "\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. */
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;
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  */
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 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
230 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
231 {
233 }
234 
235 /*!
236  * \brief Unlock the bridge_channel.
237  *
238  * \param bridge_channel What to unlock
239  */
240 #define ast_bridge_channel_unlock(bridge_channel) _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
241 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
242 {
243  __ao2_unlock(bridge_channel, file, function, line, var);
244 }
245 
246 /*!
247  * \brief Lock the bridge associated with the bridge channel.
248  * \since 12.0.0
249  *
250  * \param bridge_channel Channel that wants to lock the bridge.
251  *
252  * \details
253  * This is an upstream lock operation. The defined locking
254  * order is bridge then bridge_channel.
255  *
256  * \note On entry, neither the bridge nor bridge_channel is locked.
257  *
258  * \note The bridge_channel->bridge pointer changes because of a
259  * bridge-merge/channel-move operation between bridges.
260  */
262 
263 /*!
264  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
265  *
266  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
267  * layer, which in this case is the specific bridging technology being used. Since it
268  * is necessary for the knowledge of which channels are talking to make its way up to the
269  * application, this function has been created to allow the bridging technology to communicate
270  * that information with the bridging core.
271  *
272  * \param bridge_channel The bridge channel that has either started or stopped talking.
273  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
274  * when this indicates the channel has stopped talking.
275  *
276  * \retval 0 on success.
277  * \retval -1 on error.
278  */
280 
281 /*!
282  * \brief Set bridge channel state to leave bridge (if not leaving already).
283  *
284  * \param bridge_channel Channel to change the state on
285  * \param new_state The new state to place the channel into
286  * \param cause Cause of channel leaving bridge.
287  * If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
288  *
289  * Example usage:
290  *
291  * \code
292  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
293  * \endcode
294  *
295  * This places the channel pointed to by bridge_channel into the
296  * state BRIDGE_CHANNEL_STATE_END if it was
297  * BRIDGE_CHANNEL_STATE_WAIT before.
298  */
300 
301 /*!
302  * \brief Set bridge channel state to leave bridge (if not leaving already).
303  *
304  * \param bridge_channel Channel to change the state on
305  * \param new_state The new state to place the channel into
306  * \param cause Cause of channel leaving bridge.
307  * If cause <= 0 then use cause on channel if cause still <= 0 use AST_CAUSE_NORMAL_CLEARING.
308  *
309  * Example usage:
310  *
311  * \code
312  * ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END, AST_CAUSE_NORMAL_CLEARING);
313  * \endcode
314  *
315  * This places the channel pointed to by bridge_channel into the
316  * state BRIDGE_CHANNEL_STATE_END if it was
317  * BRIDGE_CHANNEL_STATE_WAIT before.
318  */
320 
321 /*!
322  * \brief Get the peer bridge channel of a two party bridge.
323  * \since 12.0.0
324  *
325  * \param bridge_channel What to get the peer of.
326  *
327  * \note On entry, bridge_channel->bridge is already locked.
328  *
329  * \note This is an internal bridge function.
330  *
331  * \retval peer on success.
332  * \retval NULL no peer channel.
333  */
334 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
335 
336 /*!
337  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_join
338  * \since 12.0.0
339  *
340  * \param bridge_channel Channel to restore
341  */
342 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
343 
344 /*!
345  * \brief Adjust the bridge_channel's bridge merge inhibit request count.
346  * \since 12.0.0
347  *
348  * \param bridge_channel What to operate on.
349  * \param request Inhibit request increment.
350  * (Positive to add requests. Negative to remove requests.)
351  *
352  * \note This API call is meant for internal bridging operations.
353  *
354  * \retval bridge adjusted merge inhibit with reference count.
355  */
356 struct ast_bridge *ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request);
357 
358 /*!
359  * \internal
360  * \brief Update the linkedids for all channels in a bridge
361  * \since 12.0.0
362  *
363  * \param bridge_channel The channel joining the bridge
364  * \param swap The channel being swapped out of the bridge. May be NULL.
365  *
366  * \note The bridge must be locked prior to calling this function.
367  * \note This should be called during a \ref bridge_channel_internal_push
368  * operation, typically by a sub-class of a bridge.
369  */
370 void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap);
371 
372 /*!
373  * \internal
374  * \brief Update the accountcodes for channels joining/leaving a bridge
375  * \since 12.0.0
376  *
377  * This function updates the accountcode and peeraccount on channels in two-party
378  * bridges. In multi-party bridges, peeraccount is not set - it doesn't make much sense -
379  * however accountcode propagation will still occur if the channel joining has an
380  * accountcode.
381  *
382  * \param joining The channel joining the bridge. May be NULL.
383  * \param leaving The channel leaving or being swapped out of the bridge. May be NULL.
384  *
385  * \note The joining and leaving parameters cannot both be NULL.
386  *
387  * \note The bridge must be locked prior to calling this function.
388  * \note This should be called during a \ref bridge_channel_internal_push
389  * or \ref bridge_channel_internal_pull operation, typically by a
390  * sub-class of a bridge.
391  */
393 
394 /*!
395  * \brief Write a frame to the specified bridge_channel.
396  * \since 12.0.0
397  *
398  * \param bridge_channel Channel to queue the frame.
399  * \param fr Frame to write.
400  *
401  * \retval 0 on success.
402  * \retval -1 on error.
403  */
404 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
405 
406 /*!
407  * \brief Queue a control frame onto the bridge channel with data.
408  * \since 12.0.0
409  *
410  * \param bridge_channel Which channel to queue the frame onto.
411  * \param control Type of control frame.
412  * \param data Frame payload data to pass.
413  * \param datalen Frame payload data length to pass.
414  *
415  * \retval 0 on success.
416  * \retval -1 on error.
417  */
418 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);
419 
420 /*!
421  * \brief Write a control frame into the bridge with data.
422  * \since 12.0.0
423  *
424  * \param bridge_channel Which channel is putting the frame into the bridge.
425  * \param control Type of control frame.
426  * \param data Frame payload data to pass.
427  * \param datalen Frame payload data length to pass.
428  *
429  * \retval 0 on success.
430  * \retval -1 on error.
431  */
432 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);
433 
434 /*!
435  * \brief Write a hold frame into the bridge.
436  * \since 12.0.0
437  *
438  * \param bridge_channel Which channel is putting the hold into the bridge.
439  * \param moh_class The suggested music class for the other end to use.
440  *
441  * \retval 0 on success.
442  * \retval -1 on error.
443  */
444 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
445 
446 /*!
447  * \brief Write an unhold frame into the bridge.
448  * \since 12.0.0
449  *
450  * \param bridge_channel Which channel is putting the hold into the bridge.
451  *
452  * \retval 0 on success.
453  * \retval -1 on error.
454  */
455 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
456 
457 /*!
458  * \brief Run an application on the bridge channel.
459  * \since 12.0.0
460  *
461  * \param bridge_channel Which channel to run the application on.
462  * \param app_name Dialplan application name.
463  * \param app_args Arguments for the application. (NULL tolerant)
464  * \param moh_class MOH class to request bridge peers to hear while application is running.
465  * NULL if no MOH.
466  * Empty if default MOH class.
467  *
468  * \note This is intended to be called by bridge hooks.
469  */
470 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
471 
472 /*!
473  * \brief Write a bridge action run application frame into the bridge.
474  * \since 12.0.0
475  *
476  * \param bridge_channel Which channel is putting the frame into the bridge
477  * \param app_name Dialplan application name.
478  * \param app_args Arguments for the application. (NULL or empty for no arguments)
479  * \param moh_class MOH class to request bridge peers to hear while application is running.
480  * NULL if no MOH.
481  * Empty if default MOH class.
482  *
483  * \note This is intended to be called by bridge hooks.
484  *
485  * \retval 0 on success.
486  * \retval -1 on error.
487  */
488 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
489 
490 /*!
491  * \brief Queue a bridge action run application frame onto the bridge channel.
492  * \since 12.0.0
493  *
494  * \param bridge_channel Which channel to put the frame onto
495  * \param app_name Dialplan application name.
496  * \param app_args Arguments for the application. (NULL or empty for no arguments)
497  * \param moh_class MOH class to request bridge peers to hear while application is running.
498  * NULL if no MOH.
499  * Empty if default MOH class.
500  *
501  * \note This is intended to be called by bridge hooks.
502  *
503  * \retval 0 on success.
504  * \retval -1 on error.
505  */
506 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
507 
508 /*!
509  * \brief Custom interpretation of the playfile name.
510  *
511  * \param bridge_channel Which channel to play the file on
512  * \param playfile Sound filename to play.
513  */
514 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
515 
516 /*!
517  * \brief Play a file on the bridge channel.
518  * \since 12.0.0
519  *
520  * \param bridge_channel Which channel to play the file on
521  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
522  * \param playfile Sound filename to play.
523  * \param moh_class MOH class to request bridge peers to hear while file is played.
524  * NULL if no MOH.
525  * Empty if default MOH class.
526  *
527  * \note This is intended to be called by bridge hooks.
528  */
529 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);
530 
531 /*!
532  * \brief Write a bridge action play file frame into the bridge.
533  * \since 12.0.0
534  *
535  * \param bridge_channel Which channel is putting the frame into the bridge
536  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
537  * \param playfile Sound filename to play.
538  * \param moh_class MOH class to request bridge peers to hear while file is played.
539  * NULL if no MOH.
540  * Empty if default MOH class.
541  *
542  * \note This is intended to be called by bridge hooks.
543  *
544  * \retval 0 on success.
545  * \retval -1 on error.
546  */
547 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);
548 
549 /*!
550  * \brief Queue a bridge action play file frame onto the bridge channel.
551  * \since 12.0.0
552  *
553  * \param bridge_channel Which channel to put the frame onto.
554  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
555  * \param playfile Sound filename to play.
556  * \param moh_class MOH class to request bridge peers to hear while file is played.
557  * NULL if no MOH.
558  * Empty if default MOH class.
559  *
560  * \note This is intended to be called by bridge hooks.
561  *
562  * \retval 0 on success.
563  * \retval -1 on error.
564  */
565 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);
566 
567 /*!
568  * \brief Synchronously queue a bridge action play file frame onto the bridge channel.
569  * \since 12.2.0
570  *
571  * \param bridge_channel Which channel to put the frame onto.
572  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
573  * \param playfile Sound filename to play.
574  * \param moh_class MOH class to request bridge peers to hear while file is played.
575  * NULL if no MOH.
576  * Empty if default MOH class.
577  *
578  * This function will block until the queued frame has been destroyed. This will happen
579  * either if an error occurs or if the queued playback finishes.
580  *
581  * \note No locks may be held when calling this function.
582  *
583  * \retval 0 The playback was successfully queued.
584  * \retval -1 The playback could not be queued.
585  */
587  ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
588 
589 /*!
590  * \brief Custom callback run on a bridge channel.
591  *
592  * \param bridge_channel Which channel to operate on.
593  * \param payload Data to pass to the callback. (NULL if none).
594  * \param payload_size Size of the payload if payload is non-NULL. A number otherwise.
595  *
596  * \note The payload MUST NOT have any resources that need to be freed.
597  */
598 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
599 
601  /*! The callback temporarily affects media. (Like a custom playfile.) */
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,
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,
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 void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause);
676 
677 /*!
678  * \brief Add a DTMF digit to the collected digits.
679  * \since 13.3.0
680  *
681  * \param bridge_channel Channel that received a DTMF digit.
682  * \param digit DTMF digit to add to collected digits
683  *
684  * \note Neither the bridge nor the bridge_channel locks should be held
685  * when entering this function.
686  *
687  * \note This is can only be called from within DTMF bridge hooks.
688  */
689 void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit);
690 
691 /*!
692  * \brief Add a DTMF digit to the collected digits to match against DTMF features.
693  * \since 12.8.0
694  *
695  * \param bridge_channel Channel that received a DTMF digit.
696  * \param digit DTMF digit to add to collected digits or 0 for timeout event.
697  *
698  * \note Neither the bridge nor the bridge_channel locks should be held
699  * when entering this function.
700  *
701  * \note This is intended to be called by bridge hooks and the
702  * bridge channel thread.
703  *
704  * \note This is intended to be called by non-DTMF bridge hooks and the bridge
705  * channel thread. Calling from a DTMF bridge hook can potentially cause
706  * unbounded recursion.
707  */
708 void ast_bridge_channel_feature_digit(struct ast_bridge_channel *bridge_channel, int digit);
709 
710 /*!
711  * \brief Maps a channel's stream topology to and from the bridge
712  * \since 15.0.0
713  *
714  * \details
715  * When a channel joins a bridge or its associated stream topology is
716  * updated, each stream in the topology needs to be mapped according
717  * to its media type to the bridge. Calling this method creates a
718  * mapping of each stream on the channel indexed to the bridge's
719  * supported media types and vice versa (i.e. bridge's media types
720  * indexed to channel streams).
721  *
722  * The first channel to join the bridge creates the initial order for
723  * the bridge's media types (e.g. a one to one mapping is made).
724  * Subsequently added channels are mapped to that order adding more
725  * media types if/when the newly added channel has more streams and/or
726  * media types specified by the bridge.
727  *
728  * \param bridge_channel Channel to map
729  *
730  * \note The bridge_channel's bridge must be locked prior to calling this function.
731  */
732 void ast_bridge_channel_stream_map(struct ast_bridge_channel *bridge_channel);
733 
734 #if defined(__cplusplus) || defined(c_plusplus)
735 }
736 #endif
737 
738 #endif /* _ASTERISK_BRIDGING_CHANNEL_H */
char digit
#define var
Definition: ast_expr2f.c:614
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't block if fail)
Definition: astobj2.c:342
@ AO2_LOCK_REQ_MUTEX
Definition: astobj2.h:702
int __ao2_unlock(void *a, const char *file, const char *func, int line, const char *var)
Unlock an object.
Definition: astobj2.c:288
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
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.
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.
struct ast_bridge_channel * ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel)
Get the peer bridge channel of a two party 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.
void ast_bridge_channel_update_linkedids(struct ast_bridge_channel *bridge_channel, struct ast_bridge_channel *swap)
void ast_bridge_channel_feature_digit_add(struct ast_bridge_channel *bridge_channel, int digit)
Add a DTMF digit to the collected digits.
ast_bridge_channel_custom_callback_option
@ AST_BRIDGE_CHANNEL_CB_OPTION_MEDIA
int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel)
Write an unhold frame into the bridge.
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.
static void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
void ast_bridge_channel_update_accountcodes(struct ast_bridge_channel *joining, struct ast_bridge_channel *leaving)
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.
static int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
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.
void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel)
Lock the bridge associated with the bridge channel.
void ast_bridge_channel_kick(struct ast_bridge_channel *bridge_channel, int cause)
Kick the channel out of the bridge.
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.
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.
void ast_bridge_channel_stream_map(struct ast_bridge_channel *bridge_channel)
Maps a channel's stream topology to and from the bridge.
struct ast_bridge * ast_bridge_channel_merge_inhibit(struct ast_bridge_channel *bridge_channel, int request)
Adjust the bridge_channel's bridge merge inhibit request count.
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).
bridge_channel_state
State information about a bridged channel.
@ BRIDGE_CHANNEL_STATE_END_NO_DISSOLVE
@ BRIDGE_CHANNEL_STATE_WAIT
@ BRIDGE_CHANNEL_STATE_END
int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr)
Write a frame to the specified bridge_channel.
static void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
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(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_restore_formats(struct ast_bridge_channel *bridge_channel)
Restore the formats of a bridge channel's channel to how they were before bridge_channel_internal_joi...
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.
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.
bridge_channel_thread_state
@ BRIDGE_CHANNEL_THREAD_FRAME
@ BRIDGE_CHANNEL_THREAD_SIMPLE
@ BRIDGE_CHANNEL_THREAD_IDLE
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_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class)
Write a hold frame into the bridge.
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.
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.
struct ast_channel * ast_bridge_channel_get_chan(struct ast_bridge_channel *bridge_channel)
Get a ref to the bridge_channel's ast_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.
void(* ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile)
Custom interpretation of the playfile name.
Channel Bridging API.
#define MAXIMUM_DTMF_FEATURE_STRING
Maximum length of a DTMF feature string.
Channel Bridging API.
static int request(void *obj)
Definition: chan_pjsip.c:2580
ast_control_frame_type
Internal control frame subtype field values.
unsigned int ast_callid
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
pthread_cond_t ast_cond_t
Definition: lock.h:176
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
Structure that contains information regarding a channel in a bridge.
struct ast_vector_int to_bridge
void * tech_pvt
Private information unique to the bridge technology.
void * bridge_pvt
Bridge class private channel data.
struct ast_bridge_channel::@226 stream_map
unsigned int suspended
struct ast_bridge_channel::@220 wr_queue
struct ast_bridge_channel::@219 entry
struct ast_channel * swap
struct bridge_roles_datastore * bridge_roles
struct ast_format * write_format
struct ast_bridge * bridge
Bridge this channel is participating in.
unsigned int binaural_suspended
struct timeval interdigit_timeout
char collected[MAXIMUM_DTMF_FEATURE_STRING]
struct ast_bridge_channel::@223 dtmf_hook_state
struct ast_bridge_features * features
unsigned int binaural_pos_change
struct ast_bridge_channel::@221 deferred_queue
struct timeval dtmf_tv
unsigned int just_joined
struct ast_channel * chan
struct ast_format * read_format
enum bridge_channel_state state
struct ast_vector_int to_channel
unsigned int inhibit_colp
unsigned int depart_wait
enum bridge_channel_thread_state activity
The bridge channel thread activity.
struct ast_bridge_tech_optimizations tech_args
unsigned int padding
struct ast_bridge_channel::@222 owed
unsigned int in_bridge
Structure that contains features information.
Structure specific to bridge technologies capable of performing talking optimizations.
Structure that contains information about a bridge.
Definition: bridge.h:349
Main Channel structure associated with a channel.
struct ast_bridge_channel * bridge_channel
Definition of a media format.
Definition: format.c:43
Data structure associated with a single frame of data.
Integer vector definition.
Definition: vector.h:52