ARI: Fix a crash caused by hanging during playback to a channel in a bridge
[asterisk/asterisk.git] / include / asterisk / stasis_app_impl.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_H
20 #define _ASTERISK_RES_STASIS_H
21
22 /*! \file
23  *
24  * \brief Backend API for implementing components of res_stasis.
25  *
26  * \author David M. Lee, II <dlee@digium.com>
27  * \since 12
28  *
29  * This file defines functions useful for defining new commands to execute
30  * on channels while they are in Stasis.
31  */
32
33 #include "asterisk/stasis_app.h"
34
35 /*!
36  * \since 12
37  * \brief Control a channel using \c stasis_app.
38  *
39  * This function blocks until the channel hangs up, or
40  * stasis_app_control_continue() is called on the channel's \ref
41  * stasis_app_control struct.
42  *
43  * \param chan Channel to control with Stasis.
44  * \param app_name Application controlling the channel.
45  * \param argc Number of arguments for the application.
46  * \param argv Arguments for the application.
47  */
48 int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc,
49         char *argv[]);
50
51 /*!
52  * \brief Typedef for data destructor for stasis app commands
53  *
54  * \param data Data to destroy.
55  *
56  * \details
57  * This is called during destruction of the command or if we fail to schedule
58  * a command. It is passed a pointer to the user-defined data of the command.
59  *
60  * \return Nothing
61  */
62 typedef void (*command_data_destructor_fn)(void *data);
63
64 /*! Callback type for stasis app commands */
65 typedef int (*stasis_app_command_cb)(struct stasis_app_control *control,
66         struct ast_channel *chan, void *data);
67
68 /*!
69  * \since 12
70  * \brief Invokes a \a command on a \a control's channel.
71  *
72  * This function dispatches the command to be executed in the context of
73  * stasis_app_exec(), so this command will block waiting for the results of
74  * the command.
75  *
76  * \param control Control object for the channel to send the command to.
77  * \param command Command function to execute.
78  * \param data Optional data to pass along with the control function.
79  * \param data_destructor Optional function which will be called on
80  *        the data in either the event of command completion or failure
81  *        to schedule or complete the command
82  *
83  * \return zero on success.
84  * \return error code otherwise.
85  */
86 int stasis_app_send_command(struct stasis_app_control *control,
87         stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor);
88
89 /*!
90  * \since 12
91  * \brief Asynchronous version of stasis_app_send_command().
92  *
93  * This function enqueues a command for execution, but returns immediately
94  * without waiting for the response.
95  *
96  * \param control Control object for the channel to send the command to.
97  * \param command Command function to execute.
98  * \param data Optional data to pass along with the control function.
99  * \param data_destructor Optional function which will be called on
100  *        the data in either the event of command completion or failure
101  *        to schedule or complete the command
102  * \return 0 on success.
103  * \return Non-zero on error.
104  */
105 int stasis_app_send_command_async(struct stasis_app_control *control,
106         stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor);
107
108 #endif /* _ASTERISK_RES_STASIS_H */