Asterisk - The Open Source Telephony Project GIT-master-2de1a68
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 <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 */
37struct 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 * \param subscription_model
59 * \return New \c res_stasis application.
60 * \retval NULL on error.
61 */
63
64/*!
65 * \brief Tears down an application.
66 *
67 * It should be finished before calling this.
68 *
69 * \param app Application to unsubscribe.
70 */
71void app_shutdown(struct stasis_app *app);
72
73/*!
74 * \brief Deactivates an application.
75 *
76 * Any channels currently in the application remain active (since the app might
77 * come back), but new channels are rejected.
78 *
79 * \param app Application to deactivate.
80 */
81void app_deactivate(struct stasis_app *app);
82
83/*!
84 * \brief Checks whether an app is active.
85 *
86 * \param app Application to check.
87 * \retval True (non-zero) if app is active.
88 * \retval False (zero) if app has been deactivated.
89 */
90int app_is_active(struct stasis_app *app);
91
92/*!
93 * \brief Checks whether a deactivated app has no channels.
94 *
95 * \param app Application to check.
96 * \retval True (non-zero) if app is deactivated, and has no associated channels.
97 * \retval False (zero) otherwise.
98 */
99int app_is_finished(struct stasis_app *app);
100
101/*!
102 * \brief Update the handler and data for a \c res_stasis application.
103 *
104 * If app has been deactivated, this will reactivate it.
105 *
106 * \param app Application to update.
107 * \param handler New application callback.
108 * \param data New data pointer for the callback.
109 */
110void app_update(struct stasis_app *app, stasis_app_cb handler, void *data);
111
112/*!
113 * \brief Send a message to an application.
114 *
115 * \param app App to send the message to.
116 * \param message Message to send.
117 */
118void app_send(struct stasis_app *app, struct ast_json *message);
119
120struct app_forwards;
121
122/*!
123 * \brief Create a JSON representation of a \c stasis_app
124 *
125 * \param app The application
126 *
127 * \return JSON blob on success
128 * \retval NULL on error
129 */
130struct ast_json *app_to_json(const struct stasis_app *app);
131
132/*!
133 * \brief Subscribes an application to a channel.
134 *
135 * \param app Application.
136 * \param chan Channel to subscribe to.
137 * \retval 0 on success.
138 * \retval Non-zero on error.
139 */
140int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
141
142/*!
143 * \brief Cancel the subscription an app has for a channel.
144 *
145 * \param app Subscribing application.
146 * \param chan Channel to unsubscribe from.
147 * \retval 0 on success.
148 * \retval Non-zero on error.
149 */
150int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
151
152/*!
153 * \brief Cancel the subscription an app has for a channel.
154 *
155 * \param app Subscribing application.
156 * \param channel_id Id of channel to unsubscribe from.
157 * \retval 0 on success.
158 * \retval Non-zero on error.
159 */
160int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
161
162/*!
163 * \brief Test if an app is subscribed to a channel.
164 *
165 * \param app Subscribing application.
166 * \param channel_id Id of channel to check.
167 * \retval True (non-zero) if channel is subscribed to \a app.
168 * \retval False (zero) if channel is not subscribed.
169 */
170int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id);
171
172/*!
173 * \brief Add a bridge subscription to an existing channel subscription.
174 *
175 * \param app Application.
176 * \param bridge Bridge to subscribe to.
177 * \retval 0 on success.
178 * \retval Non-zero on error.
179 */
180int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
181
182/*!
183 * \brief Cancel the bridge subscription for an application.
184 *
185 * \param app Subscribing application.
186 * \param bridge Bridge to subscribe to.
187 * \retval 0 on success.
188 * \retval Non-zero on error.
189 */
190int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
191
192/*!
193 * \brief Cancel the subscription an app has for a bridge.
194 *
195 * \param app Subscribing application.
196 * \param bridge_id Id of bridge to unsubscribe from.
197 * \retval 0 on success.
198 * \retval Non-zero on error.
199 */
200int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
201
202/*!
203 * \brief Test if an app is subscribed to a bridge.
204 *
205 * \param app Subscribing application.
206 * \param bridge_id Id of bridge to check.
207 * \retval True (non-zero) if bridge is subscribed to \a app.
208 * \retval False (zero) if bridge is not subscribed.
209 */
210int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
211
212/*!
213 * \brief Subscribes an application to a endpoint.
214 *
215 * \param app Application.
216 * \param endpoint Endpoint to subscribe to.
217 * \retval 0 on success.
218 * \retval Non-zero on error.
219 */
220int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint);
221
222/*!
223 * \brief Cancel the subscription an app has for a endpoint.
224 *
225 * \param app Subscribing application.
226 * \param endpoint_id Id of endpoint to unsubscribe from.
227 * \retval 0 on success.
228 * \retval Non-zero on error.
229 */
230int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id);
231
232/*!
233 * \brief Test if an app is subscribed to a endpoint.
234 *
235 * \param app Subscribing application.
236 * \param endpoint_id Id of endpoint to check.
237 * \retval True (non-zero) if endpoint is subscribed to \a app.
238 * \retval False (zero) if endpoint is not subscribed.
239 */
240int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id);
241
242/*!
243 * \brief Set the snapshot of the channel that this channel will replace
244 *
245 * \param chan The channel on which this will be set
246 * \param replace_snapshot The snapshot of the channel that is being replaced
247 *
248 * \retval zero success
249 * \retval non-zero failure
250 */
251int app_set_replace_channel_snapshot(struct ast_channel *chan, struct ast_channel_snapshot *replace_snapshot);
252
253/*!
254 * \brief Set the app that the replacement channel will be controlled by
255 *
256 * \param chan The channel on which this will be set
257 * \param replace_app The app that will be controlling this channel
258 *
259 * \retval zero success
260 * \retval non-zero failure
261 */
262int app_set_replace_channel_app(struct ast_channel *chan, const char *replace_app);
263
264/*!
265 * \brief Get the app that the replacement channel will be controlled by
266 *
267 * \param chan The channel on which this will be set
268 *
269 * \retval NULL on error
270 * \return the name of the controlling app (must be ast_free()d)
271 */
272char *app_get_replace_channel_app(struct ast_channel *chan);
273
274/*!
275 * \brief Send StasisEnd message to the listening app
276 *
277 * \param app The app that owns the channel
278 * \param chan The channel for which the message is being sent
279 *
280 * \retval zero on success
281 * \return non-zero on failure
282 */
283int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan);
284
285#endif /* _ASTERISK_RES_STASIS_APP_H */
static const char app[]
Definition: app_adsiprog.c:56
General Asterisk PBX channel definitions.
static const char name[]
Definition: format_mp3.c:68
int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint)
Subscribes an application to a endpoint.
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:934
int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id)
Test if an app is subscribed to a endpoint.
int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id)
Cancel the subscription an app has for a bridge.
int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge)
Add a bridge subscription to an existing channel subscription.
void app_update(struct stasis_app *app, stasis_app_cb handler, void *data)
Update the handler and data for a res_stasis application.
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:922
int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id)
Test if an app is subscribed to a channel.
int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge)
Cancel the bridge subscription for an application.
void app_shutdown(struct stasis_app *app)
Tears down an application.
int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan)
Cancel the subscription an app has for a channel.
int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan)
Subscribes an application to a channel.
int app_is_finished(struct stasis_app *app)
Checks whether a deactivated app has no channels.
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_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id)
Cancel the subscription an app has for a endpoint.
int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan)
Send StasisEnd message to the listening app.
Definition: res_stasis.c:1086
int app_is_active(struct stasis_app *app)
Checks whether an app is active.
struct ast_json * app_to_json(const struct stasis_app *app)
Create a JSON representation of a stasis_app.
int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id)
Cancel the subscription an app has for a channel.
int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id)
Test if an app is subscribed to a bridge.
void app_deactivate(struct stasis_app *app)
Deactivates an application.
stasis_app_subscription_model
@ STASIS_APP_SUBSCRIBE_MANUAL
An application must manually subscribe to each resource that it cares about. This is the default appr...
@ STASIS_APP_SUBSCRIBE_ALL
An application is automatically subscribed to all resources in Asterisk, even if it does not control ...
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:970
void app_send(struct stasis_app *app, struct ast_json *message)
Send a message to an application.
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
Stasis Application API. See Stasis Application API for detailed documentation.
void(* stasis_app_cb)(void *data, const char *app_name, struct ast_json *message)
Callback for Stasis application handler.
Definition: stasis_app.h:67
Structure that contains information about a bridge.
Definition: bridge.h:349
Structure representing a snapshot of channel state.
Main Channel structure associated with a channel.
Abstract JSON element (object, array, string, int, ...).
enum stasis_app_subscription_model subscription_model
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