Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
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)
53extern "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
78struct 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 */
92 /*! Asterisk channel we are swapping with (if swapping) */
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 */
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. */
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. */
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 */
191 /*! An index mapping of where a bridge's media needs to be routed */
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)
219static 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)
230static 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)
241static 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 */
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 */
342void 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 */
356struct 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 */
370void 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 */
404int 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 */
418int 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 */
432int 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 */
444int 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 */
455int 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 */
470void 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 */
488int 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 */
506int 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 */
514typedef 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 */
529void 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 */
547int 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 */
565int 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 */
598typedef 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 */
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 */
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 */
661int 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 */
675void 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 */
689void 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 */
708void 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 */
732void 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:605
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.
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.
struct ast_channel * ast_bridge_channel_get_chan(struct ast_bridge_channel *bridge_channel)
Get a ref to the bridge_channel's ast_channel.
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.
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_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.
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:2605
ast_control_frame_type
Internal control frame subtype field values.
unsigned int ast_callid
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
#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:178
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
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::@198 stream_map
unsigned int suspended
struct ast_bridge_channel::@195 dtmf_hook_state
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 ast_bridge_channel::@194 owed
struct timeval interdigit_timeout
char collected[MAXIMUM_DTMF_FEATURE_STRING]
struct ast_bridge_channel::@191 entry
struct ast_bridge_features * features
unsigned int binaural_pos_change
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_channel::@192 wr_queue
struct ast_bridge_tech_optimizations tech_args
struct ast_bridge_channel::@193 deferred_queue
unsigned int padding
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