33bdf258453afd1c48c085c9ee6750f0cc336b5a
[asterisk/asterisk.git] / include / asterisk / bridging_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 that is the essence of a bridge technology
46  */
47 struct ast_bridge_technology {
48         /*! Unique name to this bridge technology */
49         const char *name;
50         /*! The capabilities that this bridge technology is capable of.  This has nothing to do with
51          * format capabilities. */
52         uint32_t capabilities;
53         /*! Preference level that should be used when determining whether to use this bridge technology or not */
54         enum ast_bridge_preference preference;
55         /*!
56          * \brief Create a bridge technology instance for a bridge.
57          *
58          * \retval 0 on success
59          * \retval -1 on failure
60          *
61          * \note On entry, bridge may or may not already be locked.
62          * However, it can be accessed as if it were locked.
63          */
64         int (*create)(struct ast_bridge *bridge);
65         /*!
66          * \brief Request a bridge technology instance start operations.
67          *
68          * \retval 0 on success
69          * \retval -1 on failure
70          *
71          * \note On entry, bridge may or may not already be locked.
72          * However, it can be accessed as if it were locked.
73          */
74         int (*start)(struct ast_bridge *bridge);
75         /*!
76          * \brief Request a bridge technology instance stop in preparation for being destroyed.
77          *
78          * \note On entry, bridge is already locked.
79          */
80         void (*stop)(struct ast_bridge *bridge);
81         /*!
82          * \brief Destroy a bridging technology instance for a bridge.
83          *
84          * \note On entry, bridge must NOT be locked.
85          */
86         void (*destroy)(struct ast_bridge *bridge);
87         /*!
88          * \brief Add a channel to a bridging technology instance for a bridge.
89          *
90          * \retval 0 on success
91          * \retval -1 on failure
92          *
93          * \note On entry, bridge is already locked.
94          */
95         int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
96         /*!
97          * \brief Remove a channel from a bridging technology instance for a bridge.
98          *
99          * \note On entry, bridge is already locked.
100          */
101         void (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
102         /*!
103          * \brief Suspend a channel on a bridging technology instance for a bridge.
104          *
105          * \note On entry, bridge is already locked.
106          */
107         void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
108         /*!
109          * \brief Unsuspend a channel on a bridging technology instance for a bridge.
110          *
111          * \note On entry, bridge is already locked.
112          */
113         void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
114         /*!
115          * \brief Check if a bridge is compatible with the bridging technology.
116          *
117          * \retval 0 if not compatible
118          * \retval non-zero if compatible
119          *
120          * \note On entry, bridge may or may not already be locked.
121          * However, it can be accessed as if it were locked.
122          */
123         int (*compatible)(struct ast_bridge *bridge);
124         /*!
125          * \brief Write a frame into the bridging technology instance for a bridge.
126          *
127          * \retval 0 on success
128          * \retval -1 on failure
129          *
130          * \note On entry, bridge is already locked.
131          */
132         int (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame);
133         /*! Formats that the bridge technology supports */
134         struct ast_format_cap *format_capabilities;
135         /*! TRUE if the bridge technology is currently suspended. */
136         unsigned int suspended:1;
137         /*! Module this bridge technology belongs to. It is used for reference counting bridges using the technology. */
138         struct ast_module *mod;
139         /*! Linked list information */
140         AST_RWLIST_ENTRY(ast_bridge_technology) entry;
141 };
142
143 /*!
144  * \brief Register a bridge technology for use
145  *
146  * \param technology The bridge technology to register
147  * \param mod The module that is registering the bridge technology
148  *
149  * \retval 0 on success
150  * \retval -1 on failure
151  *
152  * Example usage:
153  *
154  * \code
155  * ast_bridge_technology_register(&simple_bridge_tech);
156  * \endcode
157  *
158  * This registers a bridge technology declared as the structure
159  * simple_bridge_tech with the bridging core and makes it available for
160  * use when creating bridges.
161  */
162 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
163
164 /*! \brief See \ref __ast_bridge_technology_register() */
165 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
166
167 /*!
168  * \brief Unregister a bridge technology from use
169  *
170  * \param technology The bridge technology to unregister
171  *
172  * \retval 0 on success
173  * \retval -1 on failure
174  *
175  * Example usage:
176  *
177  * \code
178  * ast_bridge_technology_unregister(&simple_bridge_tech);
179  * \endcode
180  *
181  * This unregisters a bridge technlogy declared as the structure
182  * simple_bridge_tech with the bridging core. It will no longer be
183  * considered when creating a new bridge.
184  */
185 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
186
187 /*!
188  * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
189  *
190  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
191  * layer, which in this case is the specific bridging technology being used. Since it
192  * is necessary for the knowledge of which channels are talking to make its way up to the
193  * application, this function has been created to allow the bridging technology to communicate
194  * that information with the bridging core.
195  *
196  * \param bridge_channel The bridge channel that has either started or stopped talking.
197  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
198  * when this indicates the channel has stopped talking.
199  *
200  * \retval 0 on success.
201  * \retval -1 on error.
202  */
203 int ast_bridge_notify_talking(struct ast_bridge_channel *bridge_channel, int started_talking);
204
205 /*!
206  * \brief Suspend a bridge technology from consideration
207  *
208  * \param technology The bridge technology to suspend
209  *
210  * Example usage:
211  *
212  * \code
213  * ast_bridge_technology_suspend(&simple_bridge_tech);
214  * \endcode
215  *
216  * This suspends the bridge technology simple_bridge_tech from being considered
217  * when creating a new bridge. Existing bridges using the bridge technology
218  * are not affected.
219  */
220 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
221
222 /*!
223  * \brief Unsuspend a bridge technology
224  *
225  * \param technology The bridge technology to unsuspend
226  *
227  * Example usage:
228  *
229  * \code
230  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
231  * \endcode
232  *
233  * This makes the bridge technology simple_bridge_tech considered when
234  * creating a new bridge again.
235  */
236 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
237
238 #if defined(__cplusplus) || defined(c_plusplus)
239 }
240 #endif
241
242 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */