Asterisk - The Open Source Telephony Project GIT-master-5963e62
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
app_stasis.c
Go to the documentation of this file.
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 <depend>res_ari</depend>
29 <support_level>core</support_level>
30 ***/
31
32#include "asterisk.h"
33
34#include "asterisk/app.h"
35#include "asterisk/ari.h"
36#include "asterisk/module.h"
37#include "asterisk/pbx.h"
38#include "asterisk/stasis.h"
40
41/*** DOCUMENTATION
42 <application name="Stasis" language="en_US">
43 <since>
44 <version>12.0.0</version>
45 </since>
46 <synopsis>Invoke an external Stasis application.</synopsis>
47 <syntax>
48 <parameter name="app_name" required="true">
49 <para>Name of the application to invoke.</para>
50 </parameter>
51 <parameter name="args">
52 <para>Optional comma-delimited arguments for the
53 application invocation.</para>
54 </parameter>
55 </syntax>
56 <description>
57 <para>Invoke a Stasis application.</para>
58 <para>This application will set the following channel variable upon
59 completion:</para>
60 <variablelist>
61 <variable name="STASISSTATUS">
62 <para>This indicates the status of the execution of the
63 Stasis application.</para>
64 <value name="SUCCESS">
65 The channel has exited Stasis without any failures in
66 Stasis.
67 </value>
68 <value name="FAILED">
69 A failure occurred when executing the Stasis
70 The app registry is not instantiated; The app
71 application. Some (not all) possible reasons for this:
72 requested is not registered; The app requested is not
73 active; Stasis couldn't send a start message.
74 </value>
75 </variable>
76 </variablelist>
77 </description>
78 </application>
79 ***/
80
81/*! \brief Maximum number of arguments for the Stasis dialplan application */
82#define MAX_ARGS 128
83
84/*! \brief Dialplan application name */
85static const char *stasis = "Stasis";
86
87/*! \brief Stasis dialplan application callback */
88static int app_exec(struct ast_channel *chan, const char *data)
89{
90 char *parse = NULL;
91 char *connection_id;
92 int ret = -1;
93
96 AST_APP_ARG(app_argv)[MAX_ARGS];
97 );
98
99 ast_assert(chan != NULL);
100 ast_assert(data != NULL);
101
102 pbx_builtin_setvar_helper(chan, "STASISSTATUS", "");
103
104 /* parse the arguments */
105 parse = ast_strdupa(data);
107
108 if (args.argc < 1) {
109 ast_log(LOG_WARNING, "Stasis app_name argument missing\n");
110 goto done;
111 }
112
113 if (stasis_app_is_registered(args.app_name)) {
114 ast_debug(3, "%s: App '%s' is already registered\n",
115 ast_channel_name(chan), args.app_name);
116 ret = stasis_app_exec(chan, args.app_name, args.argc - 1, args.app_argv);
117 goto done;
118 }
119 ast_debug(3, "%s: App '%s' is NOT already registered\n",
120 ast_channel_name(chan), args.app_name);
121
122 /*
123 * The app isn't registered so we need to see if we have a
124 * per-call outbound websocket config we can use.
125 * connection_id will be freed by ast_ari_close_per_call_websocket().
126 */
127 connection_id = ast_ari_create_per_call_websocket(args.app_name, chan);
128 if (ast_strlen_zero(connection_id)) {
130 "%s: Stasis app '%s' doesn't exist\n",
131 ast_channel_name(chan), args.app_name);
132 goto done;
133 }
134
135 ret = stasis_app_exec(chan, connection_id, args.argc - 1, args.app_argv);
137
138done:
139 if (ret) {
140 /* set ret to 0 so pbx_core doesnt hangup the channel */
141 if (!ast_check_hangup(chan)) {
142 ret = 0;
143 } else {
144 ret = -1;
145 }
146 pbx_builtin_setvar_helper(chan, "STASISSTATUS", "FAILED");
147 } else {
148 pbx_builtin_setvar_helper(chan, "STASISSTATUS", "SUCCESS");
149 }
150
151 return ret;
152}
153
154static int load_module(void)
155{
157}
158
159static int unload_module(void)
160{
162}
163
164AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Stasis dialplan application",
165 .support_level = AST_MODULE_SUPPORT_CORE,
166 .load = load_module,
167 .unload = unload_module,
168 .requires = "res_stasis,res_ari",
#define MAX_ARGS
Maximum number of arguments for the Stasis dialplan application.
Definition: app_stasis.c:82
static const char * stasis
Dialplan application name.
Definition: app_stasis.c:85
static int app_exec(struct ast_channel *chan, const char *data)
Stasis dialplan application callback.
Definition: app_stasis.c:88
static int load_module(void)
Definition: app_stasis.c:154
static int unload_module(void)
Definition: app_stasis.c:159
Asterisk RESTful API hooks.
char * ast_ari_create_per_call_websocket(const char *app_name, struct ast_channel *channel)
Create a per-call outbound websocket connection.
void ast_ari_close_per_call_websocket(char *app_id)
Close a per-call outbound websocket connection.
Asterisk main include file. File version handling, generic pbx functions.
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define ast_log
Definition: astobj2.c:42
const char * ast_channel_name(const struct ast_channel *chan)
int ast_check_hangup(struct ast_channel *chan)
Check to see if a channel is needing hang up.
Definition: channel.c:444
Application convenience functions, designed to give consistent look and feel to Asterisk apps.
#define AST_APP_ARG(name)
Define an application argument.
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application's arguments.
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
#define ast_debug(level,...)
Log a DEBUG message.
#define LOG_WARNING
Asterisk module definitions.
@ AST_MODFLAG_DEFAULT
Definition: module.h:329
#define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)
Definition: module.h:557
@ AST_MODULE_SUPPORT_CORE
Definition: module.h:121
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx_app.c:392
#define ast_register_application_xml(app, execute)
Register an application using XML documentation.
Definition: module.h:640
Core PBX routines and definitions.
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name.
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
#define NULL
Definition: resample.c:96
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
int stasis_app_is_registered(const char *name)
Check if a Stasis application is registered.
Definition: res_stasis.c:1747
Backend API for implementing components of res_stasis.
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:1369
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
Main Channel structure associated with a channel.
int done
Definition: test_amihooks.c:48
const char * args
#define ast_assert(a)
Definition: utils.h:745