Bridge system: Fix memory leaks and double frees on impart failure.
[asterisk/asterisk.git] / include / asterisk / bridge_channel_internal.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Matt Jordan <mjordan@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 #ifndef _ASTERISK_PRIVATE_BRIDGING_CHANNEL_H
20 #define _ASTERISK_PRIVATE_BRIDGING_CHANNEL_H
21
22 /*!
23  * \file
24  * \brief Private Bridging Channel API
25  *
26  * \author Matt Jordan <mjordan@digium.com>
27  *
28  * A private API to manipulate channels in a bridge. These can be called on a channel in
29  * a bridge by \ref bridge.c. These functions should not be called elsewhere, including
30  * by other members of the Bridging API.
31  *
32  * See Also:
33  * \arg \ref AstCREDITS
34  * \arg \ref Ast
35  */
36
37 /*!
38  * \internal
39  * \brief Actions that can be taken on a channel in a bridge
40  */
41 enum bridge_channel_action_type {
42         /*! Bridged channel is to send a DTMF stream out */
43         BRIDGE_CHANNEL_ACTION_DTMF_STREAM,
44         /*! Bridged channel is to indicate talking start */
45         BRIDGE_CHANNEL_ACTION_TALKING_START,
46         /*! Bridged channel is to indicate talking stop */
47         BRIDGE_CHANNEL_ACTION_TALKING_STOP,
48         /*! Bridge channel is to play the indicated sound file. */
49         BRIDGE_CHANNEL_ACTION_PLAY_FILE,
50         /*! Bridge channel is to run the indicated application. */
51         BRIDGE_CHANNEL_ACTION_RUN_APP,
52         /*! Bridge channel is to run the custom callback routine. */
53         BRIDGE_CHANNEL_ACTION_CALLBACK,
54         /*! Bridge channel is to get parked. */
55         BRIDGE_CHANNEL_ACTION_PARK,
56         /*! Bridge channel is to execute a blind transfer. */
57         BRIDGE_CHANNEL_ACTION_BLIND_TRANSFER,
58         /*! Bridge channel is to execute an attended transfer */
59         BRIDGE_CHANNEL_ACTION_ATTENDED_TRANSFER,
60
61         /*
62          * Bridge actions put after this comment must never be put onto
63          * the bridge_channel wr_queue because they have other resources
64          * that must be freed.
65          */
66
67         /*! Bridge reconfiguration deferred technology destruction. */
68         BRIDGE_CHANNEL_ACTION_DEFERRED_TECH_DESTROY = 1000,
69         /*! Bridge deferred dissolving. */
70         BRIDGE_CHANNEL_ACTION_DEFERRED_DISSOLVING,
71 };
72
73 /*!
74  * \internal
75  * \brief Allocate a new ao2 ref counted bridge_channel
76  * \since 12.0.0
77  *
78  * \param bridge The bridge to make the bridge_channel for
79  *
80  * \retval NULL on error
81  * \retval ao2 ref counted object on success
82  */
83 struct ast_bridge_channel *bridge_channel_internal_alloc(struct ast_bridge *bridge);
84
85 /*!
86  * \internal
87  * \brief Settle owed events by the channel to the original bridge.
88  * \since 12.0.0
89  *
90  * \param orig_bridge Original bridge the channel was in before leaving.
91  * \param bridge_channel Channel that owes events to the original bridge.
92  *
93  * \note On entry, the orig_bridge is already locked.
94  *
95  * \return Nothing
96  */
97 void bridge_channel_settle_owed_events(struct ast_bridge *orig_bridge, struct ast_bridge_channel *bridge_channel);
98
99 /*!
100  * \internal
101  * \brief Push the bridge channel into its specified bridge.
102  * \since 12.0.0
103  *
104  * \param bridge_channel Channel to push.
105  *
106  * \note A ref is not held by bridge_channel->swap when calling because the
107  * push with swap happens immediately.
108  *
109  * \note On entry, bridge_channel->bridge is already locked.
110  *
111  * \retval 0 on success.
112  * \retval -1 on failure.  The channel did not get pushed.
113  *
114  * \note On failure the caller must call
115  * ast_bridge_features_remove(bridge_channel->features, AST_BRIDGE_HOOK_REMOVE_ON_PULL);
116  */
117 int bridge_channel_internal_push(struct ast_bridge_channel *bridge_channel);
118
119 /*!
120  * \internal
121  * \brief Push the bridge channel into its specified bridge.
122  * \since 13.8.0
123  *
124  * \param bridge_channel Channel to push.
125  * \param optimized non-zero if the push with swap is for an optimization.
126  *
127  * \note A ref is not held by bridge_channel->swap when calling because the
128  * push with swap happens immediately.
129  *
130  * \note On entry, bridge_channel->bridge is already locked.
131  *
132  * \retval 0 on success.
133  * \retval -1 on failure.  The channel did not get pushed.
134  *
135  * \note On failure the caller must call
136  * ast_bridge_features_remove(bridge_channel->features, AST_BRIDGE_HOOK_REMOVE_ON_PULL);
137  */
138 int bridge_channel_internal_push_full(struct ast_bridge_channel *bridge_channel, int optimized);
139
140 /*!
141  * \internal
142  * \brief Pull the bridge channel out of its current bridge.
143  * \since 12.0.0
144  *
145  * \param bridge_channel Channel to pull.
146  *
147  * \note On entry, bridge_channel->bridge is already locked.
148  *
149  * \return Nothing
150  */
151 void bridge_channel_internal_pull(struct ast_bridge_channel *bridge_channel);
152
153 /*!
154  * \brief Internal bridge channel wait condition and associated result.
155  */
156 struct bridge_channel_internal_cond {
157         /*! Lock for the data structure */
158         ast_mutex_t lock;
159         /*! Wait condition */
160         ast_cond_t cond;
161         /*! Wait until done */
162         int done;
163         /*! The bridge channel */
164         struct ast_bridge_channel *bridge_channel;
165 };
166
167 /*!
168  * \internal
169  * \brief Wait for the expected signal.
170  * \since 13.5.0
171  *
172  * \param cond the wait object
173  *
174  * \return Nothing
175  */
176 void bridge_channel_internal_wait(struct bridge_channel_internal_cond *cond);
177
178 /*!
179  * \internal
180  * \brief Signal the condition wait.
181  * \since 13.5.0
182  *
183  * \param cond the wait object
184  *
185  * \return Nothing
186  */
187 void bridge_channel_internal_signal(struct bridge_channel_internal_cond *cond);
188
189 /*!
190  * \internal
191  * \brief Join the bridge_channel to the bridge (blocking)
192  *
193  * \param bridge_channel The Channel in the bridge
194  * \param cond data used for signaling
195  *
196  * \note The bridge_channel->swap holds a channel reference for the swap
197  * channel going into the bridging system.  The ref ensures that the swap
198  * pointer is valid for the bridge subclass push callbacks.  The pointer
199  * will be NULL on return if the ref was consumed.
200  *
201  * \details
202  * This API call puts the bridge_channel into the bridge and handles the
203  * bridge_channel's processing of events while it is in the bridge.  It
204  * will return when the channel has been instructed to leave the bridge.
205  *
206  * \retval 0 bridge channel successfully joined the bridge
207  * \retval -1 bridge channel failed to join the bridge
208  */
209 int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel,
210                                  struct bridge_channel_internal_cond *cond);
211
212 /*!
213  * \internal
214  * \brief Temporarily suspend a channel from a bridge, handing control over to some
215  * other system
216  *
217  * \param bridge_channel The channel in the bridge
218  * \note This function assumes that \ref bridge_channel is already locked
219  */
220 void bridge_channel_internal_suspend_nolock(struct ast_bridge_channel *bridge_channel);
221
222 /*!
223  * \internal
224  * \brief Unsuspend a channel that was previously suspended
225  *
226  * \param bridge_channel The channel in the bridge
227  * \note This function assumes that \ref bridge_channel is already locked
228  */
229 void bridge_channel_internal_unsuspend_nolock(struct ast_bridge_channel *bridge_channel);
230
231 /*!
232  * \internal
233  * \brief Queue a blind transfer action on a transferee bridge channel
234  *
235  * This is only relevant for when a blind transfer is performed on a two-party
236  * bridge. The transferee's bridge channel will have a blind transfer bridge
237  * action queued onto it, resulting in the party being redirected to a new
238  * destination
239  *
240  * \param transferee The channel to have the action queued on
241  * \param exten The destination extension for the transferee
242  * \param context The destination context for the transferee
243  * \param hook Frame hook to attach to transferee
244  *
245  * \retval 0 on success.
246  * \retval -1 on error.
247  */
248 int bridge_channel_internal_queue_blind_transfer(struct ast_channel *transferee,
249                 const char *exten, const char *context,
250                 transfer_channel_cb new_channel_cb, void *user_data);
251
252 /*!
253  * \internal
254  * \brief Queue an attended transfer action on a transferee bridge channel
255  *
256  * This is only relevant for when an attended transfer is performed on a two-party
257  * bridge. The transferee's bridge channel will have an attended transfer bridge
258  * action queued onto it.
259  *
260  * \param transferee The channel to have the action queued on
261  * \param unbridged_chan The unbridged channel who is the target of the attended
262  * transfer
263  *
264  * \retval 0 on success.
265  * \retval -1 on error.
266  */
267 int bridge_channel_internal_queue_attended_transfer(struct ast_channel *transferee,
268                 struct ast_channel *unbridged_chan);
269
270 /*!
271  * \internal
272  * \brief Return whether or not the bridge_channel would allow optimization
273  *
274  * \retval 0 if optimization is not allowed
275  * \retval non-zero if optimization is allowed
276  */
277 int bridge_channel_internal_allows_optimization(struct ast_bridge_channel *bridge_channel);
278
279 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */