Asterisk - The Open Source Telephony Project  18.5.0
res/stasis/app.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  * David M. Lee, II <[email protected]>
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 <[email protected]>
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 
40  /*
41  * \brief An application must manually subscribe to each
42  * resource that it cares about. This is the default approach.
43  */
45  /*
46  * \brief An application is automatically subscribed to all
47  * resources in Asterisk, even if it does not control them.
48  */
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  */
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 */
int app_is_finished(struct stasis_app *app)
Checks whether a deactivated app has no channels.
Main Channel structure associated with a channel.
int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint)
Subscribes an application to a endpoint.
stasis_app_subscription_model
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
Structure representing a snapshot of channel state.
int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan)
Send StasisEnd message to the listening app.
Definition: res_stasis.c:1083
struct ast_json * app_to_json(const struct stasis_app *app)
Create a JSON representation of a stasis_app.
int app_is_active(struct stasis_app *app)
Checks whether an app is active.
int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id)
Test if an app is subscribed to a bridge.
int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id)
Test if an app is subscribed to a channel.
char * app_get_replace_channel_app(struct ast_channel *chan)
Get the app that the replacement channel will be controlled by.
Definition: res_stasis.c:967
General Asterisk PBX channel definitions.
int app_set_replace_channel_snapshot(struct ast_channel *chan, struct ast_channel_snapshot *replace_snapshot)
Set the snapshot of the channel that this channel will replace.
Definition: res_stasis.c:919
int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id)
Cancel the subscription an app has for a channel.
Structure that contains information about a bridge.
Definition: bridge.h:357
struct stasis_app * app_create(const char *name, stasis_app_cb handler, void *data, enum stasis_app_subscription_model subscription_model)
Create a res_stasis application.
int app_set_replace_channel_app(struct ast_channel *chan, const char *replace_app)
Set the app that the replacement channel will be controlled by.
Definition: res_stasis.c:931
static const char name[]
Definition: cdr_mysql.c:74
void app_deactivate(struct stasis_app *app)
Deactivates an application.
void app_send(struct stasis_app *app, struct ast_json *message)
Send a message to an application.
int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id)
Cancel the subscription an app has for a endpoint.
int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan)
Subscribes an application to a channel.
void(* stasis_app_cb)(void *data, const char *app_name, struct ast_json *message)
Callback for Stasis application handler.
Definition: stasis_app.h:67
int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan)
Cancel the subscription an app has for a channel.
void app_shutdown(struct stasis_app *app)
Tears down an application.
int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id)
Cancel the subscription an app has for a bridge.
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
Abstract JSON element (object, array, string, int, ...).
int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge)
Add a bridge subscription to an existing channel subscription.
int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id)
Test if an app is subscribed to a endpoint.
void app_update(struct stasis_app *app, stasis_app_cb handler, void *data)
Update the handler and data for a res_stasis application.
Stasis Application API. See Stasis Application API for detailed documentation.
static const char app[]
Definition: app_mysql.c:62
enum stasis_app_subscription_model subscription_model
int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge)
Cancel the bridge subscription for an application.