bridge: Add a deferred queue.
[asterisk/asterisk.git] / include / asterisk / bridge_technology.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 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  */
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  */
36 enum ast_bridge_preference {
37         AST_BRIDGE_PREFERENCE_BASE_HOLDING  = 50,
38         AST_BRIDGE_PREFERENCE_BASE_EARLY    = 100,
39         AST_BRIDGE_PREFERENCE_BASE_NATIVE   = 90,
40         AST_BRIDGE_PREFERENCE_BASE_1TO1MIX  = 50,
41         AST_BRIDGE_PREFERENCE_BASE_MULTIMIX = 10,
42 };
43
44 /*!
45  * \brief Structure specific to bridge technologies capable of
46  * performing talking optimizations.
47  */
48 struct ast_bridge_tech_optimizations {
49         /*! The amount of time in ms that talking must be detected before
50          *  the dsp determines that talking has occurred */
51         unsigned int talking_threshold;
52         /*! The amount of time in ms that silence must be detected before
53          *  the dsp determines that talking has stopped */
54         unsigned int silence_threshold;
55         /*! Whether or not the bridging technology should drop audio
56          *  detected as silence from the mix. */
57         unsigned int drop_silence:1;
58 };
59
60 /*!
61  * \brief Structure that is the essence of a bridge technology
62  */
63 struct ast_bridge_technology {
64         /*! Unique name to this bridge technology */
65         const char *name;
66         /*! The capabilities that this bridge technology is capable of.  This has nothing to do with
67          * format capabilities. */
68         uint32_t capabilities;
69         /*! Preference level that should be used when determining whether to use this bridge technology or not */
70         enum ast_bridge_preference preference;
71         /*!
72          * \brief Create a bridge technology instance for a bridge.
73          *
74          * \retval 0 on success
75          * \retval -1 on failure
76          *
77          * \note On entry, bridge may or may not already be locked.
78          * However, it can be accessed as if it were locked.
79          */
80         int (*create)(struct ast_bridge *bridge);
81         /*!
82          * \brief Request a bridge technology instance start operations.
83          *
84          * \retval 0 on success
85          * \retval -1 on failure
86          *
87          * \note On entry, bridge may or may not already be locked.
88          * However, it can be accessed as if it were locked.
89          */
90         int (*start)(struct ast_bridge *bridge);
91         /*!
92          * \brief Request a bridge technology instance stop in preparation for being destroyed.
93          *
94          * \note On entry, bridge is already locked.
95          */
96         void (*stop)(struct ast_bridge *bridge);
97         /*!
98          * \brief Destroy a bridging technology instance for a bridge.
99          *
100          * \note On entry, bridge must NOT be locked.
101          */
102         void (*destroy)(struct ast_bridge *bridge);
103         /*!
104          * \brief Add a channel to a bridging technology instance for a bridge.
105          *
106          * \retval 0 on success
107          * \retval -1 on failure
108          *
109          * \note On entry, bridge is already locked.
110          *
111          * \note The bridge technology must tollerate a failed to join channel
112          * until it can be kicked from the bridge.
113          *
114          * \note A channel may be in a suspended state already when joining a bridge
115          * technology. The technology must handle this case.
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          * This is called when a bridge receives a request to change the topology on the channel. A bridge
168          * technology should define a handler for this callback if it needs to update internals or intercept
169          * the request and not pass it on to other channels. This can be done by returning a nonzero value.
170          *
171          * \retval 0 Frame accepted by the bridge.
172          * \retval -1 Frame rejected.
173          */
174         int (*stream_topology_request_change)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
175         /*!
176          * \brief Callback for when a stream topology changes on the channel
177          *
178          * This is called when a bridge receives an indication that a topology has been changed on a channel
179          * and the new topology has been mapped to the bridge. A bridge technology should define a handler for
180          * this callback if it needs to update internals due to a channel's topology changing.
181          */
182         void (*stream_topology_changed)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
183         /*! TRUE if the bridge technology is currently suspended. */
184         unsigned int suspended:1;
185         /*! Module this bridge technology belongs to. It is used for reference counting bridges using the technology. */
186         struct ast_module *mod;
187         /*! Linked list information */
188         AST_RWLIST_ENTRY(ast_bridge_technology) entry;
189 };
190
191 /*!
192  * \brief Register a bridge technology for use
193  *
194  * \param technology The bridge technology to register
195  * \param mod The module that is registering the bridge technology
196  *
197  * \retval 0 on success
198  * \retval -1 on failure
199  *
200  * Example usage:
201  *
202  * \code
203  * ast_bridge_technology_register(&simple_bridge_tech);
204  * \endcode
205  *
206  * This registers a bridge technology declared as the structure
207  * simple_bridge_tech with the bridging core and makes it available for
208  * use when creating bridges.
209  */
210 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
211
212 /*! \brief See \ref __ast_bridge_technology_register() */
213 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, AST_MODULE_SELF)
214
215 /*!
216  * \brief Unregister a bridge technology from use
217  *
218  * \param technology The bridge technology to unregister
219  *
220  * \retval 0 on success
221  * \retval -1 on failure
222  *
223  * Example usage:
224  *
225  * \code
226  * ast_bridge_technology_unregister(&simple_bridge_tech);
227  * \endcode
228  *
229  * This unregisters a bridge technlogy declared as the structure
230  * simple_bridge_tech with the bridging core. It will no longer be
231  * considered when creating a new bridge.
232  */
233 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
234
235 /*!
236  * \brief Suspend a bridge technology from consideration
237  *
238  * \param technology The bridge technology to suspend
239  *
240  * Example usage:
241  *
242  * \code
243  * ast_bridge_technology_suspend(&simple_bridge_tech);
244  * \endcode
245  *
246  * This suspends the bridge technology simple_bridge_tech from being considered
247  * when creating a new bridge. Existing bridges using the bridge technology
248  * are not affected.
249  */
250 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
251
252 /*!
253  * \brief Unsuspend a bridge technology
254  *
255  * \param technology The bridge technology to unsuspend
256  *
257  * Example usage:
258  *
259  * \code
260  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
261  * \endcode
262  *
263  * This makes the bridge technology simple_bridge_tech considered when
264  * creating a new bridge again.
265  */
266 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
267
268 #if defined(__cplusplus) || defined(c_plusplus)
269 }
270 #endif
271
272 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */