Asterisk - The Open Source Telephony Project  21.4.1
stasis_app_impl.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_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  * This is called during destruction of the command or if we fail to schedule
55  * a command. It is passed a pointer to the user-defined data of the command.
56  *
57  * \param data Data to destroy.
58  */
59 typedef void (*command_data_destructor_fn)(void *data);
60 
61 /*! Callback type for stasis app commands */
62 typedef int (*stasis_app_command_cb)(struct stasis_app_control *control,
63  struct ast_channel *chan, void *data);
64 
65 /*!
66  * \since 12
67  * \brief Invokes a \a command on a \a control's channel.
68  *
69  * This function dispatches the command to be executed in the context of
70  * stasis_app_exec(), so this command will block waiting for the results of
71  * the command.
72  *
73  * \param control Control object for the channel to send the command to.
74  * \param command Command function to execute.
75  * \param data Optional data to pass along with the control function.
76  * \param data_destructor Optional function which will be called on
77  * the data in either the event of command completion or failure
78  * to schedule or complete the command
79  *
80  * \return zero on success.
81  * \return error code otherwise.
82  */
84  stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor);
85 
86 /*!
87  * \since 12
88  * \brief Asynchronous version of stasis_app_send_command().
89  *
90  * This function enqueues a command for execution, but returns immediately
91  * without waiting for the response.
92  *
93  * \param control Control object for the channel to send the command to.
94  * \param command Command function to execute.
95  * \param data Optional data to pass along with the control function.
96  * \param data_destructor Optional function which will be called on
97  * the data in either the event of command completion or failure
98  * to schedule or complete the command
99  * \return 0 on success.
100  * \return Non-zero on error.
101  */
103  stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor);
104 
105 #endif /* _ASTERISK_RES_STASIS_H */
Main Channel structure associated with a channel.
int stasis_app_send_command(struct stasis_app_control *control, stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor)
Invokes a command on a control's channel.
Definition: control.c:920
int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc, char *argv[])
Control a channel using stasis_app.
Definition: res_stasis.c:1327
const char * data
int(* stasis_app_command_cb)(struct stasis_app_control *control, struct ast_channel *chan, void *data)
int stasis_app_send_command_async(struct stasis_app_control *control, stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor)
Asynchronous version of stasis_app_send_command().
Definition: control.c:926
void(* command_data_destructor_fn)(void *data)
Typedef for data destructor for stasis app commands.
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
Stasis Application API. See Stasis Application API for detailed documentation.