Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


bridging.h
Go to the documentation of this file.
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 
66 
67 /*! \brief Capabilities for a bridge technology */
69  /*! Bridge is only capable of mixing 2 channels */
71  /*! Bridge is capable of mixing 2 or more channels */
73  /*! Bridge should natively bridge two channels if possible */
75  /*! Bridge should run using the multithreaded model */
77  /*! Bridge should run a central bridge thread */
79  /*! Bridge technology can do video mixing (or something along those lines) */
81  /*! Bridge technology can optimize things based on who is talking */
83 };
84 
85 /*! \brief State information about a bridged channel */
87  /*! Waiting for a signal */
89  /*! Bridged channel has ended itself (it has hung up) */
91  /*! Bridged channel should be hung up */
93  /*! Bridged channel should be removed from the bridge without being hung up */
95  /*! Bridged channel is executing a feature hook */
97  /*! Bridged channel is sending a DTMF stream out */
99 };
100 
101 /*! \brief Return values for bridge technology write function */
103  /*! Bridge technology wrote out frame fine */
105  /*! Bridge technology attempted to write out the frame but failed */
107  /*! Bridge technology does not support writing out a frame of this type */
109 };
110 
111 struct ast_bridge_technology;
112 struct ast_bridge;
113 
114 /*!
115  * \brief Structure that contains information regarding a channel in a bridge
116  */
118  /*! Lock to protect this data structure */
120  /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
122  /*! Current bridged channel state */
124  /*! Asterisk channel participating in the bridge */
125  struct ast_channel *chan;
126  /*! Asterisk channel we are swapping with (if swapping) */
127  struct ast_channel *swap;
128  /*! Bridge this channel is participating in */
130  /*! Private information unique to the bridge technology */
131  void *bridge_pvt;
132  /*! Thread handling the bridged channel */
133  pthread_t thread;
134  /*! Additional file descriptors to look at */
135  int fds[4];
136  /*! Bit to indicate whether the channel is suspended from the bridge or not */
137  unsigned int suspended:1;
138  /*! Features structure for features that are specific to this channel */
140  /*! Queue of DTMF digits used for DTMF streaming */
141  char dtmf_stream_q[8];
142  /*! Linked list information */
144 };
145 
146 /*!
147  * \brief Structure that contains information about a bridge
148  */
149 struct ast_bridge {
150  /*! Number of channels participating in the bridge */
151  int num;
152  /*! Bit to indicate that the bridge thread is waiting on channels in the bridge array */
153  unsigned int waiting:1;
154  /*! Bit to indicate the bridge thread should stop */
155  unsigned int stop:1;
156  /*! Bit to indicate the bridge thread should refresh itself */
157  unsigned int refresh:1;
158  /*! Bridge flags to tweak behavior */
159  struct ast_flags feature_flags;
160  /*! Bridge technology that is handling the bridge */
162  /*! Private information unique to the bridge technology */
163  void *bridge_pvt;
164  /*! Thread running the bridge */
165  pthread_t thread;
166  /*! Enabled features information */
168  /*! Array of channels that the bridge thread is currently handling */
169  struct ast_channel **array;
170  /*! Number of channels in the above array */
171  size_t array_num;
172  /*! Number of channels the array can handle */
173  size_t array_size;
174  /*! Linked list of channels participating in the bridge */
176 };
177 
178 /*! \brief Create a new bridge
179  *
180  * \param capabilities The capabilities that we require to be used on the bridge
181  * \param flags Flags that will alter the behavior of the bridge
182  *
183  * \retval a pointer to a new bridge on success
184  * \retval NULL on failure
185  *
186  * Example usage:
187  *
188  * \code
189  * struct ast_bridge *bridge;
190  * bridge = ast_bridge_new(AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE);
191  * \endcode
192  *
193  * This creates a simple two party bridge that will be destroyed once one of
194  * the channels hangs up.
195  */
196 struct ast_bridge *ast_bridge_new(enum ast_bridge_capability capabilities, int flags);
197 
198 /*! \brief See if it is possible to create a bridge
199  *
200  * \param capabilities The capabilities that the bridge will use
201  *
202  * \retval 1 if possible
203  * \retval 0 if not possible
204  *
205  * Example usage:
206  *
207  * \code
208  * int possible = ast_bridge_check(AST_BRIDGE_CAPABILITY_1TO1MIX);
209  * \endcode
210  *
211  * This sees if it is possible to create a bridge capable of bridging two channels
212  * together.
213  */
214 int ast_bridge_check(enum ast_bridge_capability capabilities);
215 
216 /*! \brief Destroy a bridge
217  *
218  * \param bridge Bridge to destroy
219  *
220  * \retval 0 on success
221  * \retval -1 on failure
222  *
223  * Example usage:
224  *
225  * \code
226  * ast_bridge_destroy(bridge);
227  * \endcode
228  *
229  * This destroys a bridge that was previously created using ast_bridge_new.
230  */
231 int ast_bridge_destroy(struct ast_bridge *bridge);
232 
233 /*! \brief Join (blocking) a channel to a bridge
234  *
235  * \param bridge Bridge to join
236  * \param chan Channel to join
237  * \param swap Channel to swap out if swapping
238  * \param features Bridge features structure
239  *
240  * \retval state that channel exited the bridge with
241  *
242  * Example usage:
243  *
244  * \code
245  * ast_bridge_join(bridge, chan, NULL, NULL);
246  * \endcode
247  *
248  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
249  * the bridge pointer. This function will not return until the channel has been
250  * removed from the bridge, swapped out for another channel, or has hung up.
251  *
252  * If this channel will be replacing another channel the other channel can be specified
253  * in the swap parameter. The other channel will be thrown out of the bridge in an
254  * atomic fashion.
255  *
256  * If channel specific features are enabled a pointer to the features structure
257  * can be specified in the features parameter.
258  */
259 enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features);
260 
261 /*! \brief Impart (non-blocking) a channel on a bridge
262  *
263  * \param bridge Bridge to impart on
264  * \param chan Channel to impart
265  * \param swap Channel to swap out if swapping
266  * \param features Bridge features structure
267  *
268  * \retval 0 on success
269  * \retval -1 on failure
270  *
271  * Example usage:
272  *
273  * \code
274  * ast_bridge_impart(bridge, chan, NULL, NULL);
275  * \endcode
276  *
277  * This adds a channel pointed to by the chan pointer to the bridge pointed to by
278  * the bridge pointer. This function will return immediately and will not wait
279  * until the channel is no longer part of the bridge.
280  *
281  * If this channel will be replacing another channel the other channel can be specified
282  * in the swap parameter. The other channel will be thrown out of the bridge in an
283  * atomic fashion.
284  *
285  * If channel specific features are enabled a pointer to the features structure
286  * can be specified in the features parameter.
287  */
288 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features);
289 
290 /*! \brief Depart a channel from a bridge
291  *
292  * \param bridge Bridge to depart from
293  * \param chan Channel to depart
294  *
295  * \retval 0 on success
296  * \retval -1 on failure
297  *
298  * Example usage:
299  *
300  * \code
301  * ast_bridge_depart(bridge, chan);
302  * \endcode
303  *
304  * This removes the channel pointed to by the chan pointer from the bridge
305  * pointed to by the bridge pointer and gives control to the calling thread.
306  * This does not hang up the channel.
307  *
308  * \note This API call can only be used on channels that were added to the bridge
309  * using the ast_bridge_impart API call.
310  */
311 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
312 
313 /*! \brief Remove a channel from a bridge
314  *
315  * \param bridge Bridge that the channel is to be removed from
316  * \param chan Channel to remove
317  *
318  * \retval 0 on success
319  * \retval -1 on failure
320  *
321  * Example usage:
322  *
323  * \code
324  * ast_bridge_remove(bridge, chan);
325  * \endcode
326  *
327  * This removes the channel pointed to by the chan pointer from the bridge
328  * pointed to by the bridge pointer and requests that it be hung up. Control
329  * over the channel will NOT be given to the calling thread.
330  *
331  * \note This API call can be used on channels that were added to the bridge
332  * using both ast_bridge_join and ast_bridge_impart.
333  */
334 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
335 
336 /*! \brief Merge two bridges together
337  *
338  * \param bridge0 First bridge
339  * \param bridge1 Second bridge
340  *
341  * \retval 0 on success
342  * \retval -1 on failure
343  *
344  * Example usage:
345  *
346  * \code
347  * ast_bridge_merge(bridge0, bridge1);
348  * \endcode
349  *
350  * This merges the bridge pointed to by bridge1 with the bridge pointed to by bridge0.
351  * In reality all of the channels in bridge1 are simply moved to bridge0.
352  *
353  * \note The second bridge specified is not destroyed when this operation is
354  * completed.
355  */
356 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
357 
358 /*! \brief Suspend a channel temporarily from a bridge
359  *
360  * \param bridge Bridge to suspend the channel from
361  * \param chan Channel to suspend
362  *
363  * \retval 0 on success
364  * \retval -1 on failure
365  *
366  * Example usage:
367  *
368  * \code
369  * ast_bridge_suspend(bridge, chan);
370  * \endcode
371  *
372  * This suspends the channel pointed to by chan from the bridge pointed to by bridge temporarily.
373  * Control of the channel is given to the calling thread. This differs from ast_bridge_depart as
374  * the channel will not be removed from the bridge.
375  *
376  * \note This API call can be used on channels that were added to the bridge
377  * using both ast_bridge_join and ast_bridge_impart.
378  */
379 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
380 
381 /*! \brief Unsuspend a channel from a bridge
382  *
383  * \param bridge Bridge to unsuspend the channel from
384  * \param chan Channel to unsuspend
385  *
386  * \retval 0 on success
387  * \retval -1 on failure
388  *
389  * Example usage:
390  *
391  * \code
392  * ast_bridge_unsuspend(bridge, chan);
393  * \endcode
394  *
395  * This unsuspends the channel pointed to by chan from the bridge pointed to by bridge.
396  * The bridge will go back to handling the channel once this function returns.
397  *
398  * \note You must not mess with the channel once this function returns.
399  * Doing so may result in bad things happening.
400  */
401 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
402 
403 /*! \brief Change the state of a bridged channel
404  *
405  * \param bridge_channel Channel to change the state on
406  * \param new_state The new state to place the channel into
407  *
408  * Example usage:
409  *
410  * \code
411  * ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_WAIT);
412  * \endcode
413  *
414  * This places the channel pointed to by bridge_channel into the state
415  * AST_BRIDGE_CHANNEL_STATE_WAIT.
416  *
417  * \note This API call is only meant to be used in feature hook callbacks to
418  * make sure the channel either hangs up or returns to the bridge.
419  */
420 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
421 
422 #if defined(__cplusplus) || defined(c_plusplus)
423 }
424 #endif
425 
426 #endif /* _ASTERISK_BRIDGING_H */
ast_bridge_capability
Capabilities for a bridge technology.
Definition: bridging.h:68
Main Channel structure associated with a channel.
Definition: channel.h:742
char dtmf_stream_q[8]
Definition: bridging.h:141
struct ast_bridge_features * features
Definition: bridging.h:139
pthread_t thread
Definition: bridging.h:133
int ast_bridge_check(enum ast_bridge_capability capabilities)
See if it is possible to create a bridge.
Definition: bridging.c:502
enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features)
Join (blocking) a channel to a bridge.
Definition: bridging.c:993
Structure that contains features information.
static struct aji_capabilities * capabilities
Definition: res_jabber.c:393
AST_LIST_ENTRY(ast_bridge_channel) entry
unsigned int suspended
Definition: bridging.h:137
struct ast_bridge * ast_bridge_new(enum ast_bridge_capability capabilities, int flags)
Create a new bridge.
Definition: bridging.c:449
int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan)
Depart a channel from a bridge.
Definition: bridging.c:1077
unsigned int stop
Definition: app_meetme.c:969
int ast_bridge_destroy(struct ast_bridge *bridge)
Destroy a bridge.
Definition: bridging.c:515
struct ast_bridge * bridge
Definition: bridging.h:129
pthread_cond_t ast_cond_t
Definition: lock.h:144
unsigned int flags
Definition: channel.h:850
struct ast_bridge_technology * technology
Definition: bridging.h:161
size_t array_size
Definition: bridging.h:173
size_t array_num
Definition: bridging.h:171
void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state)
Change the state of a bridged channel.
Definition: bridging.c:122
int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features)
Impart (non-blocking) a channel on a bridge.
Definition: bridging.c:1043
int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1)
Merge two bridges together.
Definition: bridging.c:1119
static struct channel_usage channels
int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan)
Suspend a channel temporarily from a bridge.
Definition: bridging.c:1200
ast_cond_t cond
Definition: bridging.h:121
#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:224
Structure that contains information about a bridge.
Definition: bridging.h:149
int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan)
Remove a channel from a bridge.
Definition: bridging.c:1100
struct ast_channel ** array
Definition: bridging.h:169
pthread_t thread
Definition: bridging.h:165
struct ast_channel * swap
Definition: bridging.h:127
Structure used to handle boolean flags.
Definition: utils.h:200
struct ast_channel * chan
Definition: bridging.h:125
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
Structure that is the essence of a bridge technology.
ast_bridge_write_result
Return values for bridge technology write function.
Definition: bridging.h:102
ast_bridge_channel_state
State information about a bridged channel.
Definition: bridging.h:86
ast_mutex_t lock
Definition: bridging.h:119
enum ast_bridge_channel_state state
Definition: bridging.h:123
Channel Bridging API.
void * bridge_pvt
Definition: bridging.h:163
int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan)
Unsuspend a channel from a bridge.
Definition: bridging.c:1218
Structure for mutex and tracking information.
Definition: lock.h:121
unsigned int refresh