Clean up doxygen warnings
[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 /*! \brief Preference for choosing the bridge technology */
32 enum ast_bridge_preference {
33         /*! Bridge technology should have high precedence over other bridge technologies */
34         AST_BRIDGE_PREFERENCE_HIGH = 0,
35         /*! Bridge technology is decent, not the best but should still be considered over low */
36         AST_BRIDGE_PREFERENCE_MEDIUM,
37         /*! Bridge technology is low, it should not be considered unless it is absolutely needed */
38         AST_BRIDGE_PREFERENCE_LOW,
39 };
40
41 /*!
42  * \brief Structure that is the essence of a bridge technology
43  */
44 struct ast_bridge_technology {
45         /*! Unique name to this bridge technology */
46         const char *name;
47         /*! The capabilities that this bridge technology is capable of.  This has nothing to do with
48          * format capabilities. */
49         uint32_t capabilities;
50         /*! Preference level that should be used when determining whether to use this bridge technology or not */
51         enum ast_bridge_preference preference;
52         /*! Callback for when a bridge is being created */
53         int (*create)(struct ast_bridge *bridge);
54         /*! Callback for when a bridge is being destroyed */
55         int (*destroy)(struct ast_bridge *bridge);
56         /*! Callback for when a channel is being added to a bridge */
57         int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
58         /*! Callback for when a channel is leaving a bridge */
59         int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
60         /*! Callback for when a channel is suspended from the bridge */
61         void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
62         /*! Callback for when a channel is unsuspended from the bridge */
63         void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
64         /*! Callback to see if a channel is compatible with the bridging technology */
65         int (*compatible)(struct ast_bridge_channel *bridge_channel);
66         /*! Callback for writing a frame into the bridging technology */
67         enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame);
68         /*! Callback for when a file descriptor trips */
69         int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd);
70         /*! Callback for replacement thread function */
71         int (*thread)(struct ast_bridge *bridge);
72         /*! Callback for poking a bridge thread */
73         int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
74         /*! Formats that the bridge technology supports */
75         struct ast_format_cap *format_capabilities;
76         /*! Bit to indicate whether the bridge technology is currently suspended or not */
77         unsigned int suspended:1;
78         /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */
79         struct ast_module *mod;
80         /*! Linked list information */
81         AST_RWLIST_ENTRY(ast_bridge_technology) entry;
82 };
83
84 /*! \brief Register a bridge technology for use
85  *
86  * \param technology The bridge technology to register
87  * \param mod The module that is registering the bridge technology
88  *
89  * \retval 0 on success
90  * \retval -1 on failure
91  *
92  * Example usage:
93  *
94  * \code
95  * ast_bridge_technology_register(&simple_bridge_tech);
96  * \endcode
97  *
98  * This registers a bridge technology declared as the structure
99  * simple_bridge_tech with the bridging core and makes it available for
100  * use when creating bridges.
101  */
102 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
103
104 /*! \brief See \ref __ast_bridge_technology_register() */
105 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
106
107 /*! \brief Unregister a bridge technology from use
108  *
109  * \param technology The bridge technology to unregister
110  *
111  * \retval 0 on success
112  * \retval -1 on failure
113  *
114  * Example usage:
115  *
116  * \code
117  * ast_bridge_technology_unregister(&simple_bridge_tech);
118  * \endcode
119  *
120  * This unregisters a bridge technlogy declared as the structure
121  * simple_bridge_tech with the bridging core. It will no longer be
122  * considered when creating a new bridge.
123  */
124 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
125
126 /*! \brief Feed notification that a frame is waiting on a channel into the bridging core
127  *
128  * \param bridge The bridge that the notification should influence
129  * \param bridge_channel Bridge channel the notification was received on (if known)
130  * \param chan Channel the notification was received on (if known)
131  * \param outfd File descriptor that the notification was received on (if known)
132  *
133  * Example usage:
134  *
135  * \code
136  * ast_bridge_handle_trip(bridge, NULL, chan, -1);
137  * \endcode
138  *
139  * This tells the bridging core that a frame has been received on
140  * the channel pointed to by chan and that it should be read and handled.
141  *
142  * \note This should only be used by bridging technologies.
143  */
144 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd);
145
146 /*! \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
147  *
148  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
149  * layer, which in this case is the specific bridging technology being used. Since it
150  * is necessary for the knowledge of which channels are talking to make its way up to the
151  * application, this function has been created to allow the bridging technology to communicate
152  * that information with the bridging core.
153  *
154  * \param bridge The bridge that the channel is a part of.
155  * \param bridge_channel The bridge channel that has either started or stopped talking.
156  * \param started_talking set to 1 when this indicates the channel has started talking set to 0
157  * when this indicates the channel has stopped talking.
158  */
159 void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking);
160
161 /*! \brief Suspend a bridge technology from consideration
162  *
163  * \param technology The bridge technology to suspend
164  *
165  * Example usage:
166  *
167  * \code
168  * ast_bridge_technology_suspend(&simple_bridge_tech);
169  * \endcode
170  *
171  * This suspends the bridge technology simple_bridge_tech from being considered
172  * when creating a new bridge. Existing bridges using the bridge technology
173  * are not affected.
174  */
175 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
176
177 /*! \brief Unsuspend a bridge technology
178  *
179  * \param technology The bridge technology to unsuspend
180  *
181  * Example usage:
182  *
183  * \code
184  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
185  * \endcode
186  *
187  * This makes the bridge technology simple_bridge_tech considered when
188  * creating a new bridge again.
189  */
190 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
191
192 #if defined(__cplusplus) || defined(c_plusplus)
193 }
194 #endif
195
196 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */