stasis/control: Fix possible deadlock with swap channel
[asterisk/asterisk.git] / include / asterisk / bridge_after.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Richard Mudgett <rmudgett@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 After Bridge Execution API
22  *
23  * \author Richard Mudgett <rmudgett@digium.com>
24  *
25  * See Also:
26  * \arg \ref AstCREDITS
27  */
28
29 #ifndef _ASTERISK_BRIDGING_AFTER_H
30 #define _ASTERISK_BRIDGING_AFTER_H
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 /*! Reason the the after bridge callback will not be called. */
37 enum ast_bridge_after_cb_reason {
38         /*! The datastore is being destroyed.  Likely due to hangup. (Enum value must be zero.) */
39         AST_BRIDGE_AFTER_CB_REASON_DESTROY,
40         /*! Something else replaced the callback with another. */
41         AST_BRIDGE_AFTER_CB_REASON_REPLACED,
42         /*! The callback was removed because of a masquerade. (fixup) */
43         AST_BRIDGE_AFTER_CB_REASON_MASQUERADE,
44         /*! The channel was departed from the bridge. */
45         AST_BRIDGE_AFTER_CB_REASON_DEPART,
46         /*! Was explicitly removed by external code. */
47         AST_BRIDGE_AFTER_CB_REASON_REMOVED,
48         /*! The channel failed to enter the bridge. */
49         AST_BRIDGE_AFTER_CB_REASON_IMPART_FAILED,
50 };
51
52 /*!
53  * \brief Set channel to goto specific location after the bridge.
54  * \since 12.0.0
55  *
56  * \param chan Channel to setup after bridge goto location.
57  * \param context Context to goto after bridge.
58  * \param exten Exten to goto after bridge.
59  * \param priority Priority to goto after bridge.
60  *
61  * \note chan is locked by this function.
62  *
63  * \details Add a channel datastore to setup the goto location
64  * when the channel leaves the bridge and run a PBX from there.
65  *
66  * \return Nothing
67  */
68 void ast_bridge_set_after_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
69
70 /*!
71  * \brief Set channel to run the h exten after the bridge.
72  * \since 12.0.0
73  *
74  * \param chan Channel to setup after bridge goto location.
75  * \param context Context to goto after bridge.
76  *
77  * \note chan is locked by this function.
78  *
79  * \details Add a channel datastore to setup the goto location
80  * when the channel leaves the bridge and run a PBX from there.
81  *
82  * \return Nothing
83  */
84 void ast_bridge_set_after_h(struct ast_channel *chan, const char *context);
85
86 /*!
87  * \brief Set channel to go on in the dialplan after the bridge.
88  * \since 12.0.0
89  *
90  * \param chan Channel to setup after bridge goto location.
91  * \param context Current context of the caller channel.
92  * \param exten Current exten of the caller channel.
93  * \param priority Current priority of the caller channel
94  * \param parseable_goto User specified goto string from dialplan.
95  *
96  * \note chan is locked by this function.
97  *
98  * \details Add a channel datastore to setup the goto location
99  * when the channel leaves the bridge and run a PBX from there.
100  *
101  * If parseable_goto then use the given context/exten/priority
102  *   as the relative position for the parseable_goto.
103  * Else goto the given context/exten/priority+1.
104  *
105  * \return Nothing
106  */
107 void ast_bridge_set_after_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto);
108
109 /*!
110  * \brief Setup any after bridge goto location to begin execution.
111  * \since 12.0.0
112  *
113  * \param chan Channel to setup after bridge goto location.
114  *
115  * \note chan is locked by this function.
116  *
117  * \details Pull off any after bridge goto location datastore and
118  * setup for dialplan execution there.
119  *
120  * \retval 0 on success.  The goto location is set for a PBX to run it.
121  * \retval non-zero on error or no goto location.
122  *
123  * \note If the after bridge goto is set to run an h exten it is
124  * run here immediately.
125  */
126 int ast_bridge_setup_after_goto(struct ast_channel *chan);
127
128 /*!
129  * \brief Run any after bridge callback.
130  * \since 12.0.0
131  *
132  * \param chan Channel to run after bridge callback.
133  *
134  * \return Nothing
135  */
136 void ast_bridge_run_after_callback(struct ast_channel *chan);
137
138 /*!
139  * \brief Run discarding any after bridge callbacks.
140  * \since 12.0.0
141  *
142  * \param chan Channel to run after bridge callback.
143  *
144  * \return Nothing
145  */
146 void ast_bridge_discard_after_callback(struct ast_channel *chan, enum ast_bridge_after_cb_reason reason);
147
148 /*!
149  * \brief Run a PBX on any after bridge goto location.
150  * \since 12.0.0
151  *
152  * \param chan Channel to execute after bridge goto location.
153  *
154  * \note chan is locked by this function.
155  *
156  * \details Pull off any after bridge goto location datastore
157  * and run a PBX at that location.
158  *
159  * \note On return, the chan pointer is no longer valid because
160  * the channel has hung up.
161  *
162  * \return Nothing
163  */
164 void ast_bridge_run_after_goto(struct ast_channel *chan);
165
166 /*!
167  * \brief Discard channel after bridge goto location.
168  * \since 12.0.0
169  *
170  * \param chan Channel to discard after bridge goto location.
171  *
172  * \note chan is locked by this function.
173  *
174  * \return Nothing
175  */
176 void ast_bridge_discard_after_goto(struct ast_channel *chan);
177
178 /*!
179  * \brief Read after bridge goto if it exists
180  * \since 12.0.0
181  *
182  * \param chan Channel to read the after bridge goto parseable goto string from
183  * \param buffer Buffer to write the after bridge goto data to
184  * \param buf_size size of the buffer being written to
185  */
186 void ast_bridge_read_after_goto(struct ast_channel *chan, char *buffer, size_t buf_size);
187
188 /*!
189  * \brief After bridge callback failed.
190  * \since 12.0.0
191  *
192  * \param reason Reason callback is failing.
193  * \param data Extra data what setup the callback wanted to pass.
194  *
195  * \note Called when the channel leaves the bridging system or
196  * is destroyed.
197  *
198  * \return Nothing
199  */
200 typedef void (*ast_bridge_after_cb_failed)(enum ast_bridge_after_cb_reason reason, void *data);
201
202 /*!
203  * \brief After bridge callback function.
204  * \since 12.0.0
205  *
206  * \param chan Channel just leaving bridging system.
207  * \param data Extra data what setup the callback wanted to pass.
208  *
209  * \return Nothing
210  */
211 typedef void (*ast_bridge_after_cb)(struct ast_channel *chan, void *data);
212
213 /*!
214  * \brief Setup an after bridge callback for when the channel leaves the bridging system.
215  * \since 12.0.0
216  *
217  * \param chan Channel to setup an after bridge callback on.
218  * \param callback Function to call when the channel leaves the bridging system.
219  * \param failed Function to call when it will not be calling the callback.
220  * \param data Extra data to pass with the callback.
221  *
222  * \note chan is locked by this function.
223  *
224  * \note failed is called when the channel leaves the bridging
225  * system or is destroyed.
226  *
227  * \retval 0 on success.
228  * \retval -1 on error.
229  */
230 int ast_bridge_set_after_callback(struct ast_channel *chan, ast_bridge_after_cb callback, ast_bridge_after_cb_failed failed, void *data);
231
232 /*!
233  * \brief Get a string representation of an after bridge callback reason
234  * \since 12.0.0
235  *
236  * \param reason The reason to interpret to a string
237  * \retval NULL Unrecognized reason
238  * \retval non-NULL String representation of reason
239  */
240 const char *ast_bridge_after_cb_reason_string(enum ast_bridge_after_cb_reason reason);
241
242 #if defined(__cplusplus) || defined(c_plusplus)
243 }
244 #endif
245
246 #endif  /* _ASTERISK_BRIDGING_H */