Asterisk - The Open Source Telephony Project GIT-master-25686a5
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 <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)
28extern "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 */
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. */
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 */
220int __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 */
void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology)
Unsuspend a bridge technology.
Definition: bridge.c:3052
int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod)
Register a bridge technology for use.
Definition: bridge.c:212
ast_bridge_preference
Base preference values for choosing a bridge technology.
@ AST_BRIDGE_PREFERENCE_BASE_HOLDING
@ AST_BRIDGE_PREFERENCE_BASE_MULTIMIX
@ AST_BRIDGE_PREFERENCE_BASE_NATIVE
@ AST_BRIDGE_PREFERENCE_BASE_1TO1MIX
@ AST_BRIDGE_PREFERENCE_BASE_EARLY
int ast_bridge_technology_unregister(struct ast_bridge_technology *technology)
Unregister a bridge technology from use.
Definition: bridge.c:263
void ast_bridge_technology_suspend(struct ast_bridge_technology *technology)
Suspend a bridge technology from consideration.
Definition: bridge.c:3047
Structure that contains information regarding a channel in a bridge.
Structure specific to bridge technologies capable of performing talking optimizations.
Structure that is the essence of a bridge technology.
AST_RWLIST_ENTRY(ast_bridge_technology) entry
void(* unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Unsuspend a channel on a bridging technology instance for a bridge.
int(* stream_topology_request_change)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Callback for when a request has been made to change a stream topology on a channel.
void(* destroy)(struct ast_bridge *bridge)
Destroy a bridging technology instance for a bridge.
int(* start)(struct ast_bridge *bridge)
Request a bridge technology instance start operations.
void(* stream_topology_changed)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Callback for when a stream topology changes on the channel.
struct ast_module * mod
int(* write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame)
Write a frame into the bridging technology instance for a bridge.
int(* compatible)(struct ast_bridge *bridge)
Check if a bridge is compatible with the bridging technology.
void(* stop)(struct ast_bridge *bridge)
Request a bridge technology instance stop in preparation for being destroyed.
void(* suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Suspend a channel on a bridging technology instance for a bridge.
int(* join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Add a channel to a bridging technology instance for a bridge.
int(* create)(struct ast_bridge *bridge)
Create a bridge technology instance for a bridge.
enum ast_bridge_preference preference
void(* leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
Remove a channel from a bridging technology instance for a bridge.
Structure that contains information about a bridge.
Definition: bridge.h:349
Data structure associated with a single frame of data.
struct ast_module::@363 entry