Continue events when ARI WebSocket reconnects
[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 app;
38
39 /*!
40  * \brief Create a res_stasis application.
41  *
42  * \param name Name of the application.
43  * \param handler Callback for messages sent to the application.
44  * \param data Data pointer provided to the callback.
45  * \return New \c res_stasis application.
46  * \return \c NULL on error.
47  */
48 struct app *app_create(const char *name, stasis_app_cb handler, void *data);
49
50 /*!
51  * \brief Deactivates an application.
52  *
53  * Any channels currently in the application remain active (since the app might
54  * come back), but new channels are rejected.
55  *
56  * \param app Application to deactivate.
57  */
58 void app_deactivate(struct app *app);
59
60 /*!
61  * \brief Checks whether an app is active.
62  *
63  * \param app Application to check.
64  * \return True (non-zero) if app is active.
65  * \return False (zero) if app has been deactivated.
66  */
67 int app_is_active(struct app *app);
68
69 /*!
70  * \brief Checks whether a deactivated app has no channels.
71  *
72  * \param app Application to check.
73  * \param True (non-zero) if app is deactivated, and has no associated channels.
74  * \param False (zero) otherwise.
75  */
76 int app_is_finished(struct app *app);
77
78 /*!
79  * \brief Update the handler and data for a \c res_stasis application.
80  *
81  * If app has been deactivated, this will reactivate it.
82  *
83  * \param app Application to update.
84  * \param handler New application callback.
85  * \param data New data pointer for the callback.
86  */
87 void app_update(struct app *app, stasis_app_cb handler, void *data);
88
89 /*!
90  * \brief Return an application's name.
91  *
92  * \param app Application.
93  * \return Name of the application.
94  * \return \c NULL is \a app is \c NULL.
95  */
96 const char *app_name(const struct app *app);
97
98 /*!
99  * \brief Subscribe an application to a topic.
100  *
101  * \param app Application.
102  * \param topic Topic to subscribe to.
103  * \return New subscription.
104  * \return \c NULL on error.
105  */
106 struct stasis_subscription *app_subscribe(struct app *app,
107         struct stasis_topic *topic);
108
109 /*!
110  * \brief Send a message to an application.
111  *
112  * \param app Application.
113  * \param message Message to send.
114  */
115 void app_send(struct app *app, struct ast_json *message);
116
117 /*!
118  * \brief Send the start message to an application.
119  *
120  * \param app Application.
121  * \param chan The channel entering the application.
122  * \param argc The number of arguments for the application.
123  * \param argv The arguments for the application.
124  * \return 0 on success.
125  * \return Non-zero on error.
126  */
127 int app_send_start_msg(struct app *app, struct ast_channel *chan, int argc,
128         char *argv[]);
129
130 /*!
131  * \brief Send the end message to an application.
132  *
133  * \param app Application.
134  * \param chan The channel leaving the application.
135  * \return 0 on success.
136  * \return Non-zero on error.
137  */
138 int app_send_end_msg(struct app *app, struct ast_channel *chan);
139
140 /*!
141  * \brief Checks if an application is watching a given channel.
142  *
143  * \param app Application.
144  * \param uniqueid Uniqueid of the channel to check about.
145  * \return True (non-zero) if \a app is watching channel with given \a uniqueid
146  * \return False (zero) if \a app isn't.
147  */
148 int app_is_watching_channel(struct app *app, const char *uniqueid);
149
150 /*!
151  * \brief Add a channel to an application's watch list.
152  *
153  * \param app Application.
154  * \param chan Channel to watch.
155  * \return 0 on success.
156  * \return Non-zero on error.
157  */
158 int app_add_channel(struct app *app, const struct ast_channel *chan);
159
160 /*!
161  * \brief Remove a channel from an application's watch list.
162  *
163  * \param app Application.
164  * \param chan Channel to watch.
165  */
166 void app_remove_channel(struct app *app, const struct ast_channel *chan);
167
168 /*!
169  * \brief Add a bridge to an application's watch list by uniqueid.
170  *
171  * \param app Application.
172  * \param bridge Bridge to watch.
173  * \return 0 on success.
174  * \return Non-zero on error.
175  */
176 int app_add_bridge(struct app *app, const char *uniqueid);
177
178 /*!
179  * \brief Remove a bridge from an application's watch list by uniqueid.
180  *
181  * \param app Application.
182  * \param bridge Bridge to remove.
183  */
184 void app_remove_bridge(struct app* app, const char *uniqueid);
185
186 /*!
187  * \brief Checks if an application is watching a given bridge.
188  *
189  * \param app Application.
190  * \param uniqueid Uniqueid of the bridge to check.
191  * \return True (non-zero) if \a app is watching bridge with given \a uniqueid
192  * \return False (zero) if \a app isn't.
193  */
194 int app_is_watching_bridge(struct app *app, const char *uniqueid);
195
196 #endif /* _ASTERISK_RES_STASIS_APP_H */