Removing registrar_expire from basic-pbx config
[asterisk/asterisk.git] / res / stasis / app.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@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_RES_STASIS_APP_H
20 #define _ASTERISK_RES_STASIS_APP_H
21
22 /*! \file
23  *
24  * \brief Internal API for the Stasis application controller.
25  *
26  * \author David M. Lee, II <dlee@digium.com>
27  * \since 12
28  */
29
30 #include "asterisk/channel.h"
31 #include "asterisk/stasis.h"
32 #include "asterisk/stasis_app.h"
33
34 /*!
35  * \brief Opaque pointer to \c res_stasis app structure.
36  */
37 struct stasis_app;
38
39 enum stasis_app_subscription_model {
40         /*
41          * \brief An application must manually subscribe to each
42          * resource that it cares about. This is the default approach.
43          */
44         STASIS_APP_SUBSCRIBE_MANUAL,
45         /*
46          * \brief An application is automatically subscribed to all
47          * resources in Asterisk, even if it does not control them.
48          */
49         STASIS_APP_SUBSCRIBE_ALL
50 };
51
52 /*!
53  * \brief Create a res_stasis application.
54  *
55  * \param name Name of the application.
56  * \param handler Callback for messages sent to the application.
57  * \param data Data pointer provided to the callback.
58  * \return New \c res_stasis application.
59  * \return \c NULL on error.
60  */
61 struct stasis_app *app_create(const char *name, stasis_app_cb handler, void *data, enum stasis_app_subscription_model subscription_model);
62
63 /*!
64  * \brief Tears down an application.
65  *
66  * It should be finished before calling this.
67  *
68  * \param app Application to unsubscribe.
69  */
70 void app_shutdown(struct stasis_app *app);
71
72 /*!
73  * \brief Deactivates an application.
74  *
75  * Any channels currently in the application remain active (since the app might
76  * come back), but new channels are rejected.
77  *
78  * \param app Application to deactivate.
79  */
80 void app_deactivate(struct stasis_app *app);
81
82 /*!
83  * \brief Checks whether an app is active.
84  *
85  * \param app Application to check.
86  * \return True (non-zero) if app is active.
87  * \return False (zero) if app has been deactivated.
88  */
89 int app_is_active(struct stasis_app *app);
90
91 /*!
92  * \brief Checks whether a deactivated app has no channels.
93  *
94  * \param app Application to check.
95  * \param True (non-zero) if app is deactivated, and has no associated channels.
96  * \param False (zero) otherwise.
97  */
98 int app_is_finished(struct stasis_app *app);
99
100 /*!
101  * \brief Update the handler and data for a \c res_stasis application.
102  *
103  * If app has been deactivated, this will reactivate it.
104  *
105  * \param app Application to update.
106  * \param handler New application callback.
107  * \param data New data pointer for the callback.
108  */
109 void app_update(struct stasis_app *app, stasis_app_cb handler, void *data);
110
111 /*!
112  * \brief Send a message to an application.
113  *
114  * \param app Application.
115  * \param message Message to send.
116  */
117 void app_send(struct stasis_app *app, struct ast_json *message);
118
119 struct app_forwards;
120
121 /*!
122  * \brief Create a JSON representation of a \c stasis_app
123  *
124  * \param app The application
125  *
126  * \return \c JSON blob on success
127  * \return \c NULL on error
128  */
129 struct ast_json *app_to_json(const struct stasis_app *app);
130
131 /*!
132  * \brief Subscribes an application to a channel.
133  *
134  * \param app Application.
135  * \param chan Channel to subscribe to.
136  * \return 0 on success.
137  * \return Non-zero on error.
138  */
139 int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
140
141 /*!
142  * \brief Cancel the subscription an app has for a channel.
143  *
144  * \param app Subscribing application.
145  * \param chan Channel to unsubscribe from.
146  * \return 0 on success.
147  * \return Non-zero on error.
148  */
149 int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
150
151 /*!
152  * \brief Cancel the subscription an app has for a channel.
153  *
154  * \param app Subscribing application.
155  * \param channel_id Id of channel to unsubscribe from.
156  * \return 0 on success.
157  * \return Non-zero on error.
158  */
159 int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
160
161 /*!
162  * \brief Test if an app is subscribed to a channel.
163  *
164  * \param app Subscribing application.
165  * \param channel_id Id of channel to check.
166  * \return True (non-zero) if channel is subscribed to \a app.
167  * \return False (zero) if channel is not subscribed.
168  */
169 int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id);
170
171 /*!
172  * \brief Add a bridge subscription to an existing channel subscription.
173  *
174  * \param app Application.
175  * \param bridge Bridge to subscribe to.
176  * \return 0 on success.
177  * \return Non-zero on error.
178  */
179 int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
180
181 /*!
182  * \brief Cancel the bridge subscription for an application.
183  *
184  * \param forwards Return from app_subscribe_channel().
185  * \param bridge Bridge to subscribe to.
186  * \return 0 on success.
187  * \return Non-zero on error.
188  */
189 int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
190
191 /*!
192  * \brief Cancel the subscription an app has for a bridge.
193  *
194  * \param app Subscribing application.
195  * \param bridge_id Id of bridge to unsubscribe from.
196  * \return 0 on success.
197  * \return Non-zero on error.
198  */
199 int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
200
201 /*!
202  * \brief Test if an app is subscribed to a bridge.
203  *
204  * \param app Subscribing application.
205  * \param bridge_id Id of bridge to check.
206  * \return True (non-zero) if bridge is subscribed to \a app.
207  * \return False (zero) if bridge is not subscribed.
208  */
209 int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
210
211 /*!
212  * \brief Subscribes an application to a endpoint.
213  *
214  * \param app Application.
215  * \param chan Endpoint to subscribe to.
216  * \return 0 on success.
217  * \return Non-zero on error.
218  */
219 int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint);
220
221 /*!
222  * \brief Cancel the subscription an app has for a endpoint.
223  *
224  * \param app Subscribing application.
225  * \param endpoint_id Id of endpoint to unsubscribe from.
226  * \return 0 on success.
227  * \return Non-zero on error.
228  */
229 int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id);
230
231 /*!
232  * \brief Test if an app is subscribed to a endpoint.
233  *
234  * \param app Subscribing application.
235  * \param endpoint_id Id of endpoint to check.
236  * \return True (non-zero) if endpoint is subscribed to \a app.
237  * \return False (zero) if endpoint is not subscribed.
238  */
239 int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id);
240
241 /*!
242  * \brief Set the snapshot of the channel that this channel will replace
243  *
244  * \param channel The channel on which this will be set
245  * \param replace_snapshot The snapshot of the channel that is being replaced
246  *
247  * \retval zero success
248  * \retval non-zero failure
249  */
250 int app_set_replace_channel_snapshot(struct ast_channel *chan, struct ast_channel_snapshot *replace_snapshot);
251
252 /*!
253  * \brief Set the app that the replacement channel will be controlled by
254  *
255  * \param channel The channel on which this will be set
256  * \param replace_app The app that will be controlling this channel
257  *
258  * \retval zero success
259  * \retval non-zero failure
260  */
261 int app_set_replace_channel_app(struct ast_channel *chan, const char *replace_app);
262
263 /*!
264  * \brief Get the app that the replacement channel will be controlled by
265  *
266  * \param channel The channel on which this will be set
267  *
268  * \retval NULL on error
269  * \return the name of the controlling app (must be ast_free()d)
270  */
271 char *app_get_replace_channel_app(struct ast_channel *chan);
272
273 /*!
274  * \brief Send StasisEnd message to the listening app
275  *
276  * \param app The app that owns the channel
277  * \param chan The channel for which the message is being sent
278  *
279  * \retval zero on success
280  * \return non-zero on failure
281  */
282 int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan);
283
284 #endif /* _ASTERISK_RES_STASIS_APP_H */