asterisk/apps/app_read.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">
		<since><version>1.6.1.0</version></since>
		<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="&amp;">
				<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>&amp;</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");