Asterisk - The Open Source Telephony Project  18.5.0
bridge_technology.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * Joshua Colp <[email protected]>
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 <[email protected]>
22  */
23 
24 #ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H
25 #define _ASTERISK_BRIDGING_TECHNOLOGY_H
26 
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30 
31 /*!
32  * \brief Base preference values for choosing a bridge technology.
33  *
34  * \note Higher is more preference.
35  */
42 };
43 
44 /*!
45  * \brief Structure specific to bridge technologies capable of
46  * performing talking optimizations.
47  */
49  /*! Minimum average magnitude threshold to determine talking by the DSP. */
50  unsigned int talking_threshold;
51  /*! Time in ms of silence necessary to declare talking stopped by the bridge. */
52  unsigned int silence_threshold;
53  /*! Whether or not the bridging technology should drop audio
54  * detected as silence from the mix. */
55  unsigned int drop_silence:1;
56 };
57 
58 /*!
59  * \brief Structure that is the essence of a bridge technology
60  */
62  /*! Unique name to this bridge technology */
63  const char *name;
64  /*! The capabilities that this bridge technology is capable of. This has nothing to do with
65  * format capabilities. */
66  uint32_t capabilities;
67  /*! Preference level that should be used when determining whether to use this bridge technology or not */
68  enum ast_bridge_preference preference;
69  /*!
70  * \brief Create a bridge technology instance for a bridge.
71  *
72  * \retval 0 on success
73  * \retval -1 on failure
74  *
75  * \note On entry, bridge may or may not already be locked.
76  * However, it can be accessed as if it were locked.
77  */
78  int (*create)(struct ast_bridge *bridge);
79  /*!
80  * \brief Request a bridge technology instance start operations.
81  *
82  * \retval 0 on success
83  * \retval -1 on failure
84  *
85  * \note On entry, bridge may or may not already be locked.
86  * However, it can be accessed as if it were locked.
87  */
88  int (*start)(struct ast_bridge *bridge);
89  /*!
90  * \brief Request a bridge technology instance stop in preparation for being destroyed.
91  *
92  * \note On entry, bridge is already locked.
93  */
94  void (*stop)(struct ast_bridge *bridge);
95  /*!
96  * \brief Destroy a bridging technology instance for a bridge.
97  *
98  * \note On entry, bridge must NOT be locked.
99  */
100  void (*destroy)(struct ast_bridge *bridge);
101  /*!
102  * \brief Add a channel to a bridging technology instance for a bridge.
103  *
104  * \retval 0 on success
105  * \retval -1 on failure
106  *
107  * \note On entry, bridge is already locked.
108  *
109  * \note The bridge technology must tolerate a failed to join channel
110  * until it can be kicked from the bridge.
111  *
112  * \note A channel may be in a suspended state already when joining a bridge
113  * technology. The technology must handle this case.
114  *
115  * \note A channel may not be answered when joining a bridge technology.
116  */
117  int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
118  /*!
119  * \brief Remove a channel from a bridging technology instance for a bridge.
120  *
121  * \note On entry, bridge is already locked.
122  * \note Do not make assumptions about the number of channels in the bridge when
123  * this callback is called. When a channel is swapped into a bridge for another
124  * channel, the leave callback is called after the new channel has been added to
125  * the bridge.
126  */
127  void (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
128  /*!
129  * \brief Suspend a channel on a bridging technology instance for a bridge.
130  *
131  * \note On entry, bridge is already locked.
132  */
133  void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
134  /*!
135  * \brief Unsuspend a channel on a bridging technology instance for a bridge.
136  *
137  * \note On entry, bridge is already locked.
138  */
139  void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
140  /*!
141  * \brief Check if a bridge is compatible with the bridging technology.
142  *
143  * \retval 0 if not compatible
144  * \retval non-zero if compatible
145  *
146  * \note On entry, bridge may or may not already be locked.
147  * However, it can be accessed as if it were locked.
148  */
149  int (*compatible)(struct ast_bridge *bridge);
150  /*!
151  * \brief Write a frame into the bridging technology instance for a bridge.
152  *
153  * \note The bridge must be tolerant of bridge_channel being NULL.
154  *
155  * \retval 0 Frame accepted into the bridge.
156  * \retval -1 Frame needs to be deferred.
157  *
158  * \note On entry, bridge is already locked.
159  *
160  * \note Deferred frames will be automatically queued onto the channel when another
161  * channel joins the bridge.
162  */
163  int (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
164  /*!
165  * \brief Callback for when a request has been made to change a stream topology on a channel
166  *
167  * \details
168  * This is called when a bridge receives a request to change the
169  * topology on the channel. A bridge technology should define a
170  * handler for this callback if it needs to update internals or
171  * intercept the request and not pass it on to other channels.
172  * This can be done by returning a nonzero value.
173  *
174  * \retval 0 Frame can pass to the bridge technology.
175  * \retval non-zero Frame intercepted by the bridge technology.
176  *
177  * \note On entry, bridge is already locked.
178  */
179  int (*stream_topology_request_change)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
180  /*!
181  * \brief Callback for when a stream topology changes on the channel
182  *
183  * \details
184  * This is called when a bridge receives an indication that a
185  * topology has been changed on a channel and the new topology has
186  * been mapped to the bridge. A bridge technology should define a
187  * handler for this callback if it needs to update internals due
188  * to a channel's topology changing.
189  *
190  * \note On entry, bridge is already locked.
191  */
192  void (*stream_topology_changed)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
193  /*! TRUE if the bridge technology is currently suspended. */
194  unsigned int suspended:1;
195  /*! Module this bridge technology belongs to. It is used for reference counting bridges using the technology. */
196  struct ast_module *mod;
197  /*! Linked list information */
199 };
200 
201 /*!
202  * \brief Register a bridge technology for use
203  *
204  * \param technology The bridge technology to register
205  * \param mod The module that is registering the bridge technology
206  *
207  * \retval 0 on success
208  * \retval -1 on failure
209  *
210  * Example usage:
211  *
212  * \code
213  * ast_bridge_technology_register(&simple_bridge_tech);
214  * \endcode
215  *
216  * This registers a bridge technology declared as the structure
217  * simple_bridge_tech with the bridging core and makes it available for
218  * use when creating bridges.
219  */
220 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
221 
222 /*! \brief See \ref __ast_bridge_technology_register() */
223 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, AST_MODULE_SELF)
224 
225 /*!
226  * \brief Unregister a bridge technology from use
227  *
228  * \param technology The bridge technology to unregister
229  *
230  * \retval 0 on success
231  * \retval -1 on failure
232  *
233  * Example usage:
234  *
235  * \code
236  * ast_bridge_technology_unregister(&simple_bridge_tech);
237  * \endcode
238  *
239  * This unregisters a bridge technlogy declared as the structure
240  * simple_bridge_tech with the bridging core. It will no longer be
241  * considered when creating a new bridge.
242  */
244 
245 /*!
246  * \brief Suspend a bridge technology from consideration
247  *
248  * \param technology The bridge technology to suspend
249  *
250  * Example usage:
251  *
252  * \code
253  * ast_bridge_technology_suspend(&simple_bridge_tech);
254  * \endcode
255  *
256  * This suspends the bridge technology simple_bridge_tech from being considered
257  * when creating a new bridge. Existing bridges using the bridge technology
258  * are not affected.
259  */
261 
262 /*!
263  * \brief Unsuspend a bridge technology
264  *
265  * \param technology The bridge technology to unsuspend
266  *
267  * Example usage:
268  *
269  * \code
270  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
271  * \endcode
272  *
273  * This makes the bridge technology simple_bridge_tech considered when
274  * creating a new bridge again.
275  */
277 
278 #if defined(__cplusplus) || defined(c_plusplus)
279 }
280 #endif
281 
282 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */
static void unsuspend(struct cc_core_instance *core_instance)
Definition: ccss.c:3146
static unsigned char leave[]
Definition: leave.h:12
unsigned int stop
Definition: app_meetme.c:1096
int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod)
Register a bridge technology for use.
Definition: bridge.c:214
void ast_bridge_technology_suspend(struct ast_bridge_technology *technology)
Suspend a bridge technology from consideration.
Definition: bridge.c:3108
Structure that contains information about a bridge.
Definition: bridge.h:357
int ast_bridge_technology_unregister(struct ast_bridge_technology *technology)
Unregister a bridge technology from use.
Definition: bridge.c:265
void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology)
Unsuspend a bridge technology.
Definition: bridge.c:3113
struct ast_module * mod
static void destroy(struct ast_trans_pvt *pvt)
Definition: translate.c:291
static void suspend(struct cc_core_instance *core_instance)
Definition: ccss.c:3193
struct ast_module::@399 entry
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
Structure that contains information regarding a channel in a bridge.
Structure that is the essence of a bridge technology.
Data structure associated with a single frame of data.
ast_bridge_preference
Base preference values for choosing a bridge technology.
Structure specific to bridge technologies capable of performing talking optimizations.