Asterisk - The Open Source Telephony Project GIT-master-8924258
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
app_waitforcond.c
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2021, Naveen Albert
5 *
6 * Naveen Albert <asterisk@phreaknet.org>
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 Sleep until a condition is true
22 *
23 * \author Naveen Albert <asterisk@phreaknet.org>
24 *
25 * \ingroup applications
26 */
27
28/*** MODULEINFO
29 <support_level>extended</support_level>
30 ***/
31
32#include "asterisk.h"
33
34#include "asterisk/logger.h"
35#include "asterisk/channel.h"
36#include "asterisk/pbx.h"
37#include "asterisk/module.h"
38#include "asterisk/app.h"
39
40/*** DOCUMENTATION
41 <application name="WaitForCondition" language="en_US">
42 <since>
43 <version>16.20.0</version>
44 <version>18.6.0</version>
45 </since>
46 <synopsis>
47 Wait (sleep) until the given condition is true.
48 </synopsis>
49 <syntax>
50 <parameter name="replacementchar" required="true">
51 <para>Specifies the character in the expression used to replace the <literal>$</literal>
52 character. This character should not be used anywhere in the expression itself.</para>
53 </parameter>
54 <parameter name="expression" required="true">
55 <para>A modified logical expression with the <literal>$</literal> characters replaced by
56 <replaceable>replacementchar</replaceable>. This is necessary to pass the expression itself
57 into the application, rather than its initial evaluation.</para>
58 </parameter>
59 <parameter name="timeout">
60 <para>The maximum amount of time, in seconds, this application should wait for a condition
61 to become true before dialplan execution continues automatically to the next priority.
62 By default, there is no timeout.</para>
63 </parameter>
64 <parameter name="interval">
65 <para>The frequency, in seconds, of polling the condition, which can be adjusted depending
66 on how time-sensitive execution needs to be. By default, this is 0.05.</para>
67 </parameter>
68 </syntax>
69 <description>
70 <para>Waits until <replaceable>expression</replaceable> evaluates to true, checking every
71 <replaceable>interval</replaceable> seconds for up to <replaceable>timeout</replaceable>. Default
72 is evaluate <replaceable>expression</replaceable> every 50 milliseconds with no timeout.</para>
73 <example title="Wait for condition dialplan variable/function to become 1 for up to 40 seconds, checking every 500ms">
74 same => n,WaitForCondition(#,#["#{condition}"="1"],40,0.5)
75 </example>
76 <para>Sets <variable>WAITFORCONDITIONSTATUS</variable> to one of the following values:</para>
77 <variablelist>
78 <variable name="WAITFORCONDITIONSTATUS">
79 <value name="TRUE">
80 Condition evaluated to true before timeout expired.
81 </value>
82 <value name="FAILURE">
83 Invalid argument.
84 </value>
85 <value name="TIMEOUT">
86 Timeout elapsed without condition evaluating to true.
87 </value>
88 <value name="HANGUP">
89 Channel hung up before condition became true.
90 </value>
91 </variable>
92 </variablelist>
93 </description>
94 </application>
95 ***/
96
97static char *app = "WaitForCondition";
98
99static int waitforcond_exec(struct ast_channel *chan, const char *data)
100{
101 int ms, i;
102 double timeout = 0, poll = 0;
103 int timeout_ms = 0;
104 int poll_ms = 50; /* default is evaluate the condition every 50ms */
105 struct timeval start = ast_tvnow();
106 char dollarsignrep;
107 int brackets = 0;
108 char *pos, *open_bracket, *expression, *optargs = NULL;
109 char condition[512];
110
112 AST_APP_ARG(timeout);
113 AST_APP_ARG(interval);
114 );
115
116 pos = ast_strdupa(data);
117
118 if (ast_strlen_zero(pos)) {
119 ast_log(LOG_ERROR, "WaitForCondition requires a condition\n");
120 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
121 return 0;
122 }
123
124 /* is there at least a [ followed by a ] somewhere ? */
125 if (!(open_bracket = strchr(pos, '[')) || !strchr(open_bracket, ']')) {
126 ast_log(LOG_ERROR, "No expression detected. Did you forget to replace the $ signs?\n");
127 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
128 return 0;
129 }
130
131 dollarsignrep = pos[0];
132 if (dollarsignrep == '$' || dollarsignrep == '[' || dollarsignrep == ']'
133 || dollarsignrep == '{' || dollarsignrep == '}') {
134 ast_log(LOG_ERROR, "Dollar sign replacement cannot be %c.\n", dollarsignrep);
135 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
136 return 0;
137 }
138 ++pos;
139 if (pos[0] != ',') {
140 ast_log(LOG_ERROR, "Invalid separator: %c\n", pos[0]);
141 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
142 return 0;
143 }
144 ++pos;
145 if (pos[0] != dollarsignrep) {
146 ast_log(LOG_ERROR, "Expression start does not match provided replacement: %c\n", pos[0]);
147 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
148 return 0;
149 }
150
151 expression = pos; /* we're at the start of the expression */
152
153 /* commas may appear within the expression, so go until we've encountered as many closing brackets as opening */
154 while (++pos) {
155 if (pos[0] == '\0') {
156 ast_log(LOG_ERROR, "Could not parse end of expression.\n");
157 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "FAILURE");
158 return 0;
159 }
160 if (pos[0] == '[') {
161 brackets++;
162 } else if (pos[0] == ']') {
163 brackets--;
164 }
165 if (brackets == 0) { /* reached end of expression */
166 break;
167 }
168 }
169 ++pos;
170 if (pos[0] != '\0') {
171 ++pos; /* eat comma separator */
172 if (pos[0] != '\0') {
173 optargs = ast_strdupa(pos);
174 AST_STANDARD_APP_ARGS(args, optargs);
175 if (!ast_strlen_zero(args.timeout)) {
176 if (sscanf(args.timeout, "%30lg", &timeout) != 1) {
177 ast_log(LOG_WARNING, "Invalid timeout provided: %s. No timeout set.\n", args.timeout);
178 return -1;
179 }
180 timeout_ms = timeout * 1000.0;
181 }
182
183 if (!ast_strlen_zero(args.interval)) {
184 if (sscanf(args.interval, "%30lg", &poll) != 1) {
185 ast_log(LOG_WARNING, "Invalid polling interval provided: %s. Default unchanged.\n", args.interval);
186 return -1;
187 }
188 if (poll < 0.001) {
189 ast_log(LOG_WARNING, "Polling interval cannot be less than 1ms. Default unchanged.\n");
190 return -1;
191 }
192 poll_ms = poll * 1000.0;
193 }
194 }
195 }
196
197 for (i = 0; expression[i] != '\0'; i++) {
198 if (expression[i] == dollarsignrep) {
199 expression[i] = '$'; /* replace $s back into expression for variable parsing */
200 }
201 }
202
203 if (timeout_ms > 0) {
204 ast_debug(1, "Waiting for condition for %f seconds: %s (checking every %d ms)", timeout, expression, poll_ms);
205 } else {
206 ast_debug(1, "Waiting for condition, forever: %s (checking every %d ms)", expression, poll_ms);
207 }
208
209 while (1) {
210 /* Substitute variables now */
211 pbx_substitute_variables_helper(chan, expression, condition, sizeof(condition) - 1);
212 if (pbx_checkcondition(condition)) {
213 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "TRUE");
214 return 0;
215 }
216 /* If a timeout was specified, check that it hasn't expired */
217 if ((timeout_ms > 0) && !(ms = ast_remaining_ms(start, timeout_ms))) {
218 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "TIMEOUT");
219 return 0;
220 }
221 if (ast_safe_sleep(chan, poll_ms)) { /* don't waste CPU, we don't need a super tight loop */
222 pbx_builtin_setvar_helper(chan, "WAITFORCONDITIONSTATUS", "HANGUP");
223 return -1; /* channel hung up */
224 }
225 }
226}
227
228static int unload_module(void)
229{
231}
232
233static int load_module(void)
234{
236}
237
AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Wait until condition is true")
static char * app
static int waitforcond_exec(struct ast_channel *chan, const char *data)
static int load_module(void)
static int unload_module(void)
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
General Asterisk PBX channel definitions.
int ast_safe_sleep(struct ast_channel *chan, int ms)
Wait for a specified amount of time, looking for hangups.
Definition: channel.c:1601
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.
Support for logging to various files, console and syslog Configuration in file logger....
#define ast_debug(level,...)
Log a DEBUG message.
#define LOG_ERROR
#define LOG_WARNING
Asterisk module definitions.
#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.
int pbx_checkcondition(const char *condition)
Evaluate a condition.
Definition: pbx.c:8297
void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count)
Definition: ael_main.c:211
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
Main Channel structure associated with a channel.
const char * args
int ast_remaining_ms(struct timeval start, int max_ms)
Calculate remaining milliseconds given a starting timestamp and upper bound.
Definition: utils.c:2281
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159