Asterisk - The Open Source Telephony Project  21.4.1
control.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_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  * \retval NULL on error.
40  */
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 void control_flush_queue(struct stasis_app_control *control);
50 
51 /*!
52  * \brief set the control's thread id
53  * \since 18
54  *
55  * \param control Control object on which to set the thread id.
56  * \param threadid id to set
57  */
58 void control_set_thread(struct stasis_app_control *control, pthread_t threadid);
59 
60 /*!
61  * \brief Dispatch all commands enqueued to this control.
62  *
63  * \param control Control object to dispatch.
64  * \param chan Associated channel.
65  * \return Number of commands executed
66  */
67 int control_dispatch_all(struct stasis_app_control *control,
68  struct ast_channel *chan);
69 
70 /*!
71  * \brief Blocks until \a control's command queue has a command available.
72  *
73  * \param control Control to block on.
74  */
75 void control_wait(struct stasis_app_control *control);
76 
77 /*!
78  * \brief Returns the count of items in a control's command queue.
79  *
80  * \param control Control to count commands on
81  *
82  * \return number of commands in the command que
83  */
84 int control_command_count(struct stasis_app_control *control);
85 
86 /*!
87  * \brief Returns true if control_continue() has been called on this \a control.
88  *
89  * \param control Control to query.
90  * \retval True (non-zero) if control_continue() has been called.
91  * \retval False (zero) otherwise.
92  */
93 int control_is_done(struct stasis_app_control *control);
94 
95 void control_mark_done(struct stasis_app_control *control);
96 
97 /*!
98  * \brief Dispatch all queued prestart commands
99  *
100  * \param control The control for chan
101  * \param chan The channel on which commands should be executed
102  *
103  * \return The number of commands executed
104  */
106  struct ast_channel *chan);
107 
108 /*!
109  * \brief Returns the pointer (non-reffed) to the app associated with this control
110  *
111  * \param control Control to query.
112  *
113  * \return A pointer to the associated stasis_app
114  */
115 struct stasis_app *control_app(struct stasis_app_control *control);
116 
117 /*!
118  * \brief Set the application the control object belongs to
119  *
120  * \param control The control for the channel
121  * \param app The application this control will now belong to
122  *
123  * \note This will unref control's previous app by 1, and bump app by 1
124  */
125 void control_set_app(struct stasis_app_control *control, struct stasis_app *app);
126 
127 /*!
128  * \brief Returns the name of the application we are moving to
129  *
130  * \param control The control for the channel
131  *
132  * \return The name of the application we are moving to
133  */
134 char *control_next_app(struct stasis_app_control *control);
135 
136 /*!
137  * \brief Free any memory that was allocated for switching applications via
138  * /channels/{channelId}/move
139  *
140  * \param control The control for the channel
141  */
142 void control_move_cleanup(struct stasis_app_control *control);
143 
144 /*!
145  * \brief Returns the list of arguments to pass to the application we are moving to
146  *
147  * \note If you wish to get the size of the list, control_next_app_args_size should be
148  * called before this, as this function will steal the elements from the string vector
149  * and set the size to 0.
150  *
151  * \param control The control for the channel
152  *
153  * \return The arguments to pass to the application we are moving to
154  */
155 char **control_next_app_args(struct stasis_app_control *control);
156 
157 /*!
158  * \brief Returns the number of arguments to be passed to the application we are moving to
159  *
160  * \note This should always be called before control_next_app_args, as calling that function
161  * will steal all elements from the string vector and set the size to 0.
162  *
163  * \param control The control for the channel
164  *
165  * \return The number of arguments to be passed to the application we are moving to
166  */
168 
169 /*!
170  * \brief Command callback for adding a channel to a bridge
171  *
172  * \param control The control for chan
173  * \param chan The channel on which commands should be executed
174  * \param data Bridge to be passed to the callback
175  */
176 int control_add_channel_to_bridge(struct stasis_app_control *control, struct ast_channel *chan, void *data);
177 
178 /*!
179  * \brief Command for swapping a channel in a bridge
180  *
181  * \param control The control for chan
182  * \param chan The channel on which commands should be executed
183  * \param bridge Bridge to be passed to the callback
184  * \param swap Channel to swap with when joining the bridge
185  */
186 int control_swap_channel_in_bridge(struct stasis_app_control *control, struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap);
187 
188 /*!
189  * \brief Stop playing silence to a channel right now.
190  * \since 13.9.0
191  *
192  * \param control The control for chan
193  */
194 void control_silence_stop_now(struct stasis_app_control *control);
195 
196 
197 #endif /* _ASTERISK_RES_STASIS_CONTROL_H */
Main Channel structure associated with a channel.
int control_next_app_args_size(struct stasis_app_control *control)
Returns the number of arguments to be passed to the application we are moving to. ...
Definition: control.c:1737
char * control_next_app(struct stasis_app_control *control)
Returns the name of the application we are moving to.
Definition: control.c:1719
void control_set_app(struct stasis_app_control *control, struct stasis_app *app)
Set the application the control object belongs to.
Definition: control.c:1713
struct stasis_app * app
Definition: control.c:92
struct ast_channel * channel
Definition: control.c:62
int control_is_done(struct stasis_app_control *control)
Returns true if control_continue() has been called on this control.
Definition: control.c:370
int control_command_count(struct stasis_app_control *control)
Returns the count of items in a control's command queue.
Definition: control.c:365
struct stasis_app * control_app(struct stasis_app_control *control)
Returns the pointer (non-reffed) to the app associated with this control.
Definition: control.c:1585
Structure that contains information about a bridge.
Definition: bridge.h:349
int control_add_channel_to_bridge(struct stasis_app_control *control, struct ast_channel *chan, void *data)
Command callback for adding a channel to a bridge.
Definition: control.c:1400
void control_wait(struct stasis_app_control *control)
Blocks until control's command queue has a command available.
Definition: control.c:1537
void control_move_cleanup(struct stasis_app_control *control)
Free any memory that was allocated for switching applications via /channels/{channelId}/move.
Definition: control.c:1724
int control_prestart_dispatch_all(struct stasis_app_control *control, struct ast_channel *chan)
Dispatch all queued prestart commands.
Definition: control.c:1557
int control_swap_channel_in_bridge(struct stasis_app_control *control, struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap)
Command for swapping a channel in a bridge.
Definition: control.c:1306
char ** control_next_app_args(struct stasis_app_control *control)
Returns the list of arguments to pass to the application we are moving to.
Definition: control.c:1732
struct stasis_app_control * control_create(struct ast_channel *channel, struct stasis_app *app)
Create a control object.
Definition: control.c:129
Stasis Application API. See Stasis Application API for detailed documentation.
int control_dispatch_all(struct stasis_app_control *control, struct ast_channel *chan)
Dispatch all commands enqueued to this control.
Definition: control.c:1517
void control_flush_queue(struct stasis_app_control *control)
Flush the control command queue.
Definition: control.c:1504
void control_set_thread(struct stasis_app_control *control, pthread_t threadid)
set the control's thread id
Definition: control.c:196
void control_silence_stop_now(struct stasis_app_control *control)
Stop playing silence to a channel right now.
Definition: control.c:859