git migration: Refactor the ASTERISK_FILE_VERSION macro
[asterisk/asterisk.git] / apps / app_stasis.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012 - 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 /*! \file
20  *
21  * \brief Stasis dialplan application.
22  *
23  * \author David M. Lee, II <dlee@digium.com>
24  */
25
26 /*** MODULEINFO
27         <depend>res_stasis</depend>
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 ASTERISK_REGISTER_FILE()
34
35 #include "asterisk/app.h"
36 #include "asterisk/module.h"
37 #include "asterisk/pbx.h"
38 #include "asterisk/stasis.h"
39 #include "asterisk/stasis_app_impl.h"
40
41 /*** DOCUMENTATION
42         <application name="Stasis" language="en_US">
43                 <synopsis>Invoke an external Stasis application.</synopsis>
44                 <syntax>
45                         <parameter name="app_name" required="true">
46                                 <para>Name of the application to invoke.</para>
47                         </parameter>
48                         <parameter name="args">
49                                 <para>Optional comma-delimited arguments for the
50                                 application invocation.</para>
51                         </parameter>
52                 </syntax>
53                 <description>
54                         <para>Invoke a Stasis application.</para>
55                         <para>This application will set the following channel variable upon
56                         completion:</para>
57                         <variablelist>
58                                 <variable name="STASISSTATUS">
59                                         <para>This indicates the status of the execution of the
60                                         Stasis application.</para>
61                                         <value name="SUCCESS">
62                                                 The channel has exited Stasis without any failures in
63                                                 Stasis.
64                                         </value>
65                                         <value name="FAILED">
66                                                 A failure occurred when executing the Stasis
67                                                 The app registry is not instantiated; The app
68                                                 application. Some (not all) possible reasons for this:
69                                                 requested is not registered; The app requested is not
70                                                 active; Stasis couldn't send a start message.
71                                         </value>
72                                 </variable>
73                         </variablelist>
74                 </description>
75         </application>
76  ***/
77
78 /*! \brief Maximum number of arguments for the Stasis dialplan application */
79 #define MAX_ARGS 128
80
81 /*! \brief Dialplan application name */
82 static const char *stasis = "Stasis";
83
84 /*! /brief Stasis dialplan application callback */
85 static int app_exec(struct ast_channel *chan, const char *data)
86 {
87         char *parse = NULL;
88         int ret = -1;
89
90         AST_DECLARE_APP_ARGS(args,
91                 AST_APP_ARG(app_name);
92                 AST_APP_ARG(app_argv)[MAX_ARGS];
93         );
94
95         ast_assert(chan != NULL);
96         ast_assert(data != NULL);
97
98         pbx_builtin_setvar_helper(chan, "STASISSTATUS", "");
99
100         /* parse the arguments */
101         parse = ast_strdupa(data);
102         AST_STANDARD_APP_ARGS(args, parse);
103
104         if (args.argc < 1) {
105                 ast_log(LOG_WARNING, "Stasis app_name argument missing\n");
106         } else {
107                 ret = stasis_app_exec(chan,
108                                       args.app_name,
109                                       args.argc - 1,
110                                       args.app_argv);
111         }
112
113         if (ret == -1) {
114             pbx_builtin_setvar_helper(chan, "STASISSTATUS", "FAILED");
115         } else {
116             pbx_builtin_setvar_helper(chan, "STASISSTATUS", "SUCCESS");
117         }
118
119         return ret;
120 }
121
122 static int load_module(void)
123 {
124         int r = 0;
125
126         stasis_app_ref();
127         r |= ast_register_application_xml(stasis, app_exec);
128         return r;
129 }
130
131 static int unload_module(void)
132 {
133         int r = 0;
134         r |= ast_unregister_application(stasis);
135         stasis_app_unref();
136         return r;
137 }
138
139 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Stasis dialplan application",
140         .support_level = AST_MODULE_SUPPORT_CORE,
141         .load = load_module,
142         .unload = unload_module,
143         .nonoptreq = "res_stasis",
144         );