d4b467756427dd9da6a8dbe68860bb0c5814705e
[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 /*! Callback type for stasis app commands */
52 typedef void *(*stasis_app_command_cb)(struct stasis_app_control *control,
53         struct ast_channel *chan, void *data);
54
55 /*!
56  * \since 12
57  * \brief Invokes a \a command on a \a control's channel.
58  *
59  * This function dispatches the command to be executed in the context of
60  * stasis_app_exec(), so this command will block waiting for the results of
61  * the command.
62  *
63  * \param control Control object for the channel to send the command to.
64  * \param command Command function to execute.
65  * \param data Optional data to pass along with the control function.
66  * \return Return value from \a command.
67  * \return \c NULL on error.
68  */
69 void *stasis_app_send_command(struct stasis_app_control *control,
70         stasis_app_command_cb command, void *data);
71
72 /*!
73  * \since 12
74  * \brief Asynchronous version of stasis_app_send().
75  *
76  * This function enqueues a command for execution, but returns immediately
77  * without waiting for the response.
78  *
79  * \param control Control object for the channel to send the command to.
80  * \param command Command function to execute.
81  * \param data Optional data to pass along with the control function.
82  * \return 0 on success.
83  * \return Non-zero on error.
84  */
85 int stasis_app_send_command_async(struct stasis_app_control *control,
86         stasis_app_command_cb command, void *data);
87
88 #endif /* _ASTERISK_RES_STASIS_H */