res_stasis: Add ability to switch applications.
[asterisk/asterisk.git] / res / stasis / control.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_CONTROL_H
20 #define _ASTERISK_RES_STASIS_CONTROL_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/stasis_app.h"
31
32 /*!
33  * \brief Create a control object.
34  *
35  * \param channel Channel to control.
36  * \param app stasis_app for which this control is being created.
37  *
38  * \return New control object.
39  * \return \c NULL on error.
40  */
41 struct stasis_app_control *control_create(struct ast_channel *channel, struct stasis_app *app);
42
43 /*!
44  * \brief Flush the control command queue.
45  * \since 13.9.0
46  *
47  * \param control Control object to flush command queue.
48  *
49  * \return Nothing
50  */
51 void control_flush_queue(struct stasis_app_control *control);
52
53 /*!
54  * \brief Dispatch all commands enqueued to this control.
55  *
56  * \param control Control object to dispatch.
57  * \param chan Associated channel.
58  * \return Number of commands executed
59  */
60 int control_dispatch_all(struct stasis_app_control *control,
61         struct ast_channel *chan);
62
63 /*!
64  * \brief Blocks until \a control's command queue has a command available.
65  *
66  * \param control Control to block on.
67  */
68 void control_wait(struct stasis_app_control *control);
69
70 /*!
71  * \brief Returns the count of items in a control's command queue.
72  *
73  * \param control Control to count commands on
74  *
75  * \retval number of commands in the command que
76  */
77 int control_command_count(struct stasis_app_control *control);
78
79 /*!
80  * \brief Returns true if control_continue() has been called on this \a control.
81  *
82  * \param control Control to query.
83  * \return True (non-zero) if control_continue() has been called.
84  * \return False (zero) otherwise.
85  */
86 int control_is_done(struct stasis_app_control *control);
87
88 void control_mark_done(struct stasis_app_control *control);
89
90 /*!
91  * \brief Dispatch all queued prestart commands
92  *
93  * \param control The control for chan
94  * \param channel The channel on which commands should be executed
95  *
96  * \return The number of commands executed
97  */
98 int control_prestart_dispatch_all(struct stasis_app_control *control,
99         struct ast_channel *chan);
100
101 /*!
102  * \brief Returns the pointer (non-reffed) to the app associated with this control
103  *
104  * \param control Control to query.
105  *
106  * \returns A pointer to the associated stasis_app
107  */
108 struct stasis_app *control_app(struct stasis_app_control *control);
109
110 /*!
111  * \brief Set the application the control object belongs to
112  *
113  * \param control The control for the channel
114  * \param app The application this control will now belong to
115  *
116  * \note This will unref control's previous app by 1, and bump app by 1
117  */
118 void control_set_app(struct stasis_app_control *control, struct stasis_app *app);
119
120 /*!
121  * \brief Returns the name of the application we are moving to
122  *
123  * \param control The control for the channel
124  *
125  * \return The name of the application we are moving to
126  */
127 char *control_next_app(struct stasis_app_control *control);
128
129 /*!
130  * \brief Free any memory that was allocated for switching applications via
131  * /channels/{channelId}/move
132  *
133  * \param control The control for the channel
134  */
135 void control_move_cleanup(struct stasis_app_control *control);
136
137 /*!
138  * \brief Returns the list of arguments to pass to the application we are moving to
139  *
140  * \note If you wish to get the size of the list, control_next_app_args_size should be
141  * called before this, as this function will steal the elements from the string vector
142  * and set the size to 0.
143  *
144  * \param control The control for the channel
145  *
146  * \return The arguments to pass to the application we are moving to
147  */
148 char **control_next_app_args(struct stasis_app_control *control);
149
150 /*!
151  * \brief Returns the number of arguments to be passed to the application we are moving to
152  *
153  * \note This should always be called before control_next_app_args, as calling that function
154  * will steal all elements from the string vector and set the size to 0.
155  *
156  * \param control The control for the channel
157  *
158  * \return The number of arguments to be passed to the application we are moving to
159  */
160 int control_next_app_args_size(struct stasis_app_control *control);
161
162 /*!
163  * \brief Command callback for adding a channel to a bridge
164  *
165  * \param control The control for chan
166  * \param chan The channel on which commands should be executed
167  * \param data Bridge to be passed to the callback
168  */
169 int control_add_channel_to_bridge(struct stasis_app_control *control, struct ast_channel *chan, void *data);
170
171 /*!
172  * \brief Command for swapping a channel in a bridge
173  *
174  * \param control The control for chan
175  * \param chan The channel on which commands should be executed
176  * \param bridge Bridge to be passed to the callback
177  * \param swap Channel to swap with when joining the bridge
178  */
179 int control_swap_channel_in_bridge(struct stasis_app_control *control, struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap);
180
181 /*!
182  * \brief Stop playing silence to a channel right now.
183  * \since 13.9.0
184  *
185  * \param control The control for chan
186  */
187 void control_silence_stop_now(struct stasis_app_control *control);
188
189
190 #endif /* _ASTERISK_RES_STASIS_CONTROL_H */