confbridge: Fix MOH on simultaneous user entry to a new conference.
[asterisk/asterisk.git] / include / asterisk / bridging.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007 - 2009, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Channel Bridging API
21  * \author Joshua Colp <jcolp@digium.com>
22  * \ref AstBridging
23  */
24
25 /*!
26  * \page AstBridging Channel Bridging API
27  *
28  * The purpose of this API is to provide an easy and flexible way to bridge
29  * channels of different technologies with different features.
30  *
31  * Bridging technologies provide the mechanism that do the actual handling
32  * of frames between channels. They provide capability information, codec information,
33  * and preference value to assist the bridging core in choosing a bridging technology when
34  * creating a bridge. Different bridges may use different bridging technologies based on needs
35  * but once chosen they all operate under the same premise; they receive frames and send frames.
36  *
37  * Bridges are a combination of bridging technology, channels, and features. A
38  * developer creates a new bridge based on what they are currently expecting to do
39  * with it or what they will do with it in the future. The bridging core determines what
40  * available bridging technology will best fit the requirements and creates a new bridge.
41  * Once created, channels can be added to the bridge in a blocking or non-blocking fashion.
42  *
43  * Features are such things as channel muting or DTMF based features such as attended transfer,
44  * blind transfer, and hangup. Feature information must be set at the most granular level, on
45  * the channel. While you can use features on a global scope the presence of a feature structure
46  * on the channel will override the global scope. An example would be having the bridge muted
47  * at global scope and attended transfer enabled on a channel. Since the channel itself is not muted
48  * it would be able to speak.
49  *
50  * Feature hooks allow a developer to tell the bridging core that when a DTMF string
51  * is received from a channel a callback should be called in their application. For
52  * example, a conference bridge application may want to provide an IVR to control various
53  * settings on the conference bridge. This can be accomplished by attaching a feature hook
54  * that calls an IVR function when a DTMF string is entered.
55  *
56  */
57
58 #ifndef _ASTERISK_BRIDGING_H
59 #define _ASTERISK_BRIDGING_H
60
61 #if defined(__cplusplus) || defined(c_plusplus)
62 extern "C" {
63 #endif
64
65 #include "asterisk/bridging_features.h"
66 #include "asterisk/dsp.h"
67
68 /*! \brief Capabilities for a bridge technology */
69 enum ast_bridge_capability {
70         /*! Bridge is only capable of mixing 2 channels */
71         AST_BRIDGE_CAPABILITY_1TO1MIX = (1 << 1),
72         /*! Bridge is capable of mixing 2 or more channels */
73         AST_BRIDGE_CAPABILITY_MULTIMIX = (1 << 2),
74         /*! Bridge should natively bridge two channels if possible */
75         AST_BRIDGE_CAPABILITY_NATIVE = (1 << 3),
76         /*! Bridge should run using the multithreaded model */
77         AST_BRIDGE_CAPABILITY_MULTITHREADED = (1 << 4),
78         /*! Bridge should run a central bridge thread */
79         AST_BRIDGE_CAPABILITY_THREAD = (1 << 5),
80         /*! Bridge technology can do video mixing (or something along those lines) */
81         AST_BRIDGE_CAPABILITY_VIDEO = (1 << 6),
82         /*! Bridge technology can optimize things based on who is talking */
83         AST_BRIDGE_CAPABILITY_OPTIMIZE = (1 << 7),
84 };
85
86 /*! \brief State information about a bridged channel */
87 enum ast_bridge_channel_state {
88         /*! Waiting for a signal */
89         AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
90         /*! Bridged channel has ended itself (it has hung up) */
91         AST_BRIDGE_CHANNEL_STATE_END,
92         /*! Bridged channel should be hung up */
93         AST_BRIDGE_CHANNEL_STATE_HANGUP,
94         /*! Bridged channel should be removed from the bridge without being hung up */
95         AST_BRIDGE_CHANNEL_STATE_DEPART,
96         /*! Bridged channel is executing a feature hook */
97         AST_BRIDGE_CHANNEL_STATE_FEATURE,
98         /*! Bridged channel is sending a DTMF stream out */
99         AST_BRIDGE_CHANNEL_STATE_DTMF,
100         /*! Bridged channel began talking */
101         AST_BRIDGE_CHANNEL_STATE_START_TALKING,
102         /*! Bridged channel has stopped talking */
103         AST_BRIDGE_CHANNEL_STATE_STOP_TALKING,
104 };
105
106 /*! \brief Return values for bridge technology write function */
107 enum ast_bridge_write_result {
108         /*! Bridge technology wrote out frame fine */
109         AST_BRIDGE_WRITE_SUCCESS = 0,
110         /*! Bridge technology attempted to write out the frame but failed */
111         AST_BRIDGE_WRITE_FAILED,
112         /*! Bridge technology does not support writing out a frame of this type */
113         AST_BRIDGE_WRITE_UNSUPPORTED,
114 };
115
116 struct ast_bridge_technology;
117 struct ast_bridge;
118
119 /*!
120  * \brief Structure specific to bridge technologies capable of
121  * performing talking optimizations.
122  */
123 struct ast_bridge_tech_optimizations {
124         /*! The amount of time in ms that talking must be detected before
125          *  the dsp determines that talking has occurred */
126         unsigned int talking_threshold;
127         /*! The amount of time in ms that silence must be detected before
128          *  the dsp determines that talking has stopped */
129         unsigned int silence_threshold;
130         /*! Whether or not the bridging technology should drop audio
131          *  detected as silence from the mix. */
132         unsigned int drop_silence:1;
133 };
134
135 /*!
136  * \brief Structure that contains information regarding a channel in a bridge
137  */
138 struct ast_bridge_channel {
139         /*! Lock to protect this data structure */
140         ast_mutex_t lock;
141         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
142         ast_cond_t cond;
143         /*! Current bridged channel state */
144         enum ast_bridge_channel_state state;
145         /*! Asterisk channel participating in the bridge */
146         struct ast_channel *chan;
147         /*! Asterisk channel we are swapping with (if swapping) */
148         struct ast_channel *swap;
149         /*! Bridge this channel is participating in */
150         struct ast_bridge *bridge;
151         /*! Private information unique to the bridge technology */
152         void *bridge_pvt;
153         /*! Thread handling the bridged channel */
154         pthread_t thread;
155         /*! Additional file descriptors to look at */
156         int fds[4];
157         /*! Bit to indicate whether the channel is suspended from the bridge or not */
158         unsigned int suspended:1;
159         /*! Bit to indicate if a imparted channel is allowed to get hungup after leaving the bridge by the bridging core. */
160         unsigned int allow_impart_hangup:1;
161         /*! Features structure for features that are specific to this channel */
162         struct ast_bridge_features *features;
163         /*! Technology optimization parameters used by bridging technologies capable of
164          *  optimizing based upon talk detection. */
165         struct ast_bridge_tech_optimizations tech_args;
166         /*! Queue of DTMF digits used for DTMF streaming */
167         char dtmf_stream_q[8];
168         /*! Call ID associated with bridge channel */
169         struct ast_callid *callid;
170         /*! Linked list information */
171         AST_LIST_ENTRY(ast_bridge_channel) entry;
172 };
173
174 enum ast_bridge_video_mode_type {
175         /*! Video is not allowed in the bridge */
176         AST_BRIDGE_VIDEO_MODE_NONE = 0,
177         /*! A single user is picked as the only distributed of video across the bridge */
178         AST_BRIDGE_VIDEO_MODE_SINGLE_SRC,
179         /*! A single user's video feed is distributed to all bridge channels, but
180          *  that feed is automatically picked based on who is talking the most. */
181         AST_BRIDGE_VIDEO_MODE_TALKER_SRC,
182 };
183
184 /*! This is used for both SINGLE_SRC mode to set what channel
185  *  should be the current single video feed */
186 struct ast_bridge_video_single_src_data {
187         /*! Only accept video coming from this channel */
188         struct ast_channel *chan_vsrc;
189 };
190
191 /*! This is used for both SINGLE_SRC_TALKER mode to set what channel
192  *  should be the current single video feed */
193 struct ast_bridge_video_talker_src_data {
194         /*! Only accept video coming from this channel */
195         struct ast_channel *chan_vsrc;
196         int average_talking_energy;
197
198         /*! Current talker see's this person */
199         struct ast_channel *chan_old_vsrc;
200 };
201
202 struct ast_bridge_video_mode {
203         enum ast_bridge_video_mode_type mode;
204         /* Add data for all the video modes here. */
205         union {
206                 struct ast_bridge_video_single_src_data single_src_data;
207                 struct ast_bridge_video_talker_src_data talker_src_data;
208         } mode_data;
209 };
210
211 /*!
212  * \brief Structure that contains information about a bridge
213  */
214 struct ast_bridge {
215         /*! Number of channels participating in the bridge */
216         int num;
217         /*! The video mode this bridge is using */
218         struct ast_bridge_video_mode video_mode;
219         /*! The internal sample rate this bridge is mixed at when multiple channels are being mixed.
220          *  If this value is 0, the bridge technology may auto adjust the internal mixing rate. */
221         unsigned int internal_sample_rate;
222         /*! The mixing interval indicates how quickly the bridges internal mixing should occur
223          * for bridge technologies that mix audio. When set to 0, the bridge tech must choose a
224          * default interval for itself. */
225         unsigned int internal_mixing_interval;
226         /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */
227         unsigned int waiting:1;
228         /*! Bit to indicate the bridge thread should stop */
229         unsigned int stop:1;
230         /*! Bit to indicate the bridge thread should refresh itself */
231         unsigned int refresh:1;
232         /*! Bridge flags to tweak behavior */
233         struct ast_flags feature_flags;
234         /*! Bridge technology that is handling the bridge */
235         struct ast_bridge_technology *technology;
236         /*! Private information unique to the bridge technology */
237         void *bridge_pvt;
238         /*! Thread running the bridge */
239         pthread_t thread;
240         /*! Enabled features information */
241         struct ast_bridge_features features;
242         /*! Array of channels that the bridge thread is currently handling */
243         struct ast_channel **array;
244         /*! Number of channels in the above array */
245         size_t array_num;
246         /*! Number of channels the array can handle */
247         size_t array_size;
248         /*! Call ID associated with the bridge */
249         struct ast_callid *callid;
250         /*! Linked list of channels participating in the bridge */
251         AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
252         };
253
254 /*! \brief Create a new bridge
255  *
256  * \param capabilities The capabilities that we require to be used on the bridge
257  * \param flags Flags that will alter the behavior of the bridge
258  *
259  * \retval a pointer to a new bridge on success
260  * \retval NULL on failure
261  *
262  * Example usage:
263  *
264  * \code
265  * struct ast_bridge *bridge;
266  * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE);
267  * \endcode
268  *
269  * This creates a simple two party bridge that will be destroyed once one of
270  * the channels hangs up.
271  */
272 struct ast_bridge *ast_bridge_new(uint32_t capabilities, int flags);
273
274 /*!
275  * \brief Lock the bridge.
276  *
277  * \param bridge Bridge to lock
278  *
279  * \return Nothing
280  */
281 #define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
282 static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
283 {
284         __ao2_lock(bridge, AO2_LOCK_REQ_MUTEX, file, function, line, var);
285 }
286
287 /*!
288  * \brief Unlock the bridge.
289  *
290  * \param bridge Bridge to unlock
291  *
292  * \return Nothing
293  */
294 #define ast_bridge_unlock(bridge)       _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
295 static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
296 {
297         __ao2_unlock(bridge, file, function, line, var);
298 }
299
300 /*! \brief See if it is possible to create a bridge
301  *
302  * \param capabilities The capabilities that the bridge will use
303  *
304  * \retval 1 if possible
305  * \retval 0 if not possible
306  *
307  * Example usage:
308  *
309  * \code
310  * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX);
311  * \endcode
312  *
313  * This sees if it is possible to create a bridge capable of bridging two channels
314  * together.
315  */
316 int ast_bridge_check(uint32_t capabilities);
317
318 /*! \brief Destroy a bridge
319  *
320  * \param bridge Bridge to destroy
321  *
322  * \retval 0 on success
323  * \retval -1 on failure
324  *
325  * Example usage:
326  *
327  * \code
328  * ast_bridge_destroy(bridge);
329  * \endcode
330  *
331  * This destroys a bridge that was previously created using ast_bridge_new.
332  */
333 int ast_bridge_destroy(struct ast_bridge *bridge);
334
335 /*! \brief Join (blocking) a channel to a bridge
336  *
337  * \param bridge Bridge to join
338  * \param chan Channel to join
339  * \param swap Channel to swap out if swapping
340  * \param features Bridge features structure
341  * \param tech_args Optional Bridging tech optimization parameters for this channel.
342  *
343  * \retval state that channel exited the bridge with
344  *
345  * Example usage:
346  *
347  * \code
348  * ast_bridge_join(bridge, chan, NULL, NULL);
349  * \endcode
350  *
351  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
352  * the bridge pointer. This function will not return until the channel has been
353  * removed from the bridge, swapped out for another channel, or has hung up.
354  *
355  * If this channel will be replacing another channel the other channel can be specified
356  * in the swap parameter. The other channel will be thrown out of the bridge in an
357  * atomic fashion.
358  *
359  * If channel specific features are enabled a pointer to the features structure
360  * can be specified in the features parameter.
361  */
362 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
363         struct ast_channel *chan,
364         struct ast_channel *swap,
365         struct ast_bridge_features *features,
366         struct ast_bridge_tech_optimizations *tech_args);
367
368 /*! \brief Impart (non-blocking) a channel on a bridge
369  *
370  * \param bridge Bridge to impart on
371  * \param chan Channel to impart
372  * \param swap Channel to swap out if swapping
373  * \param features Bridge features structure
374  * \param allow_hangup  Indicates if the bridge thread should manage hanging up of the channel or not.
375  *
376  * \retval 0 on success
377  * \retval -1 on failure
378  *
379  * Example usage:
380  *
381  * \code
382  * ast_bridge_impart(bridge, chan, NULL, NULL, 0);
383  * \endcode
384  *
385  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
386  * the bridge pointer. This function will return immediately and will not wait
387  * until the channel is no longer part of the bridge.
388  *
389  * If this channel will be replacing another channel the other channel can be specified
390  * in the swap parameter. The other channel will be thrown out of the bridge in an
391  * atomic fashion.
392  *
393  * If channel specific features are enabled a pointer to the features structure
394  * can be specified in the features parameter.
395  */
396 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features, int allow_hangup);
397
398 /*! \brief Depart a channel from a bridge
399  *
400  * \param bridge Bridge to depart from
401  * \param chan Channel to depart
402  *
403  * \retval 0 on success
404  * \retval -1 on failure
405  *
406  * Example usage:
407  *
408  * \code
409  * ast_bridge_depart(bridge, chan);
410  * \endcode
411  *
412  * This removes the channel pointed to by the chan pointer from the bridge
413  * pointed to by the bridge pointer and gives control to the calling thread.
414  * This does not hang up the channel.
415  *
416  * \note This API call can only be used on channels that were added to the bridge
417  *       using the ast_bridge_impart API call.
418  */
419 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
420
421 /*! \brief Remove a channel from a bridge
422  *
423  * \param bridge Bridge that the channel is to be removed from
424  * \param chan Channel to remove
425  *
426  * \retval 0 on success
427  * \retval -1 on failure
428  *
429  * Example usage:
430  *
431  * \code
432  * ast_bridge_remove(bridge, chan);
433  * \endcode
434  *
435  * This removes the channel pointed to by the chan pointer from the bridge
436  * pointed to by the bridge pointer and requests that it be hung up. Control
437  * over the channel will NOT be given to the calling thread.
438  *
439  * \note This API call can be used on channels that were added to the bridge
440  *       using both ast_bridge_join and ast_bridge_impart.
441  */
442 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
443
444 /*! \brief Merge two bridges together
445  *
446  * \param bridge0 First bridge
447  * \param bridge1 Second bridge
448  *
449  * \retval 0 on success
450  * \retval -1 on failure
451  *
452  * Example usage:
453  *
454  * \code
455  * ast_bridge_merge(bridge0, bridge1);
456  * \endcode
457  *
458  * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0.
459  * In reality all of the channels in bridge1 are simply moved to bridge0.
460  *
461  * \note The second bridge specified is not destroyed when this operation is
462  *       completed.
463  */
464 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
465
466 /*! \brief Suspend a channel temporarily from a bridge
467  *
468  * \param bridge Bridge to suspend the channel from
469  * \param chan Channel to suspend
470  *
471  * \retval 0 on success
472  * \retval -1 on failure
473  *
474  * Example usage:
475  *
476  * \code
477  * ast_bridge_suspend(bridge, chan);
478  * \endcode
479  *
480  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
481  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
482  * the channel will not be removed from the bridge.
483  *
484  * \note This API call can be used on channels that were added to the bridge
485  *       using both ast_bridge_join and ast_bridge_impart.
486  */
487 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
488
489 /*! \brief Unsuspend a channel from a bridge
490  *
491  * \param bridge Bridge to unsuspend the channel from
492  * \param chan Channel to unsuspend
493  *
494  * \retval 0 on success
495  * \retval -1 on failure
496  *
497  * Example usage:
498  *
499  * \code
500  * ast_bridge_unsuspend(bridge, chan);
501  * \endcode
502  *
503  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
504  * The bridge will go back to handling the channel once this function returns.
505  *
506  * \note You must not mess with the channel once this function returns.
507  *       Doing so may result in bad things happening.
508  */
509 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
510
511 /*! \brief Change the state of a bridged channel
512  *
513  * \param bridge_channel Channel to change the state on
514  * \param new_state The new state to place the channel into
515  *
516  * Example usage:
517  *
518  * \code
519  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT);
520  * \endcode
521  *
522  * This places the channel pointed to by bridge_channel into the state
523  * AST_BRIDGE_CHANNEL_STATE_WAIT.
524  *
525  * \note This API call is only meant to be used in feature hook callbacks to
526  *       make sure the channel either hangs up or returns to the bridge.
527  */
528 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
529
530 /*! \brief Adjust the internal mixing sample rate of a bridge used during
531  *         multimix mode.
532  *
533  * \param bridge Channel to change the sample rate on.
534  * \param sample_rate the sample rate to change to. If a
535  *        value of 0 is passed here, the bridge will be free to pick
536  *        what ever sample rate it chooses.
537  *
538  */
539 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
540
541 /*! \brief Adjust the internal mixing interval of a bridge used during
542  *         multimix mode.
543  *
544  * \param bridge Channel to change the sample rate on.
545  * \param mixing_interval the sample rate to change to.  If 0 is set
546  * the bridge tech is free to choose any mixing interval it uses by default.
547  */
548 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);
549
550 /*!
551  * \brief Set a bridge to feed a single video source to all participants.
552  */
553 void ast_bridge_set_single_src_video_mode(struct ast_bridge *bridge, struct ast_channel *video_src_chan);
554
555 /*!
556  * \brief Set the bridge to pick the strongest talker supporting
557  * video as the single source video feed
558  */
559 void ast_bridge_set_talker_src_video_mode(struct ast_bridge *bridge);
560
561 /*!
562  * \brief Update information about talker energy for talker src video mode.
563  */
564 void ast_bridge_update_talker_src_video_mode(struct ast_bridge *bridge, struct ast_channel *chan, int talker_energy, int is_keyfame);
565
566 /*!
567  * \brief Returns the number of video sources currently active in the bridge
568  */
569 int ast_bridge_number_video_src(struct ast_bridge *bridge);
570
571 /*!
572  * \brief Determine if a channel is a video src for the bridge
573  *
574  * \retval 0 Not a current video source of the bridge.
575  * \retval None 0, is a video source of the bridge, The number
576  *         returned represents the priority this video stream has
577  *         on the bridge where 1 is the highest priority.
578  */
579 int ast_bridge_is_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
580
581 /*!
582  * \brief remove a channel as a source of video for the bridge.
583  */
584 void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *chan);
585
586 #if defined(__cplusplus) || defined(c_plusplus)
587 }
588 #endif
589
590 #endif /* _ASTERISK_BRIDGING_H */