335 lines
9.9 KiB
C
335 lines
9.9 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 1999 - 2005, Digium, Inc.
|
|
*
|
|
* Mark Spencer <markster@digium.com>
|
|
*
|
|
* See http://www.asterisk.org for more information about
|
|
* the Asterisk project. Please do not directly contact
|
|
* any of the maintainers of this project for assistance;
|
|
* the project provides a web site, mailing lists and IRC
|
|
* channels for your use.
|
|
*
|
|
* This program is free software, distributed under the terms of
|
|
* the GNU General Public License Version 2. See the LICENSE file
|
|
* at the top of the source tree.
|
|
*/
|
|
|
|
/*! \file
|
|
*
|
|
* \brief Trivial application to read a variable
|
|
*
|
|
* \author Mark Spencer <markster@digium.com>
|
|
*
|
|
* \ingroup applications
|
|
*/
|
|
|
|
/*** MODULEINFO
|
|
<support_level>core</support_level>
|
|
***/
|
|
|
|
#include "asterisk.h"
|
|
|
|
#include "asterisk/file.h"
|
|
#include "asterisk/pbx.h"
|
|
#include "asterisk/channel.h"
|
|
#include "asterisk/app.h"
|
|
#include "asterisk/module.h"
|
|
#include "asterisk/indications.h"
|
|
|
|
/*** DOCUMENTATION
|
|
<application name="Read" language="en_US">
|
|
<synopsis>
|
|
Read a variable.
|
|
</synopsis>
|
|
<syntax>
|
|
<parameter name="variable" required="true">
|
|
<para>The input digits will be stored in the given <replaceable>variable</replaceable>
|
|
name.</para>
|
|
</parameter>
|
|
<parameter name="filenames" argsep="&">
|
|
<para>Ampersand separated list of filenames to play before
|
|
reading digits or tone with option <literal>i</literal>. If
|
|
the filename is a relative filename (it does not begin with a
|
|
slash), it will be searched for in the Asterisk sounds
|
|
directory. If the filename is able to be parsed as a URL,
|
|
Asterisk will download the file and then begin playback on
|
|
it. To include a literal <literal>&</literal> in the URL
|
|
you can enclose the URL in single quotes.</para>
|
|
<argument name="filename" required="true" />
|
|
<argument name="filename2" multiple="true" />
|
|
</parameter>
|
|
<parameter name="maxdigits">
|
|
<para>Maximum acceptable number of digits. Stops reading after
|
|
<replaceable>maxdigits</replaceable> have been entered (without
|
|
requiring the user to press the <literal>#</literal> key).</para>
|
|
<para>Defaults to <literal>0</literal> - no limit - wait for the
|
|
user press the <literal>#</literal> key. Any value below
|
|
<literal>0</literal> means the same. Max accepted value is
|
|
<literal>255</literal>.</para>
|
|
</parameter>
|
|
<parameter name="options">
|
|
<optionlist>
|
|
<option name="s">
|
|
<para>to return immediately if the line is not up.</para>
|
|
</option>
|
|
<option name="i">
|
|
<para>to play filename as an indication tone from your
|
|
<filename>indications.conf</filename>.</para>
|
|
</option>
|
|
<option name="n">
|
|
<para>to read digits even if the line is not up.</para>
|
|
</option>
|
|
<option name="t">
|
|
<para>Terminator digit(s) to use for ending input.
|
|
Default is <literal>#</literal>. If you need to read
|
|
the digit <literal>#</literal> literally, you should
|
|
remove or change the terminator character. Multiple
|
|
terminator characters may be specified. If no terminator
|
|
digit is present, input cannot be ended using digits
|
|
and you will need to rely on duration and max digits
|
|
for ending input.</para>
|
|
</option>
|
|
<option name="e">
|
|
<para>to read the terminator as the digit string if the
|
|
only digit read is the terminator. This is for cases
|
|
where the terminator is a valid digit, but only by itself.
|
|
ie; <literal>1234</literal> and <literal>#</literal> are
|
|
valid, but <literal>1234#</literal> is not.</para>
|
|
</option>
|
|
</optionlist>
|
|
</parameter>
|
|
<parameter name="attempts">
|
|
<para>If greater than <literal>1</literal>, that many
|
|
<replaceable>attempts</replaceable> will be made in the
|
|
event no data is entered.</para>
|
|
</parameter>
|
|
<parameter name="timeout">
|
|
<para>The number of seconds to wait for a digit response. If greater
|
|
than <literal>0</literal>, that value will override the default timeout.
|
|
Can be floating point.</para>
|
|
</parameter>
|
|
</syntax>
|
|
<description>
|
|
<para>Reads a #-terminated string of digits a certain number of times from the
|
|
user in to the given <replaceable>variable</replaceable>.</para>
|
|
<para>This application sets the following channel variable upon completion:</para>
|
|
<variablelist>
|
|
<variable name="READSTATUS">
|
|
<para>This is the status of the read operation.</para>
|
|
<value name="OK" />
|
|
<value name="ERROR" />
|
|
<value name="HANGUP" />
|
|
<value name="INTERRUPTED" />
|
|
<value name="SKIPPED" />
|
|
<value name="TIMEOUT" />
|
|
</variable>
|
|
</variablelist>
|
|
</description>
|
|
<see-also>
|
|
<ref type="application">SendDTMF</ref>
|
|
</see-also>
|
|
</application>
|
|
***/
|
|
|
|
enum read_option_flags {
|
|
OPT_SKIP = (1 << 0),
|
|
OPT_INDICATION = (1 << 1),
|
|
OPT_NOANSWER = (1 << 2),
|
|
OPT_TERMINATOR = (1 << 3),
|
|
OPT_KEEP_TERMINATOR = (1 << 4),
|
|
};
|
|
|
|
enum {
|
|
OPT_ARG_TERMINATOR,
|
|
/* note: this entry _MUST_ be the last one in the enum */
|
|
OPT_ARG_ARRAY_SIZE,
|
|
};
|
|
|
|
AST_APP_OPTIONS(read_app_options, {
|
|
AST_APP_OPTION('s', OPT_SKIP),
|
|
AST_APP_OPTION('i', OPT_INDICATION),
|
|
AST_APP_OPTION('n', OPT_NOANSWER),
|
|
AST_APP_OPTION_ARG('t', OPT_TERMINATOR, OPT_ARG_TERMINATOR),
|
|
AST_APP_OPTION('e', OPT_KEEP_TERMINATOR),
|
|
});
|
|
|
|
static char *app = "Read";
|
|
|
|
static int read_exec(struct ast_channel *chan, const char *data)
|
|
{
|
|
int res = 0;
|
|
char tmp[256] = "";
|
|
int maxdigits = 255;
|
|
int tries = 1, to = 0, x = 0;
|
|
double tosec;
|
|
char *argcopy = NULL;
|
|
char *opt_args[OPT_ARG_ARRAY_SIZE];
|
|
struct ast_tone_zone_sound *ts = NULL;
|
|
struct ast_flags flags = {0};
|
|
const char *status = "ERROR";
|
|
char *terminator = "#"; /* use default terminator # by default */
|
|
|
|
AST_DECLARE_APP_ARGS(arglist,
|
|
AST_APP_ARG(variable);
|
|
AST_APP_ARG(filename);
|
|
AST_APP_ARG(maxdigits);
|
|
AST_APP_ARG(options);
|
|
AST_APP_ARG(attempts);
|
|
AST_APP_ARG(timeout);
|
|
);
|
|
|
|
pbx_builtin_setvar_helper(chan, "READSTATUS", status);
|
|
if (ast_strlen_zero(data)) {
|
|
ast_log(LOG_WARNING, "Read requires an argument (variable)\n");
|
|
return 0;
|
|
}
|
|
|
|
argcopy = ast_strdupa(data);
|
|
|
|
AST_STANDARD_APP_ARGS(arglist, argcopy);
|
|
|
|
if (!ast_strlen_zero(arglist.options)) {
|
|
ast_app_parse_options(read_app_options, &flags, opt_args, arglist.options);
|
|
}
|
|
|
|
if (!ast_strlen_zero(arglist.attempts)) {
|
|
tries = atoi(arglist.attempts);
|
|
if (tries <= 0)
|
|
tries = 1;
|
|
}
|
|
|
|
if (!ast_strlen_zero(arglist.timeout)) {
|
|
tosec = atof(arglist.timeout);
|
|
if (tosec <= 0)
|
|
to = 0;
|
|
else
|
|
to = tosec * 1000.0;
|
|
}
|
|
|
|
if (ast_strlen_zero(arglist.filename)) {
|
|
arglist.filename = NULL;
|
|
}
|
|
if (!ast_strlen_zero(arglist.maxdigits)) {
|
|
maxdigits = atoi(arglist.maxdigits);
|
|
if ((maxdigits < 1) || (maxdigits > 255)) {
|
|
maxdigits = 255;
|
|
} else
|
|
ast_verb(3, "Accepting a maximum of %d digits.\n", maxdigits);
|
|
}
|
|
if (ast_strlen_zero(arglist.variable)) {
|
|
ast_log(LOG_WARNING, "Invalid! Usage: Read(variable[,filename][,maxdigits][,option][,attempts][,timeout])\n\n");
|
|
return 0;
|
|
}
|
|
if (ast_test_flag(&flags, OPT_INDICATION)) {
|
|
if (!ast_strlen_zero(arglist.filename)) {
|
|
ts = ast_get_indication_tone(ast_channel_zone(chan), arglist.filename);
|
|
}
|
|
}
|
|
if (ast_test_flag(&flags, OPT_TERMINATOR)) {
|
|
if (!ast_strlen_zero(opt_args[OPT_ARG_TERMINATOR])) {
|
|
terminator = opt_args[OPT_ARG_TERMINATOR];
|
|
} else {
|
|
terminator = ""; /* no digit inherently will terminate input */
|
|
}
|
|
}
|
|
if (ast_channel_state(chan) != AST_STATE_UP) {
|
|
if (ast_test_flag(&flags, OPT_SKIP)) {
|
|
/* At the user's option, skip if the line is not up */
|
|
if (ts) {
|
|
ts = ast_tone_zone_sound_unref(ts);
|
|
}
|
|
pbx_builtin_setvar_helper(chan, arglist.variable, "");
|
|
pbx_builtin_setvar_helper(chan, "READSTATUS", "SKIPPED");
|
|
return 0;
|
|
} else if (!ast_test_flag(&flags, OPT_NOANSWER)) {
|
|
/* Otherwise answer unless we're supposed to read while on-hook */
|
|
res = ast_answer(chan);
|
|
}
|
|
}
|
|
if (!res) {
|
|
while (tries && !res) {
|
|
ast_stopstream(chan);
|
|
if (ts && ts->data[0]) {
|
|
if (!to)
|
|
to = ast_channel_pbx(chan) ? ast_channel_pbx(chan)->rtimeoutms : 6000;
|
|
res = ast_playtones_start(chan, 0, ts->data, 0);
|
|
for (x = 0; x < maxdigits; ) {
|
|
res = ast_waitfordigit(chan, to);
|
|
ast_playtones_stop(chan);
|
|
if (res < 1) {
|
|
if (res == 0)
|
|
status = "TIMEOUT";
|
|
tmp[x]='\0';
|
|
break;
|
|
}
|
|
tmp[x++] = res;
|
|
if (terminator && strchr(terminator, tmp[x-1])) {
|
|
tmp[x-1] = '\0';
|
|
status = "OK";
|
|
break;
|
|
}
|
|
if (x >= maxdigits) {
|
|
status = "OK";
|
|
}
|
|
}
|
|
} else {
|
|
res = ast_app_getdata_terminator(chan, arglist.filename, tmp, maxdigits, to, terminator);
|
|
if (res == AST_GETDATA_COMPLETE) {
|
|
status = "OK";
|
|
} else if (res == AST_GETDATA_EMPTY_END_TERMINATED) {
|
|
if (ast_test_flag(&flags, OPT_KEEP_TERMINATOR)) {
|
|
/* if the option is set to do so, read the
|
|
returned string as the terminator string */
|
|
ast_copy_string(tmp, terminator, sizeof(tmp));
|
|
}
|
|
status = "OK";
|
|
} else if (res == AST_GETDATA_TIMEOUT) {
|
|
status = "TIMEOUT";
|
|
} else if (res == AST_GETDATA_INTERRUPTED) {
|
|
status = "INTERRUPTED";
|
|
}
|
|
}
|
|
if (res > -1) {
|
|
pbx_builtin_setvar_helper(chan, arglist.variable, tmp);
|
|
if (!ast_strlen_zero(tmp)) {
|
|
ast_verb(3, "User entered '%s'\n", tmp);
|
|
tries = 0;
|
|
} else {
|
|
tries--;
|
|
if (tries)
|
|
ast_verb(3, "User entered nothing, %d chance%s left\n", tries, (tries != 1) ? "s" : "");
|
|
else
|
|
ast_verb(3, "User entered nothing.\n");
|
|
}
|
|
res = 0;
|
|
} else {
|
|
pbx_builtin_setvar_helper(chan, arglist.variable, tmp);
|
|
ast_verb(3, "User disconnected\n");
|
|
}
|
|
}
|
|
}
|
|
|
|
if (ts) {
|
|
ts = ast_tone_zone_sound_unref(ts);
|
|
}
|
|
|
|
if (ast_check_hangup(chan))
|
|
status = "HANGUP";
|
|
pbx_builtin_setvar_helper(chan, "READSTATUS", status);
|
|
return 0;
|
|
}
|
|
|
|
static int unload_module(void)
|
|
{
|
|
return ast_unregister_application(app);
|
|
}
|
|
|
|
static int load_module(void)
|
|
{
|
|
return ast_register_application_xml(app, read_exec);
|
|
}
|
|
|
|
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Read Variable Application");
|