Asterisk - The Open Source Telephony Project  21.4.1
bridge_after.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  * 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 after bridge callback will not be called. */
38  /*! The datastore is being destroyed. Likely due to hangup. (Enum value must be zero.) */
40  /*! Something else replaced the callback with another. */
42  /*! The callback was removed because of a masquerade. (fixup) */
44  /*! The channel was departed from the bridge. */
46  /*! Was explicitly removed by external code. */
48  /*! The channel failed to enter the bridge. */
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  * Add a channel datastore to setup the goto location when the
64  * channel leaves the bridge and run a PBX from there.
65  */
66 void ast_bridge_set_after_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
67 
68 /*!
69  * \brief Set channel to run the h exten after the bridge.
70  * \since 12.0.0
71  *
72  * \param chan Channel to setup after bridge goto location.
73  * \param context Context to goto after bridge.
74  *
75  * \note chan is locked by this function.
76  *
77  * Add a channel datastore to setup the goto location when the
78  * channel leaves the bridge and run a PBX from there.
79  */
80 void ast_bridge_set_after_h(struct ast_channel *chan, const char *context);
81 
82 /*!
83  * \brief Set channel to go on in the dialplan after the bridge.
84  * \since 12.0.0
85  *
86  * \param chan Channel to setup after bridge goto location.
87  * \param context Current context of the caller channel.
88  * \param exten Current exten of the caller channel.
89  * \param priority Current priority of the caller channel
90  * \param parseable_goto User specified goto string from dialplan.
91  *
92  * \note chan is locked by this function.
93  *
94  * Add a channel datastore to setup the goto location when the
95  * channel leaves the bridge and run a PBX from there.
96  *
97  * If parseable_goto then use the given context/exten/priority
98  * as the relative position for the parseable_goto.
99  * Else goto the given context/exten/priority+1.
100  */
101 void ast_bridge_set_after_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto);
102 
103 /*!
104  * \brief Setup any after bridge goto location to begin execution.
105  * \since 12.0.0
106  *
107  * \param chan Channel to setup after bridge goto location.
108  *
109  * \note chan is locked by this function.
110  *
111  * Pull off any after bridge goto location datastore and setup for
112  * dialplan execution there.
113  *
114  * \retval 0 on success. The goto location is set for a PBX to run it.
115  * \retval non-zero on error or no goto location.
116  *
117  * \note If the after bridge goto is set to run an h exten it is
118  * run here immediately.
119  */
120 int ast_bridge_setup_after_goto(struct ast_channel *chan);
121 
122 /*!
123  * \brief Run any after bridge callback.
124  * \since 12.0.0
125  *
126  * \param chan Channel to run after bridge callback.
127  */
128 void ast_bridge_run_after_callback(struct ast_channel *chan);
129 
130 /*!
131  * \brief Run discarding any after bridge callbacks.
132  * \since 12.0.0
133  *
134  * \param chan Channel to run after bridge callback.
135  * \param reason
136  */
138 
139 /*!
140  * \brief Run a PBX on any after bridge goto location.
141  * \since 12.0.0
142  *
143  * \param chan Channel to execute after bridge goto location.
144  *
145  * \note chan is locked by this function.
146  *
147  * Pull off any after bridge goto location datastore and run a PBX at that
148  * location.
149  *
150  * \note On return, the chan pointer is no longer valid because
151  * the channel has hung up.
152  */
153 void ast_bridge_run_after_goto(struct ast_channel *chan);
154 
155 /*!
156  * \brief Discard channel after bridge goto location.
157  * \since 12.0.0
158  *
159  * \param chan Channel to discard after bridge goto location.
160  *
161  * \note chan is locked by this function.
162  */
163 void ast_bridge_discard_after_goto(struct ast_channel *chan);
164 
165 /*!
166  * \brief Read after bridge goto if it exists
167  * \since 12.0.0
168  *
169  * \param chan Channel to read the after bridge goto parseable goto string from
170  * \param buffer Buffer to write the after bridge goto data to
171  * \param buf_size size of the buffer being written to
172  */
173 void ast_bridge_read_after_goto(struct ast_channel *chan, char *buffer, size_t buf_size);
174 
175 /*!
176  * \brief After bridge callback failed.
177  * \since 12.0.0
178  *
179  * \param reason Reason callback is failing.
180  * \param data Extra data what setup the callback wanted to pass.
181  *
182  * \note Called when the channel leaves the bridging system or
183  * is destroyed.
184  */
185 typedef void (*ast_bridge_after_cb_failed)(enum ast_bridge_after_cb_reason reason, void *data);
186 
187 /*!
188  * \brief After bridge callback function.
189  * \since 12.0.0
190  *
191  * \param chan Channel just leaving bridging system.
192  * \param data Extra data what setup the callback wanted to pass.
193  */
194 typedef void (*ast_bridge_after_cb)(struct ast_channel *chan, void *data);
195 
196 /*!
197  * \brief Setup an after bridge callback for when the channel leaves the bridging system.
198  * \since 12.0.0
199  *
200  * \param chan Channel to setup an after bridge callback on.
201  * \param callback Function to call when the channel leaves the bridging system.
202  * \param failed Function to call when it will not be calling the callback.
203  * \param data Extra data to pass with the callback.
204  *
205  * \note chan is locked by this function.
206  *
207  * \note failed is called when the channel leaves the bridging
208  * system or is destroyed.
209  *
210  * \retval 0 on success.
211  * \retval -1 on error.
212  */
214 
215 /*!
216  * \brief Get a string representation of an after bridge callback reason
217  * \since 12.0.0
218  *
219  * \param reason The reason to interpret to a string
220  * \retval NULL Unrecognized reason
221  * \retval non-NULL String representation of reason
222  */
224 
225 #if defined(__cplusplus) || defined(c_plusplus)
226 }
227 #endif
228 
229 #endif /* _ASTERISK_BRIDGING_H */
Main Channel structure associated with a channel.
void ast_bridge_run_after_goto(struct ast_channel *chan)
Run a PBX on any after bridge goto location.
Definition: bridge_after.c:525
const char * ast_bridge_after_cb_reason_string(enum ast_bridge_after_cb_reason reason)
Get a string representation of an after bridge callback reason.
Definition: bridge_after.c:288
const char * parseable_goto
Definition: bridge_after.c:309
const char * data
int ast_bridge_set_after_callback(struct ast_channel *chan, ast_bridge_after_cb callback, ast_bridge_after_cb_failed failed, void *data)
Setup an after bridge callback for when the channel leaves the bridging system.
Definition: bridge_after.c:251
void ast_bridge_set_after_h(struct ast_channel *chan, const char *context)
Set channel to run the h exten after the bridge.
Definition: bridge_after.c:617
void ast_bridge_discard_after_callback(struct ast_channel *chan, enum ast_bridge_after_cb_reason reason)
Run discarding any after bridge callbacks.
Definition: bridge_after.c:239
ast_bridge_after_cb_reason
Definition: bridge_after.h:37
void ast_bridge_set_after_goto(struct ast_channel *chan, const char *context, const char *exten, int priority)
Set channel to goto specific location after the bridge.
Definition: bridge_after.c:612
void ast_bridge_discard_after_goto(struct ast_channel *chan)
Discard channel after bridge goto location.
Definition: bridge_after.c:384
const char * context
Definition: bridge_after.c:311
const char * exten
Definition: bridge_after.c:313
void ast_bridge_run_after_callback(struct ast_channel *chan)
Run any after bridge callback.
Definition: bridge_after.c:212
void ast_bridge_set_after_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto)
Set channel to go on in the dialplan after the bridge.
Definition: bridge_after.c:622
void ast_bridge_read_after_goto(struct ast_channel *chan, char *buffer, size_t buf_size)
Read after bridge goto if it exists.
Definition: bridge_after.c:394
void(* ast_bridge_after_cb)(struct ast_channel *chan, void *data)
After bridge callback function.
Definition: bridge_after.h:194
void(* ast_bridge_after_cb_failed)(enum ast_bridge_after_cb_reason reason, void *data)
After bridge callback failed.
Definition: bridge_after.h:185
int ast_bridge_setup_after_goto(struct ast_channel *chan)
Setup any after bridge goto location to begin execution.
Definition: bridge_after.c:435