Perform the initial renaming of the Bridging API
[asterisk/asterisk.git] / include / asterisk / bridging_internal.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@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 /*!
20  * \file
21  * \brief Private Bridging API
22  *
23  * Functions in this file are intended to be used by the Bridging API,
24  * bridge mixing technologies, and bridge sub-classes. Users of bridges
25  * that do not fit those three categories should *not* use the API
26  * defined in this file.
27  *
28  * \author Mark Michelson <mmichelson@digium.com>
29  *
30  * See Also:
31  * \arg \ref AstCREDITS
32  */
33
34 #ifndef _ASTERISK_PRIVATE_BRIDGING_H
35 #define _ASTERISK_PRIVATE_BRIDGING_H
36
37 struct ast_bridge;
38 struct ast_bridge_channel;
39
40 /*!
41  * \brief Register the new bridge with the system.
42  * \since 12.0.0
43  *
44  * \param bridge What to register. (Tolerates a NULL pointer)
45  *
46  * \code
47  * struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
48  * {
49  *     void *bridge;
50  *
51  *     bridge = bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
52  *     bridge = bridge_base_init(bridge, capabilities, flags);
53  *     bridge = ast_bridge_basic_init(bridge, dtmf_features);
54  *     bridge = bridge_register(bridge);
55  *     return bridge;
56  * }
57  * \endcode
58  *
59  * \note This must be done after a bridge constructor has
60  * completed setting up the new bridge but before it returns.
61  *
62  * \note After a bridge is registered, ast_bridge_destroy() must
63  * eventually be called to get rid of the bridge.
64  *
65  * \retval bridge on success.
66  * \retval NULL on error.
67  */
68 struct ast_bridge *bridge_register(struct ast_bridge *bridge);
69
70 /*!
71  * \internal
72  * \brief Allocate the bridge class object memory.
73  * \since 12.0.0
74  *
75  * \param size Size of the bridge class structure to allocate.
76  * \param v_table Bridge class virtual method table.
77  *
78  * \retval bridge on success.
79  * \retval NULL on error.
80  */
81 struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
82
83 /*!
84  * \brief Initialize the base class of the bridge.
85  *
86  * \param self Bridge to operate upon. (Tolerates a NULL pointer)
87  * \param capabilities The capabilities that we require to be used on the bridge
88  * \param flags Flags that will alter the behavior of the bridge
89  *
90  * \retval self on success
91  * \retval NULL on failure, self is already destroyed
92  *
93  * Example usage:
94  *
95  * \code
96  * struct ast_bridge *bridge;
97  * bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
98  * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
99  * \endcode
100  *
101  * This creates a no frills two party bridge that will be
102  * destroyed once one of the channels hangs up.
103  */
104 struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags);
105
106 /*!
107  * \internal
108  * \brief Move a bridge channel from one bridge to another.
109  * \since 12.0.0
110  *
111  * \param dst_bridge Destination bridge of bridge channel move.
112  * \param bridge_channel Channel moving from one bridge to another.
113  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
114  * \param optimized Indicates whether the move is part of an unreal channel optimization.
115  *
116  * \note The dst_bridge and bridge_channel->bridge are assumed already locked.
117  *
118  * \retval 0 on success.
119  * \retval -1 on failure.
120  */
121 int bridge_do_move(struct ast_bridge *dst_bridge, struct ast_bridge_channel *bridge_channel,
122                 int attempt_recovery, unsigned int optimized);
123
124 /*!
125  * \internal
126  * \brief Do the merge of two bridges.
127  * \since 12.0.0
128  *
129  * \param dst_bridge Destination bridge of merge.
130  * \param src_bridge Source bridge of merge.
131  * \param kick_me Array of channels to kick from the bridges.
132  * \param num_kick Number of channels in the kick_me array.
133  * \param optimized Indicates whether the merge is part of an unreal channel optimization.
134  *
135  * \return Nothing
136  *
137  * \note The two bridges are assumed already locked.
138  *
139  * This moves the channels in src_bridge into the bridge pointed
140  * to by dst_bridge.
141  */
142 void bridge_do_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge,
143                 struct ast_bridge_channel **kick_me, unsigned int num_kick, unsigned int optimized);
144
145 /*!
146  * \internal
147  * \brief Helper function to find a bridge channel given a channel.
148  *
149  * \param bridge What to search
150  * \param chan What to search for.
151  *
152  * \note On entry, bridge is already locked.
153  *
154  * \retval bridge_channel if channel is in the bridge.
155  * \retval NULL if not in bridge.
156  */
157 struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct ast_channel *chan);
158
159 /*!
160  * \internal
161  * \brief Adjust the bridge merge inhibit request count.
162  * \since 12.0.0
163  *
164  * \param bridge What to operate on.
165  * \param request Inhibit request increment.
166  *     (Positive to add requests.  Negative to remove requests.)
167  *
168  * \note This function assumes bridge is locked.
169  *
170  * \return Nothing
171  */
172 void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
173
174 /*!
175  * \internal
176  * \brief Notify the bridge that it has been reconfigured.
177  * \since 12.0.0
178  *
179  * \param bridge Reconfigured bridge.
180  * \param colp_update Whether to perform COLP updates.
181  *
182  * \details
183  * After a series of bridge_channel_push and
184  * bridge_channel_pull calls, you need to call this function
185  * to cause the bridge to complete restructuring for the change
186  * in the channel makeup of the bridge.
187  *
188  * \note On entry, the bridge is already locked.
189  *
190  * \return Nothing
191  */
192 void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
193
194 /*!
195  * \internal
196  * \brief Dissolve the bridge.
197  * \since 12.0.0
198  *
199  * \param bridge Bridge to eject all channels
200  *
201  * \details
202  * Force out all channels that are not already going out of the
203  * bridge.  Any new channels joining will leave immediately.
204  *
205  * \note On entry, bridge is already locked.
206  *
207  * \return Nothing
208  */
209 void bridge_dissolve(struct ast_bridge *bridge);
210
211 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */