Asterisk - The Open Source Telephony Project  21.4.1
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  */
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  * \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  */
71 void 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  */
81 void 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  */
90 int 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  */
99 int 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  */
110 void 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  */
118 void app_send(struct stasis_app *app, struct ast_json *message);
119 
120 struct 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  */
130 struct 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  */
140 int 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  */
150 int 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  */
160 int 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  */
170 int 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  */
180 int 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  */
190 int 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  */
200 int 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  */
210 int 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  */
220 int 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  */
230 int 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  */
240 int 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  */
251 int 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  */
262 int 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  */
272 char *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  */
283 int app_send_end_msg(struct stasis_app *app, struct ast_channel *chan);
284 
285 #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.
An application must manually subscribe to each resource that it cares about. This is the default appr...
stasis_app_subscription_model
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
Structure representing a snapshot of channel state.
stasis_app_cb handler
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
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:970
An application is automatically subscribed to all resources in Asterisk, even if it does not control ...
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:922
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:349
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:934
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.
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.
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.