res_agi.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 1999 - 2006, 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 AGI - the Asterisk Gateway Interface
 *
 * \author Mark Spencer <markster@digium.com>
 *
 */

/*** MODULEINFO
	<depend>res_speech</depend>
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <math.h>
#include <signal.h>
#include <sys/time.h>
#include <sys/wait.h>
#include <sys/stat.h>
#include <pthread.h>

#include "asterisk/paths.h"	/* use many ast_config_AST_*_DIR */
#include "asterisk/network.h"
#include "asterisk/file.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/module.h"
#include "asterisk/astdb.h"
#include "asterisk/callerid.h"
#include "asterisk/cli.h"
#include "asterisk/image.h"
#include "asterisk/say.h"
#include "asterisk/app.h"
#include "asterisk/dsp.h"
#include "asterisk/musiconhold.h"
#include "asterisk/utils.h"
#include "asterisk/lock.h"
#include "asterisk/strings.h"
#include "asterisk/manager.h"
#include "asterisk/ast_version.h"
#include "asterisk/speech.h"
#include "asterisk/manager.h"
#include "asterisk/term.h"
#include "asterisk/xmldoc.h"
#include "asterisk/srv.h"
#include "asterisk/test.h"
#include "asterisk/netsock2.h"
#include "asterisk/stasis_channels.h"
#include "asterisk/stasis_message_router.h"
#include "asterisk/format_cache.h"

#define AST_API_MODULE
#include "asterisk/agi.h"

/*** DOCUMENTATION
	<agi name="answer" language="en_US">
		<synopsis>
			Answer channel
		</synopsis>
		<syntax />
		<description>
			<para>Answers channel if not already in answer state. Returns <literal>-1</literal> on
			channel failure, or <literal>0</literal> if successful.</para>
		</description>
		<see-also>
			<ref type="agi">hangup</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="asyncagi break" language="en_US">
		<synopsis>
			Interrupts Async AGI
		</synopsis>
		<syntax />
		<description>
			<para>Interrupts expected flow of Async AGI commands and returns control to previous source
			(typically, the PBX dialplan).</para>
		</description>
		<see-also>
			<ref type="agi">hangup</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="channel status" language="en_US">
		<synopsis>
			Returns status of the connected channel.
		</synopsis>
		<syntax>
			<parameter name="channelname" />
		</syntax>
		<description>
			<para>Returns the status of the specified <replaceable>channelname</replaceable>.
			If no channel name is given then returns the status of the current channel.</para>
			<para>Return values:</para>
			<enumlist>
				<enum name="0">
					<para>Channel is down and available.</para>
				</enum>
				<enum name="1">
					<para>Channel is down, but reserved.</para>
				</enum>
				<enum name="2">
					<para>Channel is off hook.</para>
				</enum>
				<enum name="3">
					<para>Digits (or equivalent) have been dialed.</para>
				</enum>
				<enum name="4">
					<para>Line is ringing.</para>
				</enum>
				<enum name="5">
					<para>Remote end is ringing.</para>
				</enum>
				<enum name="6">
					<para>Line is up.</para>
				</enum>
				<enum name="7">
					<para>Line is busy.</para>
				</enum>
			</enumlist>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="control stream file" language="en_US">
		<synopsis>
			Sends audio file on channel and allows the listener to control the stream.
		</synopsis>
		<syntax>
			<parameter name="filename" required="true">
				<para>The file extension must not be included in the filename.</para>
			</parameter>
			<parameter name="escape_digits" required="true" />
			<parameter name="skipms" />
			<parameter name="ffchar">
				<para>Defaults to <literal>#</literal></para>
			</parameter>
			<parameter name="rewchr">
				<para>Defaults to <literal>*</literal></para>
			</parameter>
			<parameter name="pausechr" />
			<parameter name="offsetms">
				<para>Offset, in milliseconds, to start the audio playback</para>
			</parameter>
		</syntax>
		<description>
			<para>Send the given file, allowing playback to be controlled by the given
			digits, if any. Use double quotes for the digits if you wish none to be
			permitted. If offsetms is provided then the audio will seek to offsetms
			before play starts. Returns <literal>0</literal> if playback completes without a digit
			being pressed, or the ASCII numerical value of the digit if one was pressed,
			or <literal>-1</literal> on error or if the channel was disconnected. Returns the
			position where playback was terminated as endpos.</para>

			<para>It sets the following channel variables upon completion:</para>
			<variablelist>
				<variable name="CPLAYBACKSTATUS">
					<para>Contains the status of the attempt as a text string</para>
					<value name="SUCCESS" />
					<value name="USERSTOPPED" />
					<value name="REMOTESTOPPED" />
					<value name="ERROR" />
				</variable>
				<variable name="CPLAYBACKOFFSET">
					<para>Contains the offset in ms into the file where playback
					was at when it stopped. <literal>-1</literal> is end of file.</para>
				</variable>
				<variable name="CPLAYBACKSTOPKEY">
					<para>If the playback is stopped by the user this variable contains
					the key that was pressed.</para>
				</variable>
			</variablelist>
		</description>
		<see-also>
			<ref type="agi">get option</ref>
			<ref type="agi">control stream file</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="database del" language="en_US">
		<synopsis>
			Removes database key/value
		</synopsis>
		<syntax>
			<parameter name="family" required="true" />
			<parameter name="key" required="true" />
		</syntax>
		<description>
			<para>Deletes an entry in the Asterisk database for a given
			<replaceable>family</replaceable> and <replaceable>key</replaceable>.</para>
			<para>Returns <literal>1</literal> if successful, <literal>0</literal>
			otherwise.</para>
		</description>
		<see-also>
			<ref type="agi">database get</ref>
			<ref type="agi">database put</ref>
			<ref type="agi">database deltree</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="database deltree" language="en_US">
		<synopsis>
			Removes database keytree/value
		</synopsis>
		<syntax>
			<parameter name="family" required="true" />
			<parameter name="keytree" />
		</syntax>
		<description>
			<para>Deletes a <replaceable>family</replaceable> or specific <replaceable>keytree</replaceable>
			within a <replaceable>family</replaceable> in the Asterisk database.</para>
			<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
		</description>
		<see-also>
			<ref type="agi">database get</ref>
			<ref type="agi">database put</ref>
			<ref type="agi">database del</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="database get" language="en_US">
		<synopsis>
			Gets database value
		</synopsis>
		<syntax>
			<parameter name="family" required="true" />
			<parameter name="key" required="true" />
		</syntax>
		<description>
			<para>Retrieves an entry in the Asterisk database for a given <replaceable>family</replaceable>
			and <replaceable>key</replaceable>.</para>
			<para>Returns <literal>0</literal> if <replaceable>key</replaceable> is not set.
			Returns <literal>1</literal> if <replaceable>key</replaceable> is set and returns the variable
			in parenthesis.</para>
			<para>Example return code: 200 result=1 (testvariable)</para>
		</description>
		<see-also>
			<ref type="agi">database put</ref>
			<ref type="agi">database del</ref>
			<ref type="agi">database deltree</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="database put" language="en_US">
		<synopsis>
			Adds/updates database value
		</synopsis>
		<syntax>
			<parameter name="family" required="true" />
			<parameter name="key" required="true" />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Adds or updates an entry in the Asterisk database for a given
			<replaceable>family</replaceable>, <replaceable>key</replaceable>, and
			<replaceable>value</replaceable>.</para>
			<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
		</description>
		<see-also>
			<ref type="agi">database get</ref>
			<ref type="agi">database del</ref>
			<ref type="agi">database deltree</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="exec" language="en_US">
		<synopsis>
			Executes a given Application
		</synopsis>
		<syntax>
			<parameter name="application" required="true" />
			<parameter name="options" required="true" />
		</syntax>
		<description>
			<para>Executes <replaceable>application</replaceable> with given
			<replaceable>options</replaceable>.</para>
			<para>Returns whatever the <replaceable>application</replaceable> returns, or
			<literal>-2</literal> on failure to find <replaceable>application</replaceable>.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="get data" language="en_US">
		<synopsis>
			Prompts for DTMF on a channel
		</synopsis>
		<syntax>
			<parameter name="file" required="true" />
			<parameter name="timeout" />
			<parameter name="maxdigits" />
		</syntax>
		<description>
			<para>Stream the given <replaceable>file</replaceable>, and receive DTMF data.</para>
			<para>Returns the digits received from the channel at the other end.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="get full variable" language="en_US">
		<synopsis>
			Evaluates a channel expression
		</synopsis>
		<syntax>
			<parameter name="expression" required="true" />
			<parameter name="channelname" />
		</syntax>
		<description>
			<para>Evaluates the given <replaceable>expression</replaceable> against the
			channel specified by <replaceable>channelname</replaceable>, or the current
			channel if <replaceable>channelname</replaceable> is not provided.</para>
			<para>Unlike GET VARIABLE, the <replaceable>expression</replaceable> is
			processed in a manner similar to dialplan evaluation, allowing complex
			and built-in variables to be accessed, e.g. <literal>The time is
			${EPOCH}</literal></para>
			<para>Returns <literal>0</literal> if no channel matching
			<replaceable>channelname</replaceable> exists, <literal>1</literal>
			otherwise.</para>
			<para>Example return code: 200 result=1 (The time is 1578493800)</para>
		</description>
		<see-also>
			<ref type="agi">get variable</ref>
			<ref type="agi">set variable</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="get option" language="en_US">
		<synopsis>
			Stream file, prompt for DTMF, with timeout.
		</synopsis>
		<syntax>
			<parameter name="filename" required="true" />
			<parameter name="escape_digits" required="true" />
			<parameter name="timeout" />
		</syntax>
		<description>
			<para>Behaves similar to STREAM FILE but used with a timeout option.</para>
		</description>
		<see-also>
			<ref type="agi">stream file</ref>
			<ref type="agi">control stream file</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="get variable" language="en_US">
		<synopsis>
			Gets a channel variable.
		</synopsis>
		<syntax>
			<parameter name="variablename" required="true" />
		</syntax>
		<description>
			<para>Returns <literal>0</literal> if <replaceable>variablename</replaceable> is not set.
			Returns <literal>1</literal> if <replaceable>variablename</replaceable> is set and returns
			the variable in parentheses.</para>
			<para>Example return code: 200 result=1 (testvariable)</para>
		</description>
		<see-also>
			<ref type="agi">get full variable</ref>
			<ref type="agi">set variable</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="hangup" language="en_US">
		<synopsis>
			Hangup a channel.
		</synopsis>
		<syntax>
			<parameter name="channelname" />
		</syntax>
		<description>
			<para>Hangs up the specified channel. If no channel name is given, hangs
			up the current channel</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="noop" language="en_US">
		<synopsis>
			Does nothing.
		</synopsis>
		<syntax />
		<description>
			<para>Does nothing.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="receive char" language="en_US">
		<synopsis>
			Receives one character from channels supporting it.
		</synopsis>
		<syntax>
			<parameter name="timeout" required="true">
				<para>The maximum time to wait for input in milliseconds, or <literal>0</literal>
				for infinite. Most channels</para>
			</parameter>
		</syntax>
		<description>
			<para>Receives a character of text on a channel. Most channels do not support
			the reception of text. Returns the decimal value of the character
			if one is received, or <literal>0</literal> if the channel does not support
			text reception. Returns <literal>-1</literal> only on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">receive text</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="receive text" language="en_US">
		<synopsis>
			Receives text from channels supporting it.
		</synopsis>
		<syntax>
			<parameter name="timeout" required="true">
				<para>The timeout to be the maximum time to wait for input in
				milliseconds, or <literal>0</literal> for infinite.</para>
			</parameter>
		</syntax>
		<description>
			<para>Receives a string of text on a channel. Most channels
			do not support the reception of text. Returns <literal>-1</literal> for failure
			or <literal>1</literal> for success, and the string in parenthesis.</para>
		</description>
		<see-also>
			<ref type="agi">receive char</ref>
			<ref type="agi">send text</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="record file" language="en_US">
		<synopsis>
			Records to a given file.
		</synopsis>
		<syntax>
			<parameter name="filename" required="true">
				<para>The destination filename of the recorded audio.</para>
			</parameter>
			<parameter name="format" required="true">
				<para>The audio format in which to save the resulting file.</para>
			</parameter>
			<parameter name="escape_digits" required="true">
				<para>The DTMF digits that will terminate the recording process.</para>
			</parameter>
			<parameter name="timeout" required="true">
				<para>The maximum recording time in milliseconds. Set to -1 for no
				limit.</para>
			</parameter>
			<parameter name="offset_samples">
				<para>Causes the recording to first seek to the specified offset before
				recording begins.</para>
			</parameter>
			<parameter name="beep">
				<para>Causes Asterisk to play a beep as recording begins. This argument
				can take any value.</para>
			</parameter>
			<parameter name="s=silence">
				<para>The number of seconds of silence that are permitted before the
				recording is terminated, regardless of the
				<replaceable>escape_digits</replaceable> or <replaceable>timeout</replaceable>
				arguments. If specified, this parameter must be preceded by
				<literal>s=</literal>.</para>
			</parameter>
		</syntax>
		<description>
			<para>Record to a file until a given dtmf digit in the sequence is received.
			Returns <literal>-1</literal> on hangup or error.  The format will specify what kind of file
			will be recorded. The <replaceable>timeout</replaceable> is the maximum record time in
			milliseconds, or <literal>-1</literal> for no <replaceable>timeout</replaceable>.
			<replaceable>offset samples</replaceable> is optional, and, if provided, will seek
			to the offset without exceeding the end of the
			file. <replaceable>beep</replaceable> can take any value, and causes Asterisk
			to play a beep to the channel that is about to be recorded. <replaceable>silence</replaceable> is
			the number of seconds of silence allowed before the function returns despite the
			lack of dtmf digits or reaching <replaceable>timeout</replaceable>. <replaceable>silence</replaceable>
			value must be preceded by <literal>s=</literal> and is also optional.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say alpha" language="en_US">
		<synopsis>
			Says a given character string.
		</synopsis>
		<syntax>
			<parameter name="number" required="true" />
			<parameter name="escape_digits" required="true" />
		</syntax>
		<description>
			<para>Say a given character string, returning early if any of the given DTMF digits
			are received on the channel. Returns <literal>0</literal> if playback completes
			without a digit being pressed, or the ASCII numerical value of the digit if one
			was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say digits</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say time</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say digits" language="en_US">
		<synopsis>
			Says a given digit string.
		</synopsis>
		<syntax>
			<parameter name="number" required="true" />
			<parameter name="escape_digits" required="true" />
		</syntax>
		<description>
			<para>Say a given digit string, returning early if any of the given DTMF digits
			are received on the channel. Returns <literal>0</literal> if playback completes
			without a digit being pressed, or the ASCII numerical value of the digit if one
			was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say time</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say number" language="en_US">
		<synopsis>
			Says a given number.
		</synopsis>
		<syntax>
			<parameter name="number" required="true" />
			<parameter name="escape_digits" required="true" />
			<parameter name="gender" />
		</syntax>
		<description>
			<para>Say a given number, returning early if any of the given DTMF digits
			are received on the channel.  Returns <literal>0</literal> if playback
			completes without a digit being pressed, or the ASCII numerical value of
			the digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say digits</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say time</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say phonetic" language="en_US">
		<synopsis>
			Says a given character string with phonetics.
		</synopsis>
		<syntax>
			<parameter name="string" required="true" />
			<parameter name="escape_digits" required="true" />
		</syntax>
		<description>
			<para>Say a given character string with phonetics, returning early if any of the
			given DTMF digits are received on the channel. Returns <literal>0</literal> if
			playback completes without a digit pressed, the ASCII numerical value of the digit
			if one was pressed, or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say digits</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say time</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say date" language="en_US">
		<synopsis>
			Says a given date.
		</synopsis>
		<syntax>
			<parameter name="date" required="true">
				<para>Is number of seconds elapsed since 00:00:00 on January 1, 1970.
				Coordinated Universal Time (UTC).</para>
			</parameter>
			<parameter name="escape_digits" required="true" />
		</syntax>
		<description>
			<para>Say a given date, returning early if any of the given DTMF digits are
			received on the channel. Returns <literal>0</literal> if playback
			completes without a digit being pressed, or the ASCII numerical value of the
			digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say digits</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say time</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say time" language="en_US">
		<synopsis>
			Says a given time.
		</synopsis>
		<syntax>
			<parameter name="time" required="true">
				<para>Is number of seconds elapsed since 00:00:00 on January 1, 1970.
				Coordinated Universal Time (UTC).</para>
			</parameter>
			<parameter name="escape_digits" required="true" />
		</syntax>
		<description>
			<para>Say a given time, returning early if any of the given DTMF digits are
			received on the channel. Returns <literal>0</literal> if playback completes
			without a digit being pressed, or the ASCII numerical value of the digit if
			one was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say digits</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say datetime</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="say datetime" language="en_US">
		<synopsis>
			Says a given time as specified by the format given.
		</synopsis>
		<syntax>
			<parameter name="time" required="true">
				<para>Is number of seconds elapsed since 00:00:00
				on January 1, 1970, Coordinated Universal Time (UTC)</para>
			</parameter>
			<parameter name="escape_digits" required="true" />
			<parameter name="format">
				<para>Is the format the time should be said in. See
				<filename>voicemail.conf</filename> (defaults to <literal>ABdY
				'digits/at' IMp</literal>).</para>
			</parameter>
			<parameter name="timezone">
				<para>Acceptable values can be found in <filename>/usr/share/zoneinfo</filename>
				Defaults to machine default.</para>
			</parameter>
		</syntax>
		<description>
			<para>Say a given time, returning early if any of the given DTMF digits are
			received on the channel. Returns <literal>0</literal> if playback
			completes without a digit being pressed, or the ASCII numerical value of the
			digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">say alpha</ref>
			<ref type="agi">say digits</ref>
			<ref type="agi">say number</ref>
			<ref type="agi">say phonetic</ref>
			<ref type="agi">say date</ref>
			<ref type="agi">say time</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="send image" language="en_US">
		<synopsis>
			Sends images to channels supporting it.
		</synopsis>
		<syntax>
			<parameter name="image" required="true" />
		</syntax>
		<description>
			<para>Sends the given image on a channel. Most channels do not support the
			transmission of images. Returns <literal>0</literal> if image is sent, or if
			the channel does not support image transmission.  Returns <literal>-1</literal>
			only on error/hangup. Image names should not include extensions.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="send text" language="en_US">
		<synopsis>
			Sends text to channels supporting it.
		</synopsis>
		<syntax>
			<parameter name="text to send" required="true">
				<para>Text consisting of greater than one word should be placed
				in quotes since the command only accepts a single argument.</para>
			</parameter>
		</syntax>
		<description>
			<para>Sends the given text on a channel. Most channels do not support the
			transmission of text. Returns <literal>0</literal> if text is sent, or if the
			channel does not support text transmission. Returns <literal>-1</literal> only
			on error/hangup.</para>
		</description>
		<see-also>
			<ref type="agi">receive text</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set autohangup" language="en_US">
		<synopsis>
			Autohangup channel in some time.
		</synopsis>
		<syntax>
			<parameter name="time" required="true" />
		</syntax>
		<description>
			<para>Cause the channel to automatically hangup at <replaceable>time</replaceable>
			seconds in the future. Of course it can be hungup before then as well. Setting to
			<literal>0</literal> will cause the autohangup feature to be disabled on this channel.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set callerid" language="en_US">
		<synopsis>
			Sets callerid for the current channel.
		</synopsis>
		<syntax>
			<parameter name="number" required="true" />
		</syntax>
		<description>
			<para>Changes the callerid of the current channel.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set context" language="en_US">
		<synopsis>
			Sets channel context.
		</synopsis>
		<syntax>
			<parameter name="desired context" required="true" />
		</syntax>
		<description>
			<para>Sets the context for continuation upon exiting the application.</para>
		</description>
		<see-also>
			<ref type="agi">set extension</ref>
			<ref type="agi">set priority</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set extension" language="en_US">
		<synopsis>
			Changes channel extension.
		</synopsis>
		<syntax>
			<parameter name="new extension" required="true" />
		</syntax>
		<description>
			<para>Changes the extension for continuation upon exiting the application.</para>
		</description>
		<see-also>
			<ref type="agi">set context</ref>
			<ref type="agi">set priority</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set music" language="en_US">
		<synopsis>
			Enable/Disable Music on hold generator
		</synopsis>
		<syntax>
			<parameter required="true">
				<enumlist>
					<enum>
						<parameter name="on" literal="true" required="true" />
					</enum>
					<enum>
						<parameter name="off" literal="true" required="true" />
					</enum>
				</enumlist>
			</parameter>
			<parameter name="class" required="true" />
		</syntax>
		<description>
			<para>Enables/Disables the music on hold generator. If <replaceable>class</replaceable>
			is not specified, then the <literal>default</literal> music on hold class will be
			used. This generator will be stopped automatically when playing a file.</para>
			<para>Always returns <literal>0</literal>.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set priority" language="en_US">
		<synopsis>
			Set channel dialplan priority.
		</synopsis>
		<syntax>
			<parameter name="priority" required="true" />
		</syntax>
		<description>
			<para>Changes the priority for continuation upon exiting the application.
			The priority must be a valid priority or label.</para>
		</description>
		<see-also>
			<ref type="agi">set context</ref>
			<ref type="agi">set extension</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="set variable" language="en_US">
		<synopsis>
			Sets a channel variable.
		</synopsis>
		<syntax>
			<parameter name="variablename" required="true" />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Sets a variable to the current channel.</para>
		</description>
		<see-also>
			<ref type="agi">get variable</ref>
			<ref type="agi">get full variable</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="stream file" language="en_US">
		<synopsis>
			Sends audio file on channel.
		</synopsis>
		<syntax>
			<parameter name="filename" required="true">
				<para>File name to play. The file extension must not be
				included in the <replaceable>filename</replaceable>.</para>
			</parameter>
			<parameter name="escape_digits" required="true">
				<para>Use double quotes for the digits if you wish none to be
				permitted.</para>
			</parameter>
			<parameter name="sample offset">
				<para>If sample offset is provided then the audio will seek to sample
				offset before play starts.</para>
			</parameter>
		</syntax>
		<description>
			<para>Send the given file, allowing playback to be interrupted by the given
			digits, if any. Returns <literal>0</literal> if playback completes without a digit
			being pressed, or the ASCII numerical value of the digit if one was pressed,
			or <literal>-1</literal> on error or if the channel was disconnected. If
			musiconhold is playing before calling stream file it will be automatically
			stopped and will not be restarted after completion.</para>
			<para>It sets the following channel variables upon completion:</para>
			<variablelist>
				<variable name="PLAYBACKSTATUS">
					<para>The status of the playback attempt as a text string.</para>
					<value name="SUCCESS"/>
					<value name="FAILED"/>
				</variable>
			</variablelist>
		</description>
		<see-also>
			<ref type="agi">control stream file</ref>
			<ref type="agi">get option</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="tdd mode" language="en_US">
		<synopsis>
			Toggles TDD mode (for the deaf).
		</synopsis>
		<syntax>
			<parameter name="boolean" required="true">
				<enumlist>
					<enum name="on" />
					<enum name="off" />
				</enumlist>
			</parameter>
		</syntax>
		<description>
			<para>Enable/Disable TDD transmission/reception on a channel. Returns <literal>1</literal> if
			successful, or <literal>0</literal> if channel is not TDD-capable.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="verbose" language="en_US">
		<synopsis>
			Logs a message to the asterisk verbose log.
		</synopsis>
		<syntax>
			<parameter name="message" required="true" />
			<parameter name="level" required="true" />
		</syntax>
		<description>
			<para>Sends <replaceable>message</replaceable> to the console via verbose
			message system. <replaceable>level</replaceable> is the verbose level (1-4).
			Always returns <literal>1</literal></para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="wait for digit" language="en_US">
		<synopsis>
			Waits for a digit to be pressed.
		</synopsis>
		<syntax>
			<parameter name="timeout" required="true" />
		</syntax>
		<description>
			<para>Waits up to <replaceable>timeout</replaceable> milliseconds for channel to
			receive a DTMF digit. Returns <literal>-1</literal> on channel failure, <literal>0</literal>
			if no digit is received in the timeout, or the numerical value of the ascii of the digit if
			one is received. Use <literal>-1</literal> for the <replaceable>timeout</replaceable> value if
			you desire the call to block indefinitely.</para>
		</description>
		<see-also>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="speech create" language="en_US">
		<synopsis>
			Creates a speech object.
		</synopsis>
		<syntax>
			<parameter name="engine" required="true" />
		</syntax>
		<description>
			<para>Create a speech object to be used by the other Speech AGI commands.</para>
		</description>
		<see-also>
			<ref type="agi">speech set</ref>
			<ref type="agi">speech destroy</ref>
			<ref type="agi">speech load grammar</ref>
			<ref type="agi">speech unload grammar</ref>
			<ref type="agi">speech activate grammar</ref>
			<ref type="agi">speech deactivate grammar</ref>
			<ref type="agi">speech recognize</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="speech set" language="en_US">
		<synopsis>
			Sets a speech engine setting.
		</synopsis>
		<syntax>
			<parameter name="name" required="true" />
			<parameter name="value" required="true" />
		</syntax>
		<description>
			<para>Set an engine-specific setting.</para>
		</description>
		<see-also>
			<ref type="agi">speech create</ref>
			<ref type="agi">speech destroy</ref>
			<ref type="agi">speech load grammar</ref>
			<ref type="agi">speech unload grammar</ref>
			<ref type="agi">speech activate grammar</ref>
			<ref type="agi">speech deactivate grammar</ref>
			<ref type="agi">speech recognize</ref>
			<ref type="application">AGI</ref>
		</see-also>
	</agi>
	<agi name="speech destroy" language="en_US">
		<synopsis>
			Destroys a speech object.
		</synopsis>
		<syntax>
		</syntax>
		<description>
			<para>Destroy the speech object created by <literal>SPEECH CREATE</literal>.</para>
		</description>
		<see-also>