Asterisk - The Open Source Telephony Project  21.4.1
bridge_channel_internal.h
Go to the documentation of this file.
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 AstBridging
34  * \arg \ref AstCREDITS
35  */
36 
37 /*!
38  * \internal
39  * \brief Actions that can be taken on a channel in a bridge
40  */
42  /*! Bridged channel is to send a DTMF stream out */
44  /*! Bridged channel is to indicate talking start */
46  /*! Bridged channel is to indicate talking stop */
48  /*! Bridge channel is to play the indicated sound file. */
50  /*! Bridge channel is to run the indicated application. */
52  /*! Bridge channel is to run the custom callback routine. */
54  /*! Bridge channel is to get parked. */
56  /*! Bridge channel is to execute a blind transfer. */
58  /*! Bridge channel is to execute an 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. */
69  /*! Bridge 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  * \return 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 void bridge_channel_settle_owed_events(struct ast_bridge *orig_bridge, struct ast_bridge_channel *bridge_channel);
96 
97 /*!
98  * \internal
99  * \brief Queue any deferred frames on the channel.
100  * \since 13.17.0
101  *
102  * \param bridge_channel Channel that the deferred frames should be pulled from and queued to.
103  */
104 void bridge_channel_queue_deferred_frames(struct ast_bridge_channel *bridge_channel);
105 
106 /*!
107  * \internal
108  * \brief Push the bridge channel into its specified bridge.
109  * \since 12.0.0
110  *
111  * \param bridge_channel Channel to push.
112  *
113  * \note A ref is not held by bridge_channel->swap when calling because the
114  * push with swap happens immediately.
115  *
116  * \note On entry, bridge_channel->bridge is already locked.
117  *
118  * \retval 0 on success.
119  * \retval -1 on failure. The channel did not get pushed.
120  *
121  * \note On failure the caller must call
122  * ast_bridge_features_remove(bridge_channel->features, AST_BRIDGE_HOOK_REMOVE_ON_PULL);
123  */
124 int bridge_channel_internal_push(struct ast_bridge_channel *bridge_channel);
125 
126 /*!
127  * \internal
128  * \brief Push the bridge channel into its specified bridge.
129  * \since 13.8.0
130  *
131  * \param bridge_channel Channel to push.
132  * \param optimized non-zero if the push with swap is for an optimization.
133  *
134  * \note A ref is not held by bridge_channel->swap when calling because the
135  * push with swap happens immediately.
136  *
137  * \note On entry, bridge_channel->bridge is already locked.
138  *
139  * \retval 0 on success.
140  * \retval -1 on failure. The channel did not get pushed.
141  *
142  * \note On failure the caller must call
143  * ast_bridge_features_remove(bridge_channel->features, AST_BRIDGE_HOOK_REMOVE_ON_PULL);
144  */
145 int bridge_channel_internal_push_full(struct ast_bridge_channel *bridge_channel, int optimized);
146 
147 /*!
148  * \internal
149  * \brief Pull the bridge channel out of its current bridge.
150  * \since 12.0.0
151  *
152  * \param bridge_channel Channel to pull.
153  *
154  * \note On entry, bridge_channel->bridge is already locked.
155  */
156 void bridge_channel_internal_pull(struct ast_bridge_channel *bridge_channel);
157 
158 /*!
159  * \internal
160  * \brief Signal imparting threads to wake up.
161  * \since 13.9.0
162  *
163  * \param chan Channel imparted that we need to signal.
164  */
165 void bridge_channel_impart_signal(struct ast_channel *chan);
166 
167 /*!
168  * \internal
169  * \brief Join the bridge_channel to the bridge (blocking)
170  *
171  * \param bridge_channel The Channel in the bridge
172  *
173  * \note The bridge_channel->swap holds a channel reference for the swap
174  * channel going into the bridging system. The ref ensures that the swap
175  * pointer is valid for the bridge subclass push callbacks. The pointer
176  * will be NULL on return if the ref was consumed.
177  *
178  * \details
179  * This API call puts the bridge_channel into the bridge and handles the
180  * bridge_channel's processing of events while it is in the bridge. It
181  * will return when the channel has been instructed to leave the bridge.
182  *
183  * \retval 0 bridge channel successfully joined the bridge
184  * \retval -1 bridge channel failed to join the bridge
185  */
186 int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel);
187 
188 /*!
189  * \internal
190  * \brief Suspend a channel from a bridge.
191  *
192  * \param bridge_channel Channel to suspend.
193  *
194  * \note This function assumes bridge_channel->bridge is locked.
195  */
196 void bridge_channel_internal_suspend_nolock(struct ast_bridge_channel *bridge_channel);
197 
198 /*!
199  * \internal
200  * \brief Unsuspend a channel from a bridge.
201  *
202  * \param bridge_channel Channel to unsuspend.
203  *
204  * \note This function assumes bridge_channel->bridge is locked.
205  */
206 void bridge_channel_internal_unsuspend_nolock(struct ast_bridge_channel *bridge_channel);
207 
208 /*!
209  * \internal
210  * \brief Queue a blind transfer action on a transferee bridge channel
211  *
212  * This is only relevant for when a blind transfer is performed on a two-party
213  * bridge. The transferee's bridge channel will have a blind transfer bridge
214  * action queued onto it, resulting in the party being redirected to a new
215  * destination
216  *
217  * \param transferee The channel to have the action queued on
218  * \param exten The destination extension for the transferee
219  * \param context, new_channel_cb, user_data
220  *
221  * \retval 0 on success.
222  * \retval -1 on error.
223  */
224 int bridge_channel_internal_queue_blind_transfer(struct ast_channel *transferee,
225  const char *exten, const char *context,
226  transfer_channel_cb new_channel_cb, void *user_data);
227 
228 /*!
229  * \internal
230  * \brief Queue an attended transfer action on a transferee bridge channel
231  *
232  * This is only relevant for when an attended transfer is performed on a two-party
233  * bridge. The transferee's bridge channel will have an attended transfer bridge
234  * action queued onto it.
235  *
236  * \param transferee The channel to have the action queued on
237  * \param unbridged_chan The unbridged channel who is the target of the attended
238  * transfer
239  *
240  * \retval 0 on success.
241  * \retval -1 on error.
242  */
243 int bridge_channel_internal_queue_attended_transfer(struct ast_channel *transferee,
244  struct ast_channel *unbridged_chan);
245 
246 /*!
247  * \internal
248  * \brief Return whether or not the bridge_channel would allow optimization
249  *
250  * \retval 0 if optimization is not allowed
251  * \retval non-zero if optimization is allowed
252  */
253 int bridge_channel_internal_allows_optimization(struct ast_bridge_channel *bridge_channel);
254 
255 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */
Main Channel structure associated with a channel.
struct ast_bridge * bridge
Bridge this channel is participating in.
Structure that contains information about a bridge.
Definition: bridge.h:349
struct ast_channel * chan
Structure that contains information regarding a channel in a bridge.
bridge_channel_action_type
void(* transfer_channel_cb)(struct ast_channel *chan, struct transfer_channel_data *user_data, enum ast_transfer_type transfer_type)
Callback function type called during blind transfers.
Definition: bridge.h:1143