Merge phase 1 support for the new bridging architecture.
[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 */
48         int capabilities;
49         /*! Preference level that should be used when determining whether to use this bridge technology or not */
50         enum ast_bridge_preference preference;
51         /*! Callback for when a bridge is being created */
52         int (*create)(struct ast_bridge *bridge);
53         /*! Callback for when a bridge is being destroyed */
54         int (*destroy)(struct ast_bridge *bridge);
55         /*! Callback for when a channel is being added to a bridge */
56         int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
57         /*! Callback for when a channel is leaving a bridge */
58         int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
59         /*! Callback for when a channel is suspended from the bridge */
60         void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
61         /*! Callback for when a channel is unsuspended from the bridge */
62         void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
63         /*! Callback to see if a channel is compatible with the bridging technology */
64         int (*compatible)(struct ast_bridge_channel *bridge_channel);
65         /*! Callback for writing a frame into the bridging technology */
66         enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame);
67         /*! Callback for when a file descriptor trips */
68         int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd);
69         /*! Callback for replacement thread function */
70         int (*thread)(struct ast_bridge *bridge);
71         /*! Callback for poking a bridge thread */
72         int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
73         /*! Formats that the bridge technology supports */
74         int formats;
75         /*! Bit to indicate whether the bridge technology is currently suspended or not */
76         unsigned int suspended:1;
77         /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */
78         struct ast_module *mod;
79         /*! Linked list information */
80         AST_RWLIST_ENTRY(ast_bridge_technology) entry;
81 };
82
83 /*! \brief Register a bridge technology for use
84  *
85  * \param technology The bridge technology to register
86  * \param module The module that is registering the bridge technology
87  *
88  * \retval 0 on success
89  * \retval -1 on failure
90  *
91  * Example usage:
92  *
93  * \code
94  * ast_bridge_technology_register(&simple_bridge_tech);
95  * \endcode
96  *
97  * This registers a bridge technology declared as the structure
98  * simple_bridge_tech with the bridging core and makes it available for
99  * use when creating bridges.
100  */
101 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
102
103 /*! \brief See \ref __ast_bridge_technology_register() */
104 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
105
106 /*! \brief Unregister a bridge technology from use
107  *
108  * \param technology The bridge technology to unregister
109  *
110  * \retval 0 on success
111  * \retval -1 on failure
112  *
113  * Example usage:
114  *
115  * \code
116  * ast_bridge_technology_unregister(&simple_bridge_tech);
117  * \endcode
118  *
119  * This unregisters a bridge technlogy declared as the structure
120  * simple_bridge_tech with the bridging core. It will no longer be
121  * considered when creating a new bridge.
122  */
123 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
124
125 /*! \brief Feed notification that a frame is waiting on a channel into the bridging core
126  *
127  * \param bridge The bridge that the notification should influence
128  * \param bridge_channel Bridge channel the notification was received on (if known)
129  * \param chan Channel the notification was received on (if known)
130  * \param outfd File descriptor that the notification was received on (if known)
131  *
132  * Example usage:
133  *
134  * \code
135  * ast_bridge_handle_trip(bridge, NULL, chan, -1);
136  * \endcode
137  *
138  * This tells the bridging core that a frame has been received on
139  * the channel pointed to by chan and that it should be read and handled.
140  *
141  * \note This should only be used by bridging technologies.
142  */
143 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd);
144
145 /*! \brief Suspend a bridge technology from consideration
146  *
147  * \param technology The bridge technology to suspend
148  *
149  * Example usage:
150  *
151  * \code
152  * ast_bridge_technology_suspend(&simple_bridge_tech);
153  * \endcode
154  *
155  * This suspends the bridge technology simple_bridge_tech from being considered
156  * when creating a new bridge. Existing bridges using the bridge technology
157  * are not affected.
158  */
159 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
160
161 /*! \brief Unsuspend a bridge technology
162  *
163  * \param technology The bridge technology to unsuspend
164  *
165  * Example usage:
166  *
167  * \code
168  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
169  * \endcode
170  *
171  * This makes the bridge technology simple_bridge_tech considered when
172  * creating a new bridge again.
173  */
174 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
175
176 #if defined(__cplusplus) || defined(c_plusplus)
177 }
178 #endif
179
180 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */