diff options
author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-11-01 21:10:07 +0000 |
---|---|---|
committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-11-01 21:10:07 +0000 |
commit | b1f91b97d2085cc845d0f57bd9907de50c995105 (patch) | |
tree | 9c836ac808552d20be6bd2baa3a3c29f642eda53 /apps | |
parent | c5d084051f21e943fcbcc347fc80b166885f298d (diff) |
Merge changes from team/group/appdocsxml
This commit introduces the first phase of an effort to manage documentation of the
interfaces in Asterisk in an XML format. Currently, a new format is available for
applications and dialplan functions. A good number of conversions to the new format
are also included.
For more information, see the following message to asterisk-dev:
http://lists.digium.com/pipermail/asterisk-dev/2008-October/034968.html
git-svn-id: http://svn.digium.com/svn/asterisk/trunk@153365 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'apps')
54 files changed, 2924 insertions, 1327 deletions
diff --git a/apps/app_adsiprog.c b/apps/app_adsiprog.c index 255026fbd..f35a81eea 100644 --- a/apps/app_adsiprog.c +++ b/apps/app_adsiprog.c @@ -47,14 +47,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "ADSIProg"; -static char *synopsis = "Load Asterisk ADSI Scripts into phone"; +/*** DOCUMENTATION + <application name="ADSIProg" language="en_US"> + <synopsis> + Load Asterisk ADSI Scripts into phone + </synopsis> + <syntax> + <parameter name="script" required="false"> + <para>adsi script to use. If not given uses the default script <filename>asterisk.adsi</filename></para> + </parameter> + </syntax> + <description> + <para>This application programs an ADSI Phone with the given script</para> + </description> + </application> + ***/ /* #define DUMP_MESSAGES */ -static char *descrip = -" ADSIProg(script): This application programs an ADSI Phone with the given\n" -"script. If nothing is specified, the default script (asterisk.adsi) is used.\n"; - struct adsi_event { int id; char *name; @@ -1570,7 +1580,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(app, adsi_exec, synopsis, descrip)) + if (ast_register_application_xml(app, adsi_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_alarmreceiver.c b/apps/app_alarmreceiver.c index db76bbdb7..12ae49d65 100644 --- a/apps/app_alarmreceiver.c +++ b/apps/app_alarmreceiver.c @@ -63,18 +63,21 @@ struct event_node{ typedef struct event_node event_node_t; static char *app = "AlarmReceiver"; - -static char *synopsis = "Provide support for receiving alarm reports from a burglar or fire alarm panel"; -static char *descrip = -" AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco\n" -"Contact ID. This application should be called whenever there is an alarm\n" -"panel calling in to dump its events. The application will handshake with the\n" -"alarm panel, and receive events, validate them, handshake them, and store them\n" -"until the panel hangs up. Once the panel hangs up, the application will run the\n" -"system command specified by the eventcmd setting in alarmreceiver.conf and pipe\n" -"the events to the standard input of the application. The configuration file also\n" -"contains settings for DTMF timing, and for the loudness of the acknowledgement\n" -"tones.\n"; +/*** DOCUMENTATION + <application name="AlarmReceiver" language="en_US"> + <synopsis> + Provide support for receiving alarm reports from a burglar or fire alarm panel + </synopsis> + <syntax /> + <description> + <para>This application should be called whenever there is an alarm panel calling in to dump its events. + The application will handshake with the alarm panel, and receive events, validate them, handshake them, and store them until the panel hangs up. + Once the panel hangs up, the application will run the system command specified by the eventcmd setting in <filename>alarmreceiver.conf</filename> and pipe the events to the standard input of the application. + The configuration file also contains settings for DTMF timing, and for the loudness of the acknowledgement tones.</para> + <note><para>Only 1 signalling format is supported at this time: Ademco Contact ID.</para></note> + </description> + </application> + ***/ /* Config Variables */ static int fdtimeout = 2000; @@ -711,7 +714,7 @@ static int unload_module(void) static int load_module(void) { if (load_config()) { - if (ast_register_application(app, alarmreceiver_exec, synopsis, descrip)) + if (ast_register_application_xml(app, alarmreceiver_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } else diff --git a/apps/app_amd.c b/apps/app_amd.c index 81298f400..bf3603b3e 100644 --- a/apps/app_amd.c +++ b/apps/app_amd.c @@ -39,45 +39,88 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/config.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="AMD" language="en_US"> + <synopsis> + Attempt to detect answering machines. + </synopsis> + <syntax> + <parameter name="initialSilence" required="false"> + <para>Is maximum initial silence duration before greeting.</para> + <para>If this is exceeded set as MACHINE</para> + </parameter> + <parameter name="greeting" required="false"> + <para>is the maximum length of a greeting.</para> + <para>If this is exceeded set as MACHINE</para> + </parameter> + <parameter name="afterGreetingSilence" required="false"> + <para>Is the silence after detecting a greeting.</para> + <para>If this is exceeded set as HUMAN</para> + </parameter> + <parameter name="totalAnalysis Time" required="false"> + <para>Is the maximum time allowed for the algorithm</para> + <para>to decide HUMAN or MACHINE</para> + </parameter> + <parameter name="miniumWordLength" required="false"> + <para>Is the minimum duration of Voice considered to be a word</para> + </parameter> + <parameter name="betweenWordSilence" required="false"> + <para>Is the minimum duration of silence after a word to + consider the audio that follows to be a new word</para> + </parameter> + <parameter name="maximumNumberOfWords" required="false"> + <para>Is the maximum number of words in a greeting</para> + <para>If this is exceeded set as MACHINE</para> + </parameter> + <parameter name="silenceThreshold" required="false"> + <para>How long do we consider silence</para> + </parameter> + <parameter name="maximumWordLength" required="false"> + <para>Is the maximum duration of a word to accept.</para> + <para>If exceeded set as MACHINE</para> + </parameter> + </syntax> + <description> + <para>This application attempts to detect answering machines at the beginning + of outbound calls. Simply call this application after the call + has been answered (outbound only, of course).</para> + <para>When loaded, AMD reads amd.conf and uses the parameters specified as + default values. Those default values get overwritten when the calling AMD + with parameters.</para> + <para>This application sets the following channel variables:</para> + <variablelist> + <variable name="AMDSTATUS"> + <para>This is the status of the answering machine detection</para> + <value name="MACHINE" /> + <value name="HUMAN" /> + <value name="NOTSURE" /> + <value name="HANGUP" /> + </variable> + <variable name="AMDCAUSE"> + <para>Indicates the cause that led to the conclusion</para> + <value name="TOOLONG"> + Total Time. + </value> + <value name="INITIALSILENCE"> + Silence Duration - Initial Silence. + </value> + <value name="HUMAN"> + Silence Duration - afterGreetingSilence. + </value> + <value name="LONGGREETING"> + Voice Duration - Greeting. + </value> + <value name="MAXWORDLENGTH"> + Word Count - maximum number of words. + </value> + </variable> + </variablelist> + </description> + </application> + + ***/ static char *app = "AMD"; -static char *synopsis = "Attempts to detect answering machines"; -static char *descrip = -" AMD([initialSilence],[greeting],[afterGreetingSilence],[totalAnalysisTime]\n" -" ,[minimumWordLength],[betweenWordsSilence],[maximumNumberOfWords]\n" -" ,[silenceThreshold],[|maximumWordLength])\n" -" This application attempts to detect answering machines at the beginning\n" -" of outbound calls. Simply call this application after the call\n" -" has been answered (outbound only, of course).\n" -" When loaded, AMD reads amd.conf and uses the parameters specified as\n" -" default values. Those default values get overwritten when calling AMD\n" -" with parameters.\n" -"- 'initialSilence' is the maximum silence duration before the greeting. If\n" -" exceeded then MACHINE.\n" -"- 'greeting' is the maximum length of a greeting. If exceeded then MACHINE.\n" -"- 'afterGreetingSilence' is the silence after detecting a greeting.\n" -" If exceeded then HUMAN.\n" -"- 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide\n" -" on a HUMAN or MACHINE.\n" -"- 'minimumWordLength'is the minimum duration of Voice to considered as a word.\n" -"- 'betweenWordsSilence' is the minimum duration of silence after a word to \n" -" consider the audio that follows as a new word.\n" -"- 'maximumNumberOfWords'is the maximum number of words in the greeting. \n" -" If exceeded then MACHINE.\n" -"- 'silenceThreshold' is the silence threshold.\n" -"- 'maximumWordLength' is the maximum duration of a word to accept. If exceeded then MACHINE\n" -"This application sets the following channel variables upon completion:\n" -" AMDSTATUS - This is the status of the answering machine detection.\n" -" Possible values are:\n" -" MACHINE | HUMAN | NOTSURE | HANGUP\n" -" AMDCAUSE - Indicates the cause that led to the conclusion.\n" -" Possible values are:\n" -" TOOLONG-<%d total_time>\n" -" INITIALSILENCE-<%d silenceDuration>-<%d initialSilence>\n" -" HUMAN-<%d silenceDuration>-<%d afterGreetingSilence>\n" -" MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords>\n" -" LONGGREETING-<%d voiceDuration>-<%d greeting>\n" -" MAXWORDLENGTH-<%d consecutiveVoiceDuration>\n"; #define STATE_IN_WORD 1 #define STATE_IN_SILENCE 2 @@ -437,7 +480,7 @@ static int load_module(void) { if (load_config(0)) return AST_MODULE_LOAD_DECLINE; - if (ast_register_application(app, amd_exec, synopsis, descrip)) + if (ast_register_application_xml(app, amd_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_authenticate.c b/apps/app_authenticate.c index 1bdc1153b..10d0b2f73 100644 --- a/apps/app_authenticate.c +++ b/apps/app_authenticate.c @@ -54,31 +54,52 @@ AST_APP_OPTIONS(auth_app_options, { static char *app = "Authenticate"; - -static char *synopsis = "Authenticate a user"; - -static char *descrip = -" Authenticate(password[,options[,maxdigits[,prompt]]]): This application asks the caller\n" -"to enter a given password in order to continue dialplan execution. If the password\n" -"begins with the '/' character, it is interpreted as a file which contains a list of\n" -"valid passwords, listed 1 password per line in the file.\n" -" When using a database key, the value associated with the key can be anything.\n" -"Users have three attempts to authenticate before the channel is hung up.\n" -" Options:\n" -" a - Set the channels' account code to the password that is entered\n" -" d - Interpret the given path as database key, not a literal file\n" -" m - Interpret the given path as a file which contains a list of account\n" -" codes and password hashes delimited with ':', listed one per line in\n" -" the file. When one of the passwords is matched, the channel will have\n" -" its account code set to the corresponding account code in the file.\n" -" r - Remove the database key upon successful entry (valid with 'd' only)\n" -" maxdigits - maximum acceptable number of digits. Stops reading after\n" -" maxdigits have been entered (without requiring the user to\n" -" press the '#' key).\n" -" Defaults to 0 - no limit - wait for the user press the '#' key.\n" -" prompt - Override the agent-pass prompt file.\n" - ; -; +/*** DOCUMENTATION + <application name="Authenticate" language="en_US"> + <synopsis> + Authenticate a user + </synopsis> + <syntax> + <parameter name="password" required="true"> + <para>Password the user should know</para> + </parameter> + <parameter name="options" required="false"> + <optionlist> + <option name="a"> + <para>Set the channels' account code to the password that is entered</para> + </option> + <option name="d"> + <para>Interpret the given path as database key, not a literal file</para> + </option> + <option name="m"> + <para>Interpret the given path as a file which contains a list of account + codes and password hashes delimited with <literal>:</literal>, listed one per line in + the file. When one of the passwords is matched, the channel will have + its account code set to the corresponding account code in the file.</para> + </option> + <option name="r"> + <para>Remove the database key upon successful entry (valid with <literal>d</literal> only)</para> + </option> + </optionlist> + </parameter> + <parameter name="maxdigits" required="false"> + <para>maximum acceptable number of digits. Stops reading after + maxdigits have been entered (without requiring the user to press the <literal>#</literal> key). + Defaults to 0 - no limit - wait for the user press the <literal>#</literal> key.</para> + </parameter> + <parameter name="prompt" required="false"> + <para>Override the agent-pass prompt file.</para> + </parameter> + </syntax> + <description> + <para>This application asks the caller to enter a given password in order to continue dialplan execution.</para> + <para>If the password begins with the <literal>/</literal> character, + it is interpreted as a file which contains a list of valid passwords, listed 1 password per line in the file.</para> + <para>When using a database key, the value associated with the key can be anything.</para> + <para>Users have three attempts to authenticate before the channel is hung up.</para> + </description> + </application> + ***/ static int auth_exec(struct ast_channel *chan, void *data) { @@ -225,7 +246,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(app, auth_exec, synopsis, descrip)) + if (ast_register_application_xml(app, auth_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_cdr.c b/apps/app_cdr.c index 038b0a32f..ca228da03 100644 --- a/apps/app_cdr.c +++ b/apps/app_cdr.c @@ -32,13 +32,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/module.h" -static char *nocdr_descrip = -" NoCDR(): This application will tell Asterisk not to maintain a CDR for the\n" -"current call.\n"; +/*** DOCUMENTATION + <application name="NoCDR" language="en_US"> + <synopsis> + Tell Asterisk to not maintain a CDR for the current call + </synopsis> + <syntax /> + <description> + <para>This application will tell Asterisk not to maintain a CDR for the current call.</para> + </description> + </application> + ***/ static char *nocdr_app = "NoCDR"; -static char *nocdr_synopsis = "Tell Asterisk to not maintain a CDR for the current call"; - static int nocdr_exec(struct ast_channel *chan, void *data) { @@ -55,7 +61,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(nocdr_app, nocdr_exec, nocdr_synopsis, nocdr_descrip)) + if (ast_register_application_xml(nocdr_app, nocdr_exec)) return AST_MODULE_LOAD_FAILURE; return AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_chanisavail.c b/apps/app_chanisavail.c index 68cab31aa..bc1adcc79 100644 --- a/apps/app_chanisavail.c +++ b/apps/app_chanisavail.c @@ -43,22 +43,54 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "ChanIsAvail"; -static char *synopsis = "Check channel availability"; - -static char *descrip = -" ChanIsAvail(Technology/resource[&Technology2/resource2...][,options]): \n" -"This application will check to see if any of the specified channels are\n" -"available.\n" -" Options:\n" -" a - Check for all available channels, not only the first one.\n" -" s - Consider the channel unavailable if the channel is in use at all.\n" -" t - Simply checks if specified channels exist in the channel list\n" -" (implies option s).\n" -"This application sets the following channel variable upon completion:\n" -" AVAILCHAN - the name of the available channel, if one exists\n" -" AVAILORIGCHAN - the canonical channel name that was used to create the channel\n" -" AVAILSTATUS - the status code for the available channel\n"; - +/*** DOCUMENTATION + <application name="ChanIsAvail" language="en_US"> + <synopsis> + Check channel availability + </synopsis> + <syntax> + <parameter name="Technology/Resource" required="true" argsep="&"> + <argument name="Technology2/Resource2" multiple="true"> + <para>Optional extra devices to check</para> + <para>If you need more then one enter them as + Technology2/Resource2&Technology3/Resourse3&.....</para> + </argument> + <para>Specification of the device(s) to check. These must be in the format of + <literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable> + represents a particular channel driver, and <replaceable>Resource</replaceable> + represents a resource available to that particular channel driver.</para> + </parameter> + <parameter name="options" required="false"> + <optionlist> + <option name="a"> + <para>Check for all available channels, not only the first one</para> + </option> + <option name="s"> + <para>Consider the channel unavailable if the channel is in use at all</para> + </option> + <option name="t" implies="s"> + <para>Simply checks if specified channels exist in the channel list</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>This application will check to see if any of the specified channels are available.</para> + <para>This application sets the following channel variables:</para> + <variablelist> + <variable name="AVAILCHAN"> + <para>The name of the available channel, if one exists</para> + </variable> + <variable name="AVAILORIGCHAN"> + <para>The canonical channel name that was used to create the channel</para> + </variable> + <variable name="AVAILSTATUS"> + <para>The status code for the available channel</para> + </variable> + </variablelist> + </description> + </application> + ***/ static int chanavail_exec(struct ast_channel *chan, void *data) { @@ -165,7 +197,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, chanavail_exec, synopsis, descrip) ? + return ast_register_application_xml(app, chanavail_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_channelredirect.c b/apps/app_channelredirect.c index 610f254df..f89c45225 100644 --- a/apps/app_channelredirect.c +++ b/apps/app_channelredirect.c @@ -35,14 +35,32 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/features.h" +/*** DOCUMENTATION + <application name="ChannelRedirect" language="en_US"> + <synopsis> + Redirects given channel to a dialplan target + </synopsis> + <syntax> + <parameter name="channel" required="true" /> + <parameter name="context" required="false" /> + <parameter name="extension" required="false" /> + <parameter name="priority" required="true" /> + </syntax> + <description> + <para>Sends the specified channel to the specified extension priority</para> + + <para>This application sets the following channel variables upon completion</para> + <variablelist> + <variable name="CHANNELREDIRECT_STATUS"> + <value name="NOCHANNEL" /> + <value name="SUCCESS" /> + <para>Are set to the result of the redirection</para> + </variable> + </variablelist> + </description> + </application> + ***/ static char *app = "ChannelRedirect"; -static char *synopsis = "Redirects given channel to a dialplan target."; -static char *descrip = -"ChannelRedirect(channel,[[context,]extension,]priority)\n" -" Sends the specified channel to the specified extension priority\n" -"This application sets the following channel variables upon completion:\n" -" CHANNELREDIRECT_STATUS - Are set to the result of the redirection\n" -" either NOCHANNEL or SUCCESS\n"; static int asyncgoto_exec(struct ast_channel *chan, void *data) { @@ -89,7 +107,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, asyncgoto_exec, synopsis, descrip) ? + return ast_register_application_xml(app, asyncgoto_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_chanspy.c b/apps/app_chanspy.c index dea2017ea..92a430546 100644 --- a/apps/app_chanspy.c +++ b/apps/app_chanspy.c @@ -52,128 +52,238 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define AST_NAME_STRLEN 256 #define NUM_SPYGROUPS 128 -static const char *tdesc = "Listen to a channel, and optionally whisper into it"; +/*** DOCUMENTATION + <application name="ChanSpy" language="en_US"> + <synopsis> + Listen to a channel, and optionally whisper into it. + </synopsis> + <syntax> + <parameter name="chanprefix" /> + <parameter name="options"> + <optionlist> + <option name="b"> + <para>Only spy on channels involved in a bridged call.</para> + </option> + <option name="B"> + <para>Instead of whispering on a single channel barge in on both + channels involved in the call.</para> + </option> + <option name="d"> + <para>Override the typical numeric DTMF functionality and instead + use DTMF to switch between spy modes.</para> + <enumlist> + <enum name="4"> + <para>spy mode</para> + </enum> + <enum name="5"> + <para>whisper mode</para> + </enum> + <enum name="6"> + <para>barge mode</para> + </enum> + </enumlist> + </option> + <option name="g"> + <argument name="grp" required="true"> + <para>Only spy on channels in which one or more of the groups + listed in <replaceable>grp</replaceable> matches one or more groups from the + <variable>SPYGROUP</variable> variable set on the channel to be spied upon.</para> + </argument> + <note><para>both <replaceable>grp</replaceable> and <variable>SPYGROUP</variable> can contain + either a single group or a colon-delimited list of groups, such + as <literal>sales:support:accounting</literal>.</para></note> + </option> + <option name="n" argsep="@"> + <para>Say the name of the person being spied on if that person has recorded + his/her name. If a context is specified, then that voicemail context will + be searched when retrieving the name, otherwise the <literal>default</literal> context + be used when searching for the name (i.e. if SIP/1000 is the channel being + spied on and no mailbox is specified, then <literal>1000</literal> will be used when searching + for the name).</para> + <argument name="mailbox" /> + <argument name="context" /> + </option> + <option name="q"> + <para>Don't play a beep when beginning to spy on a channel, or speak the + selected channel name.</para> + </option> + <option name="r"> + <para>Record the session to the monitor spool directory. An optional base for the filename + may be specified. The default is <literal>chanspy</literal>.</para> + <argument name="basename" /> + </option> + <option name="s"> + <para>Skip the playback of the channel type (i.e. SIP, IAX, etc) when + speaking the selected channel name.</para> + </option> + <option name="v"> + <argument name="value" /> + <para>Adjust the initial volume in the range from <literal>-4</literal> + to <literal>4</literal>. A negative value refers to a quieter setting.</para> + </option> + <option name="w"> + <para>Enable <literal>whisper</literal> mode, so the spying channel can talk to + the spied-on channel.</para> + </option> + <option name="W"> + <para>Enable <literal>private whisper</literal> mode, so the spying channel can + talk to the spied-on channel but cannot listen to that channel.</para> + </option> + <option name="o"> + <para>Only listen to audio coming from this channel.</para> + </option> + <option name="X"> + <para>Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the <variable>SPY_EXIT_CONTEXT</variable> channel variable. The + name of the last channel that was spied on will be stored + in the <variable>SPY_CHANNEL</variable> variable.</para> + </option> + <option name="e"> + <argument name="ext" required="true" /> + <para>Enable <emphasis>enforced</emphasis> mode, so the spying channel can + only monitor extensions whose name is in the <replaceable>ext</replaceable> : delimited + list.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>This application is used to listen to the audio from an Asterisk channel. This includes the audio + coming in and "out of the channel being spied on. If the <literal>chanprefix</literal> parameter is specified, + only channels beginning with this string will be spied upon.</para> + <para>While spying, the following actions may be performed:</para> + <para> - Dialing <literal>#</literal> cycles the volume level.</para> + <para> - Dialing <literal>*</literal> will stop spying and look for another channel to spy on.</para> + <para> - Dialing a series of digits followed by <literal>#</literal> builds a channel name to append + to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing the digits '1234#' + while spying will begin spying on the channel 'Agent/1234'. Note that this feature will be overriden if the 'd' option + is used</para> + <note><para>The <replaceable>X</replaceable> option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will exit to it. + This also disables choosing a channel based on <literal>chanprefix</literal> and a digit sequence.</para></note> + </description> + </application> + <application name="ExtenSpy" language="en_US"> + <synopsis> + Listen to a channel, and optionally whisper into it. + </synopsis> + <syntax> + <parameter name="exten" required="true" argsep="@"> + <argument name="exten" required="true"> + <para>Specify extension.</para> + </argument> + <argument name="context"> + <para>Optionally specify a context, defaults to <literal>default</literal>.</para> + </argument> + </parameter> + <parameter name="options"> + <optionlist> + <option name="b"> + <para>Only spy on channels involved in a bridged call.</para> + </option> + <option name="B"> + <para>Instead of whispering on a single channel barge in on both + channels involved in the call.</para> + </option> + <option name="d"> + <para>Override the typical numeric DTMF functionality and instead + use DTMF to switch between spy modes.</para> + <enumlist> + <enum name="4"> + <para>spy mode</para> + </enum> + <enum name="5"> + <para>whisper mode</para> + </enum> + <enum name="6"> + <para>barge mode</para> + </enum> + </enumlist> + </option> + <option name="g"> + <argument name="grp" required="true"> + <para>Only spy on channels in which one or more of the groups + listed in <replaceable>grp</replaceable> matches one or more groups from the + <variable>SPYGROUP</variable> variable set on the channel to be spied upon.</para> + </argument> + <note><para>both <replaceable>grp</replaceable> and <variable>SPYGROUP</variable> can contain + either a single group or a colon-delimited list of groups, such + as <literal>sales:support:accounting</literal>.</para></note> + </option> + <option name="n" argsep="@"> + <para>Say the name of the person being spied on if that person has recorded + his/her name. If a context is specified, then that voicemail context will + be searched when retrieving the name, otherwise the <literal>default</literal> context + be used when searching for the name (i.e. if SIP/1000 is the channel being + spied on and no mailbox is specified, then <literal>1000</literal> will be used when searching + for the name).</para> + <argument name="mailbox" /> + <argument name="context" /> + </option> + <option name="q"> + <para>Don't play a beep when beginning to spy on a channel, or speak the + selected channel name.</para> + </option> + <option name="r"> + <para>Record the session to the monitor spool directory. An optional base for the filename + may be specified. The default is <literal>chanspy</literal>.</para> + <argument name="basename" /> + </option> + <option name="s"> + <para>Skip the playback of the channel type (i.e. SIP, IAX, etc) when + speaking the selected channel name.</para> + </option> + <option name="v"> + <argument name="value" /> + <para>Adjust the initial volume in the range from <literal>-4</literal> + to <literal>4</literal>. A negative value refers to a quieter setting.</para> + </option> + <option name="w"> + <para>Enable <literal>whisper</literal> mode, so the spying channel can talk to + the spied-on channel.</para> + </option> + <option name="W"> + <para>Enable <literal>private whisper</literal> mode, so the spying channel can + talk to the spied-on channel but cannot listen to that channel.</para> + </option> + <option name="o"> + <para>Only listen to audio coming from this channel.</para> + </option> + <option name="X"> + <para>Allow the user to exit ChanSpy to a valid single digit + numeric extension in the current context or the context + specified by the <variable>SPY_EXIT_CONTEXT</variable> channel variable. The + name of the last channel that was spied on will be stored + in the <variable>SPY_CHANNEL</variable> variable.</para> + </option> + <option name="e"> + <argument name="ext" required="true" /> + <para>Enable <emphasis>enforced</emphasis> mode, so the spying channel can + only monitor extensions whose name is in the <replaceable>ext</replaceable> : delimited + list.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>This application is used to listen to the audio from an Asterisk channel. This includes + the audio coming in and out of the channel being spied on. Only channels created by outgoing calls for the + specified extension will be selected for spying. If the optional context is not supplied, + the current channel's context will be used.</para> + <para>While spying, the following actions may be performed:</para> + <para> - Dialing <literal>#</literal> cycles the volume level.</para> + <para> - Dialing <literal>*</literal> will stop spying and look for another channel to spy on.</para> + <note><para>The <replaceable>X</replaceable> option supersedes the three features above in that if a valid + single digit extension exists in the correct context ChanSpy will exit to it. + This also disables choosing a channel based on <literal>chanprefix</literal> and a digit sequence.</para></note> + </description> + </application> + + ***/ static const char *app_chan = "ChanSpy"; -static const char *desc_chan = -" ChanSpy([chanprefix][,options]): This application is used to listen to the\n" -"audio from an Asterisk channel. This includes the audio coming in and\n" -"out of the channel being spied on. If the 'chanprefix' parameter is specified,\n" -"only channels beginning with this string will be spied upon.\n" -" While spying, the following actions may be performed:\n" -" - Dialing # cycles the volume level.\n" -" - Dialing * will stop spying and look for another channel to spy on.\n" -" - Dialing a series of digits followed by # builds a channel name to append\n" -" to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing\n" -" the digits '1234#' while spying will begin spying on the channel\n" -" 'Agent/1234'. Note that this feature will be overriden if the 'd' option\n" -" is used\n" -" Note: The X option supersedes the three features above in that if a valid\n" -" single digit extension exists in the correct context ChanSpy will\n" -" exit to it. This also disables choosing a channel based on 'chanprefix'\n" -" and a digit sequence.\n" -" Options:\n" -" b - Only spy on channels involved in a bridged call.\n" -" B - Instead of whispering on a single channel barge in on both\n" -" channels involved in the call.\n" -" d - Override the typical numeric DTMF functionality and instead\n" -" use DTMF to switch between spy modes.\n" -" 4 = spy mode\n" -" 5 = whisper mode\n" -" 6 = barge mode\n" -" g(grp) - Only spy on channels in which one or more of the groups \n" -" listed in 'grp' matches one or more groups from the\n" -" SPYGROUP variable set on the channel to be spied upon.\n" -" Note that both 'grp' and SPYGROUP can contain either a\n" -" single group or a colon-delimited list of groups, such\n" -" as 'sales:support:accounting'.\n" -" n([mailbox][@context]) - Say the name of the person being spied on if that person has recorded\n" -" his/her name. If a context is specified, then that voicemail context will\n" -" be searched when retrieving the name, otherwise the \"default\" context\n" -" will be searched. If no mailbox is specified, then the channel name will\n" -" be used when searching for the name (i.e. if SIP/1000 is the channel being\n" -" spied on and no mailbox is specified, then \"1000\" will be used when searching\n" -" for the name).\n" -" q - Don't play a beep when beginning to spy on a channel, or speak the\n" -" selected channel name.\n" -" r[(basename)] - Record the session to the monitor spool directory. An\n" -" optional base for the filename may be specified. The\n" -" default is 'chanspy'.\n" -" s - Skip the playback of the channel type (i.e. SIP, IAX, etc) when\n" -" speaking the selected channel name.\n" -" v([value]) - Adjust the initial volume in the range from -4 to 4. A\n" -" negative value refers to a quieter setting.\n" -" w - Enable 'whisper' mode, so the spying channel can talk to\n" -" the spied-on channel.\n" -" W - Enable 'private whisper' mode, so the spying channel can\n" -" talk to the spied-on channel but cannot listen to that\n" -" channel.\n" -" o - Only listen to audio coming from this channel.\n" -" X - Allow the user to exit ChanSpy to a valid single digit\n" -" numeric extension in the current context or the context\n" -" specified by the SPY_EXIT_CONTEXT channel variable. The\n" -" name of the last channel that was spied on will be stored\n" -" in the SPY_CHANNEL variable.\n" -" e(ext) - Enable 'enforced' mode, so the spying channel can\n" -" only monitor extensions whose name is in the 'ext' : \n" -" delimited list.\n" -; static const char *app_ext = "ExtenSpy"; -static const char *desc_ext = -" ExtenSpy(exten[@context][,options]): This application is used to listen to the\n" -"audio from an Asterisk channel. This includes the audio coming in and\n" -"out of the channel being spied on. Only channels created by outgoing calls for the\n" -"specified extension will be selected for spying. If the optional context is not\n" -"supplied, the current channel's context will be used.\n" -" While spying, the following actions may be performed:\n" -" - Dialing # cycles the volume level.\n" -" - Dialing * will stop spying and look for another channel to spy on.\n" -" Note: The X option superseeds the two features above in that if a valid\n" -" single digit extension exists in the correct context it ChanSpy will\n" -" exit to it.\n" -" Options:\n" -" b - Only spy on channels involved in a bridged call.\n" -" B - Instead of whispering on a single channel barge in on both\n" -" channels involved in the call.\n" -" d - Override the typical numeric DTMF functionality and instead\n" -" use DTMF to switch between spy modes.\n" -" 4 = spy mode\n" -" 5 = whisper mode\n" -" 6 = barge mode\n" -" g(grp) - Only spy on channels in which one or more of the groups \n" -" listed in 'grp' matches one or more groups from the\n" -" SPYGROUP variable set on the channel to be spied upon.\n" -" Note that both 'grp' and SPYGROUP can contain either a\n" -" single group or a colon-delimited list of groups, such\n" -" as 'sales:support:accounting'.\n" -" n([mailbox][@context]) - Say the name of the person being spied on if that person has recorded\n" -" his/her name. If a context is specified, then that voicemail context will\n" -" be searched when retrieving the name, otherwise the \"default\" context\n" -" will be searched. If no mailbox is specified, then the channel name will\n" -" be used when searching for the name (i.e. if SIP/1000 is the channel being\n" -" spied on and no mailbox is specified, then \"1000\" will be used when searching\n" -" for the name).\n" -" q - Don't play a beep when beginning to spy on a channel, or speak the\n" -" selected channel name.\n" -" r[(basename)] - Record the session to the monitor spool directory. An\n" -" optional base for the filename may be specified. The\n" -" default is 'chanspy'.\n" -" s - Skip the playback of the channel type (i.e. SIP, IAX, etc) when\n" -" speaking the selected channel name.\n" -" v([value]) - Adjust the initial volume in the range from -4 to 4. A\n" -" negative value refers to a quieter setting.\n" -" w - Enable 'whisper' mode, so the spying channel can talk to\n" -" the spied-on channel.\n" -" W - Enable 'private whisper' mode, so the spying channel can\n" -" talk to the spied-on channel but cannot listen to that\n" -" channel.\n" -" o - Only listen to audio coming from this channel.\n" -" X - Allow the user to exit ChanSpy to a valid single digit\n" -" numeric extension in the current context or the context\n" -" specified by the SPY_EXIT_CONTEXT channel variable. The\n" -" name of the last channel that was spied on will be stored\n" -" in the SPY_CHANNEL variable.\n" -; enum { OPTION_QUIET = (1 << 0), /* Quiet, no announcement */ @@ -1103,8 +1213,8 @@ static int load_module(void) { int res = 0; - res |= ast_register_application(app_chan, chanspy_exec, tdesc, desc_chan); - res |= ast_register_application(app_ext, extenspy_exec, tdesc, desc_ext); + res |= ast_register_application_xml(app_chan, chanspy_exec); + res |= ast_register_application_xml(app_ext, extenspy_exec); return res; } diff --git a/apps/app_controlplayback.c b/apps/app_controlplayback.c index f79ab6d42..4d7432d9c 100644 --- a/apps/app_controlplayback.c +++ b/apps/app_controlplayback.c @@ -33,32 +33,67 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/module.h" +/*** DOCUMENTATION + <application name="ControlPlayback" language="en_US"> + <synopsis> + Play a file with fast forward and rewind. + </synopsis> + <syntax> + <parameter name="filename" required="true" /> + <parameter name="skipms"> + <para>This is number of milliseconds to skip when rewinding or + fast-forwarding.</para> + </parameter> + <parameter name="ff"> + <para>Fast-forward when this DTMF digit is received. (defaults to <literal>#</literal>)</para> + </parameter> + <parameter name="rew"> + <para>Rewind when this DTMF digit is received. (defaults to <literal>*</literal>)</para> + </parameter> + <parameter name="stop"> + <para>Stop playback when this DTMF digit is received.</para> + </parameter> + <parameter name="pause"> + <para>Pause playback when this DTMF digit is received.</para> + </parameter> + <parameter name="restart"> + <para>Restart playback when this DTMF digit is received.</para> + </parameter> + <parameter name="options"> + <optionlist> + <option name="o"> + <argument name="time" required="true"> + <para>Start at <replaceable>time</replaceable> ms from the + beginning of the file.</para> + </argument> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>This application will play back the given <replaceable>filename</replaceable>.</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="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> + </application> + ***/ static const char *app = "ControlPlayback"; -static const char *synopsis = "Play a file with fast forward and rewind"; - -static const char *descrip = -" ControlPlayback(file[,skipms[,ff[,rew[,stop[,pause[,restart,options]]]]]]]):\n" -"This application will play back the given filename. By default, the '*' key\n" -"can be used to rewind, and the '#' key can be used to fast-forward.\n" -"Parameters:\n" -" skipms - This is number of milliseconds to skip when rewinding or\n" -" fast-forwarding.\n" -" ff - Fast-forward when this DTMF digit is received.\n" -" rew - Rewind when this DTMF digit is received.\n" -" stop - Stop playback when this DTMF digit is received.\n" -" pause - Pause playback when this DTMF digit is received.\n" -" restart - Restart playback when this DTMF digit is received.\n" -"Options:\n" -" o(#) - Start at # ms from the beginning of the file.\n" -"This application sets the following channel variables upon completion:\n" -" CPLAYBACKSTATUS - This variable contains the status of the attempt as a text\n" -" string, one of: SUCCESS | USERSTOPPED | ERROR\n" -" CPLAYBACKOFFSET - This contains the offset in ms into the file where\n" -" playback was at when it stopped. -1 is end of file.\n" -" CPLAYBACKSTOPKEY - If the playback is stopped by the user this variable contains\n" -" the key that was pressed.\n"; - enum { OPT_OFFSET = (1 << 1), }; @@ -185,7 +220,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, controlplayback_exec, synopsis, descrip); + return ast_register_application_xml(app, controlplayback_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Control Playback Application"); diff --git a/apps/app_dahdibarge.c b/apps/app_dahdibarge.c index f16b4dea6..cfa445acc 100644 --- a/apps/app_dahdibarge.c +++ b/apps/app_dahdibarge.c @@ -52,17 +52,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/utils.h" +/*** DOCUMENTATION + <application name="DAHDIBarge" language="en_US"> + <synopsis> + Barge in (monitor) DAHDI channel. + </synopsis> + <syntax> + <parameter name="channel"> + <para>Channel to barge.</para> + </parameter> + </syntax> + <description> + <para>Barges in on a specified DAHDI <replaceable>channel</replaceable> or prompts + if one is not specified. Returns <literal>-1</literal> when caller user hangs + up and is independent of the state of the channel being monitored. + </para> + </description> + </application> + ***/ static char *app = "DAHDIBarge"; -static char *synopsis = "Barge in (monitor) DAHDI channel"; - -static char *descrip = -" DAHDIBarge([channel]): Barges in on a specified DAHDI\n" -"channel or prompts if one is not specified. Returns\n" -"-1 when caller user hangs up and is independent of the\n" -"state of the channel being monitored."; - - #define CONF_SIZE 160 static int careful_write(int fd, unsigned char *data, int len) @@ -293,7 +302,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, conf_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, conf_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Barge in on DAHDI channel application"); diff --git a/apps/app_dahdiras.c b/apps/app_dahdiras.c index 1671f8bdd..879868ea5 100644 --- a/apps/app_dahdiras.c +++ b/apps/app_dahdiras.c @@ -52,17 +52,28 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/app.h" -static char *app = "DAHDIRAS"; - -static char *synopsis = "Executes DAHDI ISDN RAS application"; +/*** DOCUMENTATION + <application name="DAHDIRAS" language="en_US"> + <synopsis> + Executes DAHDI ISDN RAS application. + </synopsis> + <syntax> + <parameter name="args" required="true"> + <para>A list of parameters to pass to the pppd daemon, + separeted by <literal>,</literal> characters.</para> + </parameter> + </syntax> + <description> + <para>Executes a RAS server using pppd on the given channel. + The channel must be a clear channel (i.e. PRI source) and a DAHDI + channel to be able to use this function (No modem emulation is included).</para> + <para>Your pppd must be patched to be DAHDI aware.</para> + </description> + </application> -static char *descrip = -" DAHDIRAS(args): Executes a RAS server using pppd on the given channel.\n" -"The channel must be a clear channel (i.e. PRI source) and a DAHDI\n" -"channel to be able to use this function (No modem emulation is included).\n" -"Your pppd must be patched to be DAHDI aware. Arguments should be\n" -"separated by , characters.\n"; + ***/ +static char *app = "DAHDIRAS"; #define PPP_MAX_ARGS 32 #define PPP_EXEC "/usr/sbin/pppd" @@ -218,7 +229,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, dahdiras_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, dahdiras_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "DAHDI ISDN Remote Access Server"); diff --git a/apps/app_dahdiscan.c b/apps/app_dahdiscan.c index a8a939725..8251ffcbf 100644 --- a/apps/app_dahdiscan.c +++ b/apps/app_dahdiscan.c @@ -52,16 +52,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/options.h" +/*** DOCUMENTATION + <application name="DAHDIScan" language="en_US"> + <synopsis> + Scan DAHDI channels to monitor calls. + </synopsis> + <syntax> + <parameter name="group"> + <para>Limit scanning to a channel <replaceable>group</replaceable> by setting this option.</para> + </parameter> + </syntax> + <description> + <para>Allows a call center manager to monitor DAHDI channels in a + convenient way. Use <literal>#</literal> to select the next channel and use <literal>*</literal> to exit.</para> + </description> + </application> + ***/ static char *app = "DAHDIScan"; -static char *synopsis = "Scan DAHDI channels to monitor calls"; - -static char *descrip = -" DAHDIScan([group]) allows a call center manager to monitor DAHDI channels in\n" -"a convenient way. Use '#' to select the next channel and use '*' to exit\n" -"Limit scanning to a channel GROUP by setting the option group argument.\n"; - - #define CONF_SIZE 160 static struct ast_channel *get_dahdi_channel_locked(int num) { @@ -363,7 +371,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, conf_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, conf_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Scan DAHDI channels application"); diff --git a/apps/app_dial.c b/apps/app_dial.c index f0fd7463d..089523ef4 100644 --- a/apps/app_dial.c +++ b/apps/app_dial.c @@ -62,188 +62,396 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/global_datastores.h" #include "asterisk/dsp.h" -static char *app = "Dial"; +/*** DOCUMENTATION + <application name="Dial" language="en_US"> + <synopsis> + Attempt to connect to another device or endpoint and bridge the call. + </synopsis> + <syntax> + <parameter name="Technology/Resource" required="true" argsep="&"> + <argument name="Technology/Resource" required="true"> + <para>Specification of the device(s) to dial. These must be in the format of + <literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable> + represents a particular channel driver, and <replaceable>Resource</replaceable> + represents a resource available to that particular channel driver.</para> + </argument> + <argument name="Technology2/Resource2" required="false" multiple="true"> + <para>Optional extra devices to dial in parallel</para> + <para>If you need more then one enter them as + Technology2/Resource2&Technology3/Resourse3&.....</para> + </argument> + </parameter> + <parameter name="timeout" required="false"> + <para>Specifies the number of seconds we attempt to dial the specified devices</para> + <para>If not specified, this defaults to 136 years.</para> + </parameter> + <parameter name="options" required="false"> + <optionlist> + <option name="A"> + <argument name="x" required="true"> + <para>The file to play to the called party</para> + </argument> + <para>Play an announcement to the called party, where <replaceable>x</replaceable> is the prompt to be played</para> + </option> + <option name="C"> + <para>Reset the call detail record (CDR) for this call.</para> + </option> + <option name="c"> + <para>If the Dial() application cancels this call, always set the flag to tell the channel + driver that the call is answered elsewhere.</para> + </option> + <option name="d"> + <para>Allow the calling user to dial a 1 digit extension while waiting for + a call to be answered. Exit to that extension if it exists in the + current context, or the context defined in the <variable>EXITCONTEXT</variable> variable, + if it exists.</para> + </option> + <option name="D" argsep=":"> + <argument name="called" /> + <argument name="calling" /> + <para>Send the specified DTMF strings <emphasis>after</emphasis> the called + party has answered, but before the call gets bridged. The + <replaceable>called</replaceable> DTMF string is sent to the called party, and the + <replaceable>calling</replaceable> DTMF string is sent to the calling party. Both arguments + can be used alone.</para> + </option> + <option name="e"> + <para>Execute the <literal>h</literal> extension for peer after the call ends</para> + </option> + <option name="f"> + <para>Force the callerid of the <emphasis>calling</emphasis> channel to be set as the + extension associated with the channel using a dialplan <literal>hint</literal>. + For example, some PSTNs do not allow CallerID to be set to anything + other than the number assigned to the caller.</para> + </option> + <option name="F" argsep="^"> + <argument name="context" required="false" /> + <argument name="exten" required="false" /> + <argument name="priority" required="true" /> + <para>When the caller hangs up, transfer the called party + to the specified destination and continue execution at that location.</para> + </option> + <option name="g"> + <para>Proceed with dialplan execution at the next priority in the current extension if the + destination channel hangs up.</para> + </option> + <option name="G" argsep="^"> + <argument name="context" required="false" /> + <argument name="exten" required="false" /> + <argument name="priority" required="true" /> + <para>If the call is answered, transfer the calling party to + the specified <replaceable>priority</replaceable> and the called party to the specified + <replaceable>priority</replaceable> plus one.</para> + <note> + <para>You cannot use any additional action post answer options in conjunction with this option.</para> + </note> + </option> + <option name="h"> + <para>Allow the called party to hang up by sending the <literal>*</literal> DTMF digit.</para> + </option> + <option name="H"> + <para>Allow the calling party to hang up by hitting the <literal>*</literal> DTMF digit.</para> + </option> + <option name="i"> + <para>Asterisk will ignore any forwarding requests it may receive on this dial attempt.</para> + </option> + <option name="k"> + <para>Allow the called party to enable parking of the call by sending + the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para> + </option> + <option name="K"> + <para>Allow the calling party to enable parking of the call by sending + the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para> + </option> + <option name="L" argsep=":"> + <argument name="x" required="true"> + <para>Maximum call time, in milliseconds</para> + </argument> + <argument name="y"> + <para>Warning time, in milliseconds</para> + </argument> + <argument name="z"> + <para>Repeat time, in milliseconds</para> + </argument> + <para>Limit the call to <replaceable>x</replaceable> milliseconds. Play a warning when <replaceable>y</replaceable> milliseconds are + left. Repeat the warning every <replaceable>z</replaceable> milliseconds until time expires.</para> + <para>This option is affected by the following variables:</para> + <variablelist> + <variable name="LIMIT_PLAYAUDIO_CALLER"> + <value name="yes" default="true" /> + <value name="no" /> + <para>If set, this variable causes Asterisk to play the prompts to the caller.</para> + </variable> + <variable name="LIMIT_PLAYAUDIO_CALLEE"> + <value name="yes" /> + <value name="no" default="true"/> + <para>If set, this variable causes Asterisk to play the prompts to the callee.</para> + </variable> + <variable name="LIMIT_TIMEOUT_FILE"> + <value name="filename"/> + <para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play when the timeout is reached. + If not set, the time remaining will be announced.</para> + </variable> + <variable name="LIMIT_CONNECT_FILE"> + <value name="filename"/> + <para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play when the call begins. + If not set, the time remaining will be announced.</para> + </variable> + <variable name="LIMIT_WARNING_FILE"> + <value name="filename"/> + <para>If specified, <replaceable>filename</replaceable> specifies the sound prompt to play as + a warning when time <replaceable>x</replaceable> is reached. If not set, the time remaining will be announced.</para> + </variable> + </variablelist> + </option> + <option name="m"> + <argument name="class" required="false"/> + <para>Provide hold music to the calling party until a requested + channel answers. A specific music on hold <replaceable>class</replaceable> + (as defined in <filename>musiconhold.conf</filename>) can be specified.</para> + </option> + <option name="M" argsep="^"> + <argument name="macro" required="true"> + <para>Name of the macro that should be executed.</para> + </argument> + <argument name="arg" multiple="true"> + <para>Macro arguments</para> + </argument> + <para>Execute the specified <replaceable>macro</replaceable> for the <emphasis>called</emphasis> channel + before connecting to the calling channel. Arguments can be specified to the Macro + using <literal>^</literal> as a delimiter. The macro can set the variable + <variable>MACRO_RESULT</variable> to specify the following actions after the macro is + finished executing:</para> + <variablelist> + <variable name="MACRO_RESULT"> + <para>If set, this action will be taken after the macro finished executing.</para> + <value name="ABORT"> + Hangup both legs of the call + </value> + <value name="CONGESTION"> + Behave as if line congestion was encountered + </value> + <value name="BUSY"> + Behave as if a busy signal was encountered + </value> + <value name="CONTINUE"> + Hangup the called party and allow the calling party to continue dialplan execution at the next priority + </value> + <!-- TODO: Fix this syntax up, once we've figured out how to specify the GOTO syntax --> + <value name="GOTO:<context>^<exten>^<priority>"> + Transfer the call to the specified destination. + </value> + </variable> + </variablelist> + <note> + <para>You cannot use any additional action post answer options in conjunction + with this option. Also, pbx services are not run on the peer (called) channel, + so you will not be able to set timeouts via the TIMEOUT() function in this macro.</para> + </note> + </option> + <option name="n"> + <para>This option is a modifier for the call screening/privacy mode. (See the + <literal>p</literal> and <literal>P</literal> options.) It specifies + that no introductions are to be saved in the <directory>priv-callerintros</directory> + directory.</para> + </option> + <option name="N"> + <para>This option is a modifier for the call screening/privacy mode. It specifies + that if Caller*ID is present, do not screen the call.</para> + </option> + <option name="o"> + <para>Specify that the Caller*ID that was present on the <emphasis>calling</emphasis> channel + be set as the Caller*ID on the <emphasis>called</emphasis> channel. This was the + behavior of Asterisk 1.0 and earlier.</para> + </option> + <option name="O"> + <argument name="mode"> + <para>With <replaceable>mode</replaceable> either not specified or set to <literal>1</literal>, + the originator hanging up will cause the phone to ring back immediately.</para> + <para>With <replaceable>mode</replaceable> set to <literal>2</literal>, when the operator + flashes the trunk, it will ring their phone back.</para> + </argument> + <para>Enables <emphasis>operator services</emphasis> mode. This option only + works when bridging a DAHDI channel to another DAHDI channel + only. if specified on non-DAHDI interfaces, it will be ignored. + When the destination answers (presumably an operator services + station), the originator no longer has control of their line. + They may hang up, but the switch will not release their line + until the destination party (the operator) hangs up.</para> + </option> + <option name="p"> + <para>This option enables screening mode. This is basically Privacy mode + without memory.</para> + </option> + <option name="P"> + <argument name="x" /> + <para>Enable privacy mode. Use <replaceable>x</replaceable> as the family/key in the AstDB database if + it is provided. The current extension is used if a database family/key is not specified.</para> + </option> + <option name="r"> + <para>Indicate ringing to the calling party, even if the called party isn't actually ringing. Pass no audio to the calling + party until the called channel has answered.</para> + </option> + <option name="S"> + <argument name="x" required="true" /> + <para>Hang up the call <replaceable>x</replaceable> seconds <emphasis>after</emphasis> the called party has + answered the call.</para> + </option> + <option name="t"> + <para>Allow the called party to transfer the calling party by sending the + DTMF sequence defined in <filename>features.conf</filename>.</para> + </option> + <option name="T"> + <para>Allow the calling party to transfer the called party by sending the + DTMF sequence defined in <filename>features.conf</filename>.</para> + </option> + <option name="U" argsep="^"> + <argument name="x" required="true"> + <para>Name of the subroutine to execute via Gosub</para> + </argument> + <argument name="arg" multiple="true" required="false"> + <para>Arguments for the Gosub routine</para> + </argument> + <para>Execute via Gosub the routine <replaceable>x</replaceable> for the <emphasis>called</emphasis> channel before connecting + to the calling channel. Arguments can be specified to the Gosub + using <literal>^</literal> as a delimiter. The Gosub routine can set the variable + <variable>GOSUB_RESULT</variable> to specify the following actions after the Gosub returns.</para> + <variablelist> + <variable name="GOSUB_RESULT"> + <value name="ABORT"> + Hangup both legs of the call. + </value> + <value name="CONGESTION"> + Behave as if line congestion was encountered. + </value> + <value name="BUSY"> + Behave as if a busy signal was encountered. + </value> + <value name="CONTINUE"> + Hangup the called party and allow the calling party + to continue dialplan execution at the next priority. + </value> + <!-- TODO: Fix this syntax up, once we've figured out how to specify the GOTO syntax --> + <value name="GOTO:<context>^<exten>^<priority>"> + Transfer the call to the specified priority. Optionally, an extension, or + extension and priority can be specified. + </value> + </variable> + </variablelist> + <note> + <para>You cannot use any additional action post answer options in conjunction + with this option. Also, pbx services are not run on the peer (called) channel, + so you will not be able to set timeouts via the TIMEOUT() function in this routine.</para> + </note> + </option> + <option name="w"> + <para>Allow the called party to enable recording of the call by sending + the DTMF sequence defined for one-touch recording in <filename>features.conf</filename>.</para> + </option> + <option name="W"> + <para>Allow the calling party to enable recording of the call by sending + the DTMF sequence defined for one-touch recording in <filename>features.conf</filename>.</para> + </option> + <option name="x"> + <para>Allow the called party to enable recording of the call by sending + the DTMF sequence defined for one-touch automixmonitor in <filename>features.conf</filename>.</para> + </option> + <option name="X"> + <para>Allow the calling party to enable recording of the call by sending + the DTMF sequence defined for one-touch automixmonitor in <filename>features.conf</filename>.</para> + </option> + </optionlist> + </parameter> + <parameter name="URL"> + <para>The optional URL will be sent to the called party if the channel driver supports it.</para> + </parameter> + </syntax> + <description> + <para>This application will place calls to one or more specified channels. As soon + as one of the requested channels answers, the originating channel will be + answered, if it has not already been answered. These two channels will then + be active in a bridged call. All other channels that were requested will then + be hung up.</para> + + <para>Unless there is a timeout specified, the Dial application will wait + indefinitely until one of the called channels answers, the user hangs up, or + if all of the called channels are busy or unavailable. Dialplan executing will + continue if no requested channels can be called, or if the timeout expires. + This application will report normal termination if the originating channel + hangs up, or if the call is bridged and either of the parties in the bridge + ends the call.</para> + + <para>If the <variable>OUTBOUND_GROUP</variable> variable is set, all peer channels created by this + application will be put into that group (as in Set(GROUP()=...). + If the <variable>OUTBOUND_GROUP_ONCE</variable> variable is set, all peer channels created by this + application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP, + however, the variable will be unset after use.</para> + + <para>This application sets the following channel variables:</para> + <variablelist> + <variable name="DIALEDTIME"> + <para>This is the time from dialing a channel until when it is disconnected.</para> + </variable> + <variable name="ANSWEREDTIME"> + <para>This is the amount of time for actual call.</para> + </variable> + <variable name="DIALSTATUS"> + <para>This is the status of the call</para> + <value name="CHANUNAVAIL" /> + <value name="CONGESTION" /> + <value name="NOANSWER" /> + <value name="BUSY" /> + <value name="ANSWER" /> + <value name="CANCEL" /> + <value name="DONTCALL"> + For the Privacy and Screening Modes. + Will be set if the called party chooses to send the calling party to the 'Go Away' script. + </value> + <value name="TORTURE"> + For the Privacy and Screening Modes. + Will be set if the called party chooses to send the calling party to the 'torture' script. + </value> + <value name="INVALIDARGS" /> + </variable> + </variablelist> + </description> + </application> + <application name="RetryDial" language="en_US"> + <synopsis> + Place a call, retrying on failure allowing an optional exit extension. + </synopsis> + <syntax> + <parameter name="announce" required="true"> + <para>Filename of sound that will be played when no channel can be reached</para> + </parameter> + <parameter name="sleep" required="true"> + <para>Number of seconds to wait after a dialattempt failed before a new attempt is made</para> + </parameter> + <parameter name="retries" required="true"> + <para>Number of retries</para> + <para>When this is reached flow will continue at the next priority in the dialplan</para> + </parameter> + <parameter name="dialargs" required="true"> + <para>Same format as arguments provided to the Dial application</para> + </parameter> + </syntax> + <description> + <para>This application will attempt to place a call using the normal Dial application. + If no channel can be reached, the <replaceable>announce</replaceable> file will be played. + Then, it will wait <replaceable>sleep</replaceable> number of seconds before retrying the call. + After <replaceable>retries</replaceable> number of attempts, the calling channel will continue at the next priority in the dialplan. + If the <replaceable>retries</replaceable> setting is set to 0, this application will retry endlessly. + While waiting to retry a call, a 1 digit extension may be dialed. If that + extension exists in either the context defined in <variable>EXITCONTEXT</variable> or the current + one, The call will jump to that extension immediately. + The <replaceable>dialargs</replaceable> are specified in the same format that arguments are provided + to the Dial application.</para> + </description> + </application> + ***/ -static char *synopsis = "Place a call and connect to the current channel"; - -static char *descrip = -" Dial(Technology/resource[&Tech2/resource2...][,timeout][,options][,URL]):\n" -"This application will place calls to one or more specified channels. As soon\n" -"as one of the requested channels answers, the originating channel will be\n" -"answered, if it has not already been answered. These two channels will then\n" -"be active in a bridged call. All other channels that were requested will then\n" -"be hung up.\n" -" Unless there is a timeout specified, the Dial application will wait\n" -"indefinitely until one of the called channels answers, the user hangs up, or\n" -"if all of the called channels are busy or unavailable. Dialplan executing will\n" -"continue if no requested channels can be called, or if the timeout expires.\n\n" -" This application sets the following channel variables upon completion:\n" -" DIALEDTIME - This is the time from dialing a channel until when it\n" -" is disconnected.\n" -" ANSWEREDTIME - This is the amount of time for actual call.\n" -" DIALSTATUS - This is the status of the call:\n" -" CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL\n" -" DONTCALL | TORTURE | INVALIDARGS\n" -" For the Privacy and Screening Modes, the DIALSTATUS variable will be set to\n" -"DONTCALL if the called party chooses to send the calling party to the 'Go Away'\n" -"script. The DIALSTATUS variable will be set to TORTURE if the called party\n" -"wants to send the caller to the 'torture' script.\n" -" This application will report normal termination if the originating channel\n" -"hangs up, or if the call is bridged and either of the parties in the bridge\n" -"ends the call.\n" -" The optional URL will be sent to the called party if the channel supports it.\n" -" If the OUTBOUND_GROUP variable is set, all peer channels created by this\n" -"application will be put into that group (as in Set(GROUP()=...).\n" -" If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this\n" -"application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP,\n" -"however, the variable will be unset after use.\n\n" -" Options:\n" -" A(x) - Play an announcement to the called party, using 'x' as the file.\n" -" C - Reset the CDR for this call.\n" -" c - If DIAL cancels this call, always set the flag to tell the channel\n" -" driver that the call is answered elsewhere.\n" -" d - Allow the calling user to dial a 1 digit extension while waiting for\n" -" a call to be answered. Exit to that extension if it exists in the\n" -" current context, or the context defined in the EXITCONTEXT variable,\n" -" if it exists.\n" -" D([called][:calling]) - Send the specified DTMF strings *after* the called\n" -" party has answered, but before the call gets bridged. The 'called'\n" -" DTMF string is sent to the called party, and the 'calling' DTMF\n" -" string is sent to the calling party. Both parameters can be used\n" -" alone.\n" -" e - execute the 'h' extension for peer after the call ends. This\n" -" operation will not be performed if the peer was parked\n" -" f - Force the callerid of the *calling* channel to be set as the\n" -" extension associated with the channel using a dialplan 'hint'.\n" -" For example, some PSTNs do not allow CallerID to be set to anything\n" -" other than the number assigned to the caller.\n" -" F(context^exten^pri) - When the caller hangs up, transfer the called party\n" -" to the specified context and extension and continue execution.\n" -" g - Proceed with dialplan execution at the current extension if the\n" -" destination channel hangs up.\n" -" G(context^exten^pri) - If the call is answered, transfer the calling party to\n" -" the specified priority and the called party to the specified priority+1.\n" -" Optionally, an extension, or extension and context may be specified. \n" -" Otherwise, the current extension is used. You cannot use any additional\n" -" action post answer options in conjunction with this option.\n" -" h - Allow the called party to hang up by sending the '*' DTMF digit, or\n" -" whatever sequence was defined in the featuremap section for\n" -" 'disconnect' in features.conf\n" -" H - Allow the calling party to hang up by hitting the '*' DTMF digit, or\n" -" whatever sequence was defined in the featuremap section for\n" -" 'disconnect' in features.conf\n" -" i - Asterisk will ignore any forwarding requests it may receive on this\n" -" dial attempt.\n" -" k - Allow the called party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in the featuremap section of features.conf.\n" -" K - Allow the calling party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in the featuremap section of features.conf.\n" -" L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are\n" -" left. Repeat the warning every 'z' ms. The following special\n" -" variables can be used with this option:\n" -" * LIMIT_PLAYAUDIO_CALLER yes|no (default yes)\n" -" Play sounds to the caller.\n" -" * LIMIT_PLAYAUDIO_CALLEE yes|no\n" -" Play sounds to the callee.\n" -" * LIMIT_TIMEOUT_FILE File to play when time is up.\n" -" * LIMIT_CONNECT_FILE File to play when call begins.\n" -" * LIMIT_WARNING_FILE File to play as warning if 'y' is defined.\n" -" The default is to say the time remaining.\n" -" m([class]) - Provide hold music to the calling party until a requested\n" -" channel answers. A specific MusicOnHold class can be\n" -" specified.\n" -" M(x[^arg]) - Execute the Macro for the *called* channel before connecting\n" -" to the calling channel. Arguments can be specified to the Macro\n" -" using '^' as a delimiter. The Macro can set the variable\n" -" MACRO_RESULT to specify the following actions after the Macro is\n" -" finished executing.\n" -" * ABORT Hangup both legs of the call.\n" -" * CONGESTION Behave as if line congestion was encountered.\n" -" * BUSY Behave as if a busy signal was encountered.\n" -" * CONTINUE Hangup the called party and allow the calling party\n" -" to continue dialplan execution at the next priority.\n" -" * GOTO:<context>^<exten>^<priority> - Transfer the call to the\n" -" specified priority. Optionally, an extension, or\n" -" extension and priority can be specified.\n" -" You cannot use any additional action post answer options in conjunction\n" -" with this option. Also, pbx services are not run on the peer (called) channel,\n" -" so you will not be able to set timeouts via the TIMEOUT() function in this macro.\n" -" n - This option is a modifier for the screen/privacy mode. It specifies\n" -" that no introductions are to be saved in the priv-callerintros\n" -" directory.\n" -" N - This option is a modifier for the screen/privacy mode. It specifies\n" -" that if callerID is present, do not screen the call.\n" -" o - Specify that the CallerID that was present on the *calling* channel\n" -" be set as the CallerID on the *called* channel. This was the\n" -" behavior of Asterisk 1.0 and earlier.\n" -" O([x]) - \"Operator Services\" mode (DAHDI channel to DAHDI channel\n" -" only, if specified on non-DAHDI interface, it will be ignored).\n" -" When the destination answers (presumably an operator services\n" -" station), the originator no longer has control of their line.\n" -" They may hang up, but the switch will not release their line\n" -" until the destination party hangs up (the operator). Specified\n" -" without an arg, or with 1 as an arg, the originator hanging up\n" -" will cause the phone to ring back immediately. With a 2 specified,\n" -" when the \"operator\" flashes the trunk, it will ring their phone\n" -" back.\n" -" p - This option enables screening mode. This is basically Privacy mode\n" -" without memory.\n" -" P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if\n" -" it is provided. The current extension is used if a database\n" -" family/key is not specified.\n" -" r - Indicate ringing to the calling party. Pass no audio to the calling\n" -" party until the called channel has answered.\n" -" S(x) - Hang up the call after 'x' seconds *after* the called party has\n" -" answered the call.\n" -" t - Allow the called party to transfer the calling party by sending the\n" -" DTMF sequence defined in the blindxfer setting in the featuremap section\n" -" of features.conf.\n" -" T - Allow the calling party to transfer the called party by sending the\n" -" DTMF sequence defined in the blindxfer setting in the featuremap section\n" -" of features.conf.\n" -" U(x[^arg]) - Execute via Gosub the routine 'x' for the *called* channel before connecting\n" -" to the calling channel. Arguments can be specified to the Gosub\n" -" using '^' as a delimiter. The Gosub routine can set the variable\n" -" GOSUB_RESULT to specify the following actions after the Gosub returns.\n" -" * ABORT Hangup both legs of the call.\n" -" * CONGESTION Behave as if line congestion was encountered.\n" -" * BUSY Behave as if a busy signal was encountered.\n" -" * CONTINUE Hangup the called party and allow the calling party\n" -" to continue dialplan execution at the next priority.\n" -" * GOTO:<context>^<exten>^<priority> - Transfer the call to the\n" -" specified priority. Optionally, an extension, or\n" -" extension and priority can be specified.\n" -" You cannot use any additional action post answer options in conjunction\n" -" with this option. Also, pbx services are not run on the peer (called) channel,\n" -" so you will not be able to set timeouts via the TIMEOUT() function in this routine.\n" -" w - Allow the called party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automon setting in the featuremap section\n" -" of features.conf.\n" -" W - Allow the calling party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automon setting in the featuremap section\n" -" of features.conf.\n" -" x - Allow the called party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automixmon setting in the featuremap section\n" -" of features.conf.\n" -" X - Allow the calling party to enable recording of the call by sending\n" -" the DTMF sequence defined in the automixmon setting in the featuremap section\n" -" of features.conf.\n"; - -/* RetryDial App by Anthony Minessale II <anthmct@yahoo.com> Jan/2005 */ +static char *app = "Dial"; static char *rapp = "RetryDial"; -static char *rsynopsis = "Place a call, retrying on failure allowing optional exit extension."; -static char *rdescrip = -" RetryDial(announce,sleep,retries,dialargs): This application will attempt to\n" -"place a call using the normal Dial application. If no channel can be reached,\n" -"the 'announce' file will be played. Then, it will wait 'sleep' number of\n" -"seconds before retrying the call. After 'retries' number of attempts, the\n" -"calling channel will continue at the next priority in the dialplan. If the\n" -"'retries' setting is set to 0, this application will retry endlessly.\n" -" While waiting to retry a call, a 1 digit extension may be dialed. If that\n" -"extension exists in either the context defined in ${EXITCONTEXT} or the current\n" -"one, The call will jump to that extension immediately.\n" -" The 'dialargs' are specified in the same format that arguments are provided\n" -"to the Dial application.\n"; enum { OPT_ANNOUNCE = (1 << 0), @@ -2187,8 +2395,8 @@ static int load_module(void) else ast_add_extension2(con, 1, "s", 1, NULL, NULL, "KeepAlive", ast_strdup(""), ast_free_ptr, "app_dial"); - res = ast_register_application(app, dial_exec, synopsis, descrip); - res |= ast_register_application(rapp, retrydial_exec, rsynopsis, rdescrip); + res = ast_register_application_xml(app, dial_exec); + res |= ast_register_application_xml(rapp, retrydial_exec); return res; } diff --git a/apps/app_dictate.c b/apps/app_dictate.c index 86ccad875..b780182e3 100644 --- a/apps/app_dictate.c +++ b/apps/app_dictate.c @@ -40,11 +40,22 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/app.h" -static char *app = "Dictate"; -static char *synopsis = "Virtual Dictation Machine"; -static char *desc = " Dictate([<base_dir>[,<filename>]])\n" -"Start dictation machine using optional base dir for files.\n"; +/*** DOCUMENTATION + <application name="Dictate" language="en_US"> + <synopsis> + Virtual Dictation Machine. + </synopsis> + <syntax> + <parameter name="base_dir" /> + <parameter name="filename" /> + </syntax> + <description> + <para>Start dictation machine using optional <replaceable>base_dir</replaceable> for files.</para> + </description> + </application> + ***/ +static char *app = "Dictate"; typedef enum { DFLAG_RECORD = (1 << 0), @@ -332,7 +343,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, dictate_exec, synopsis, desc); + return ast_register_application_xml(app, dictate_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Virtual Dictation Machine"); diff --git a/apps/app_directed_pickup.c b/apps/app_directed_pickup.c index 1ead1d772..5f88df85d 100644 --- a/apps/app_directed_pickup.c +++ b/apps/app_directed_pickup.c @@ -43,23 +43,48 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define PICKUPMARK "PICKUPMARK" -static const char *app = "Pickup"; -static const char *synopsis = "Directed Call Pickup"; -static const char *descrip = -" Pickup([extension[@context][&extension2@[context]...]]): This application can\n" -"pickup any ringing channel that is calling the specified extension. If no\n" -"context is specified, the current context will be used. If you use the special\n" -"string \"PICKUPMARK\" for the context parameter, for example 10@PICKUPMARK,\n" -"this application tries to find a channel which has defined a ${PICKUPMARK}\n" -"channel variable with the same value as \"extension\" (in this example, \"10\").\n" -"When no parameter is specified, the application will pickup a channel matching\n" -"the pickup group of the active channel."; +/*** DOCUMENTATION + <application name="Pickup" language="en_US"> + <synopsis> + Directed extension call pickup. + </synopsis> + <syntax argsep="&"> + <parameter name="ext" argsep="@" required="true"> + <argument name="extension" required="true"/> + <argument name="context" /> + </parameter> + <parameter name="ext2" argsep="@" multiple="true"> + <argument name="extension2" required="true"/> + <argument name="context2"/> + </parameter> + </syntax> + <description> + <para>This application can pickup any ringing channel that is calling + the specified <replaceable>extension</replaceable>. If no <replaceable>context</replaceable> + is specified, the current context will be used. If you use the special string <literal>PICKUPMARK</literal> + for the context parameter, for example 10@PICKUPMARK, this application + tries to find a channel which has defined a <variable>PICKUPMARK</variable> + channel variable with the same value as <replaceable>extension</replaceable> + (in this example, <literal>10</literal>). When no parameter is specified, the application + will pickup a channel matching the pickup group of the active channel.</para> + </description> + </application> + <application name="PickupChan" language="en_US"> + <synopsis> + Pickup a ringing channel. + </synopsis> + <syntax> + <parameter name="channel" required="true" /> + <parameter name="channel2" multiple="true" /> + </syntax> + <description> + <para>This will pickup a specified <replaceable>channel</replaceable> if ringing.</para> + </description> + </application> + ***/ +static const char *app = "Pickup"; static const char *app2 = "PickupChan"; -static const char *synopsis2 = "Pickup a ringing channel"; -static const char *descrip2 = -" PickupChan(channel[&channel...]): This application can pickup any ringing channel\n"; - /*! \todo This application should return a result code, like PICKUPRESULT */ /* Perform actual pickup between two channels */ @@ -248,8 +273,8 @@ static int load_module(void) { int res; - res = ast_register_application(app, pickup_exec, synopsis, descrip); - res |= ast_register_application(app2, pickupchan_exec, synopsis2, descrip2); + res = ast_register_application_xml(app, pickup_exec); + res |= ast_register_application_xml(app2, pickupchan_exec); return res; } diff --git a/apps/app_directory.c b/apps/app_directory.c index b2a5741ed..2b0b6776c 100644 --- a/apps/app_directory.c +++ b/apps/app_directory.c @@ -42,50 +42,78 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/utils.h" -static char *app = "Directory"; +/*** DOCUMENTATION + <application name="Directory" language="en_US"> + <synopsis> + Provide directory of voicemail extensions. + </synopsis> + <syntax> + <parameter name="vm-context"> + <para>This is the context within voicemail.conf to use for the Directory. If not specified and + <literal>searchcontexts=no</literal> in <filename>voicemail.conf</filename>, then <literal>default</literal> + will be assumed.</para> + </parameter> + <parameter name="dial-context" required="false"> + <para>This is the dialplan context to use when looking for an + extension that the user has selected, or when jumping to the + <literal>o</literal> or <literal>a</literal> extension.</para> + </parameter> + <parameter name="options" required="false"> + <optionlist> + <option name="e"> + <para>In addition to the name, also read the extension number to the + caller before presenting dialing options.</para> + </option> + <option name="f"> + <para>Allow the caller to enter the first name of a user in the + directory instead of using the last name. If specified, the + optional number argument will be used for the number of + characters the user should enter.</para> + <argument name="n" required="true" /> + </option> + <option name="l"> + <para>Allow the caller to enter the last name of a user in the + directory. This is the default. If specified, the + optional number argument will be used for the number of + characters the user should enter.</para> + <argument name="n" required="true" /> + </option> + <option name="b"> + <para> Allow the caller to enter either the first or the last name + of a user in the directory. If specified, the optional number + argument will be used for the number of characters the user should enter.</para> + <argument name="n" required="true" /> + </option> + <option name="m"> + <para>Instead of reading each name sequentially and asking for + confirmation, create a menu of up to 8 names.</para> + </option> + <option name="p"> + <para>Pause for n milliseconds after the digits are typed. This is + helpful for people with cellphones, who are not holding the + receiver to their ear while entering DTMF.</para> + <argument name="n" required="true" /> + </option> + </optionlist> + <note><para>Only one of the <replaceable>f</replaceable>, <replaceable>l</replaceable>, or <replaceable>b</replaceable> + options may be specified. <emphasis>If more than one is specified</emphasis>, then Directory will act as + if <replaceable>b</replaceable> was specified. The number + of characters for the user to type defaults to <literal>3</literal>.</para></note> + </parameter> + </syntax> + <description> + <para>This application will present the calling channel with a directory of extensions from which they can search + by name. The list of names and corresponding extensions is retrieved from the + voicemail configuration file, <filename>voicemail.conf</filename>.</para> + <para>This application will immediately exit if one of the following DTMF digits are + received and the extension to jump to exists:</para> + <para><literal>0</literal> - Jump to the 'o' extension, if it exists.</para> + <para><literal>*</literal> - Jump to the 'a' extension, if it exists.</para> + </description> + </application> -static char *synopsis = "Provide directory of voicemail extensions"; -static char *descrip = -" Directory([vm-context][,dial-context[,options]]): This application will present\n" -"the calling channel with a directory of extensions from which they can search\n" -"by name. The list of names and corresponding extensions is retrieved from the\n" -"voicemail configuration file, voicemail.conf.\n" -" This application will immediately exit if one of the following DTMF digits are\n" -"received and the extension to jump to exists:\n" -" 0 - Jump to the 'o' extension, if it exists.\n" -" * - Jump to the 'a' extension, if it exists.\n\n" -" Parameters:\n" -" vm-context - This is the context within voicemail.conf to use for the\n" -" Directory. If not specified and searchcontexts=no in\n" -" voicemail.conf, then \"default\" will be assumed.\n" -" Otherwise, in not specified, all contexts will be searched.\n" -" dial-context - This is the dialplan context to use when looking for an\n" -" extension that the user has selected, or when jumping to the\n" -" 'o' or 'a' extension.\n\n" -" Options:\n" -" e In addition to the name, also read the extension number to the\n" -" caller before presenting dialing options.\n" -" f[(<n>)] Allow the caller to enter the first name of a user in the\n" -" directory instead of using the last name. If specified, the\n" -" optional number argument will be used for the number of\n" -" characters the user should enter.\n" -" l[(<n>)] Allow the caller to enter the last name of a user in the\n" -" directory. This is the default. If specified, the\n" -" optional number argument will be used for the number of\n" -" characters the user should enter.\n" -" b[(<n>)] Allow the caller to enter either the first or the last name\n" -" of a user in the directory. If specified, the optional number\n" -" argument will be used for the number of characters the user\n" -" should enter.\n" -" m Instead of reading each name sequentially and asking for\n" -" confirmation, create a menu of up to 8 names.\n" -" p(<n>) Pause for n milliseconds after the digits are typed. This is\n" -" helpful for people with cellphones, who are not holding the\n" -" receiver to their ear while entering DTMF.\n" -"\n" -" Only one of the f, l, or b options may be specified. If more than one is\n" -" specified, then Directory will act as if 'b' was specified. The number\n" -" of characters for the user to type defaults to 3.\n"; + ***/ +static char *app = "Directory"; /* For simplicity, I'm keeping the format compatible with the voicemail config, but i'm open to suggestions for isolating it */ @@ -809,7 +837,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, directory_exec, synopsis, descrip); + return ast_register_application_xml(app, directory_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Extension Directory"); diff --git a/apps/app_disa.c b/apps/app_disa.c index 2ed5e15f7..515bdce9c 100644 --- a/apps/app_disa.c +++ b/apps/app_disa.c @@ -45,51 +45,69 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/callerid.h" #include "asterisk/stringfields.h" +/*** DOCUMENTATION + <application name="DISA" language="en_US"> + <synopsis> + Direct Inward System Access. + </synopsis> + <syntax> + <parameter name="passcode|filename" required="true"> + <para>If you need to present a DISA dialtone without entering a password, + simply set <replaceable>passcode</replaceable> to <literal>no-password</literal></para> + <para>You may specified a <replaceable>filename</replaceable> instead of a + <replaceable>passcode</replaceable>, this filename must contain individual passcodes</para> + </parameter> + <parameter name="context"> + <para>Specifies the dialplan context in which the user-entered extension + will be matched. If no context is specified, the DISA application defaults + to the <literal>disa</literal> context. Presumably a normal system will have a special + context set up for DISA use with some or a lot of restrictions.</para> + </parameter> + <parameter name="cid"> + <para>Specifies a new (different) callerid to be used for this call.</para> + </parameter> + <parameter name="mailbox" argsep="@"> + <para>Will cause a stutter-dialtone (indication <emphasis>dialrecall</emphasis>) + to be used, if the specified mailbox contains any new messages.</para> + <argument name="mailbox" required="true" /> + <argument name="context" required="false" /> + </parameter> + <parameter name="options"> + <optionlist> + <option name="n"> + <para>The DISA application will not answer initially.</para> + </option> + <option name="p"> + <para>The extension entered will be considered complete when a <literal>#</literal> + is entered.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>The DISA, Direct Inward System Access, application allows someone from + outside the telephone switch (PBX) to obtain an <emphasis>internal</emphasis> system + dialtone and to place calls from it as if they were placing a call from + within the switch. + DISA plays a dialtone. The user enters their numeric passcode, followed by + the pound sign <literal>#</literal>. If the passcode is correct, the user is then given + system dialtone within <replaceable>context</replaceable> on which a call may be placed. + If the user enters an invalid extension and extension <literal>i</literal> exists in the specified + <replaceable>context</replaceable>, it will be used. + </para> + <para>Be aware that using this may compromise the security of your PBX.</para> + <para>The arguments to this application (in <filename>extensions.conf</filename>) allow either + specification of a single global <replaceable>passcode</replaceable> (that everyone uses), or + individual passcodes contained in a file (<replaceable>filename</replaceable>).</para> + <para>The file that contains the passcodes (if used) allows a complete + specification of all of the same arguments available on the command + line, with the sole exception of the options. The file may contain blank + lines, or comments starting with <literal>#</literal> or <literal>;</literal>.</para> + </description> + </application> + ***/ static char *app = "DISA"; -static char *synopsis = "DISA (Direct Inward System Access)"; - -static char *descrip = -"DISA(<numeric passcode>[,<context>[,<cid>[,mailbox[,options]]]]) or\n" -"DISA(<filename>[,,,,options])\n" -"The DISA, Direct Inward System Access, application allows someone from \n" -"outside the telephone switch (PBX) to obtain an \"internal\" system \n" -"dialtone and to place calls from it as if they were placing a call from \n" -"within the switch.\n" -"DISA plays a dialtone. The user enters their numeric passcode, followed by\n" -"the pound sign (#). If the passcode is correct, the user is then given\n" -"system dialtone within <context> on which a call may be placed. If the user\n" -"enters an invalid extension and extension \"i\" exists in the specified\n" -"context, it will be used.\n" -"\n" -"If you need to present a DISA dialtone without entering a password, simply\n" -"set <passcode> to \"no-password\".\n" -"\n" -"Be aware that using this may compromise the security of your PBX.\n" -"\n" -"The arguments to this application (in extensions.conf) allow either\n" -"specification of a single global passcode (that everyone uses), or\n" -"individual passcodes contained in a file.\n" -"\n" -"The file that contains the passcodes (if used) allows a complete\n" -"specification of all of the same arguments available on the command\n" -"line, with the sole exception of the options. The file may contain blank\n" -"lines, or comments starting with \"#\" or \";\".\n" -"\n" -"<context> specifies the dialplan context in which the user-entered extension\n" -"will be matched. If no context is specified, the DISA application defaults\n" -"the context to \"disa\". Presumably a normal system will have a special\n" -"context set up for DISA use with some or a lot of restrictions.\n" -"\n" -"<cid> specifies a new (different) callerid to be used for this call.\n" -"\n" -"<mailbox[@context]> will cause a stutter-dialtone (indication \"dialrecall\")\n" -"to be used, if the specified mailbox contains any new messages.\n" -"\n" -"The following options are available:\n" -" n - the DISA application will not answer initially.\n" -" p - the extension entered will be considered complete when a '#' is entered.\n"; - enum { NOANSWER_FLAG = (1 << 0), POUND_TO_END_FLAG = (1 << 1), @@ -363,7 +381,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, disa_exec, synopsis, descrip) ? + return ast_register_application_xml(app, disa_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_dumpchan.c b/apps/app_dumpchan.c index 7742633fd..e2300dbea 100644 --- a/apps/app_dumpchan.c +++ b/apps/app_dumpchan.c @@ -36,15 +36,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/channel.h" -static char *app = "DumpChan"; -static char *synopsis = "Dump Info About The Calling Channel"; -static char *desc = - " DumpChan([<min_verbose_level>])\n" - "Displays information on channel and listing of all channel\n" - "variables. If min_verbose_level is specified, output is only\n" - "displayed when the verbose level is currently set to that number\n" - "or greater. \n"; +/*** DOCUMENTATION + <application name="DumpChan" language="en_US"> + <synopsis> + Dump Info About The Calling Channel. + </synopsis> + <syntax> + <parameter name="level"> + <para>Minimun verbose level</para> + </parameter> + </syntax> + <description> + <para>Displays information on channel and listing of all channel + variables. If <replaceable>level</replaceable> is specified, output is only + displayed when the verbose level is currently set to that number + or greater.</para> + </description> + </application> + ***/ +static char *app = "DumpChan"; static int serialize_showchan(struct ast_channel *c, char *buf, size_t size) { @@ -156,7 +167,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, dumpchan_exec, synopsis, desc); + return ast_register_application_xml(app, dumpchan_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Dump Info About The Calling Channel"); diff --git a/apps/app_echo.c b/apps/app_echo.c index 76c701cd7..8b0d21f06 100644 --- a/apps/app_echo.c +++ b/apps/app_echo.c @@ -33,15 +33,20 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/channel.h" -static char *app = "Echo"; - -static char *synopsis = "Echo audio, video, or DTMF back to the calling party"; - -static char *descrip = -" Echo(): This application will echo any audio, video, or DTMF frames read from\n" -"the calling channel back to itself. If the DTMF digit '#' is received, the\n" -"application will exit.\n"; +/*** DOCUMENTATION + <application name="Echo" language="en_US"> + <synopsis> + Echo audio, video, DTMF back to the calling party + </synopsis> + <syntax /> + <description> + <para>Echos back any audio, video or DTMF frames read from the calling + channel back to itself. Note: If '#' detected application exits</para> + </description> + </application> + ***/ +static char *app = "Echo"; static int echo_exec(struct ast_channel *chan, void *data) { @@ -81,7 +86,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, echo_exec, synopsis, descrip); + return ast_register_application_xml(app, echo_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Simple Echo Application"); diff --git a/apps/app_exec.c b/apps/app_exec.c index 285b8b2f0..b4a66962e 100644 --- a/apps/app_exec.c +++ b/apps/app_exec.c @@ -36,6 +36,80 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="Exec" language="en_US"> + <synopsis> + Executes dialplan application. + </synopsis> + <syntax> + <parameter name="appname" required="true" hasparams="true"> + <para>Application name and arguments of the dialplan application to execute.</para> + <argument name="arguments" required="true" /> + </parameter> + </syntax> + <description> + <para>Allows an arbitrary application to be invoked even when not + hardcoded into the dialplan. If the underlying application + terminates the dialplan, or if the application cannot be found, + Exec will terminate the dialplan.</para> + <para>To invoke external applications, see the application System. + If you would like to catch any error instead, see TryExec.</para> + </description> + </application> + <application name="TryExec" language="en_US"> + <synopsis> + Executes dialplan application, always returning. + </synopsis> + <syntax> + <parameter name="appname" required="true" hasparams="true"> + <argument name="arguments" required="true" /> + </parameter> + </syntax> + <description> + <para>Allows an arbitrary application to be invoked even when not + hardcoded into the dialplan. To invoke external applications + see the application System. Always returns to the dialplan. + The channel variable TRYSTATUS will be set to one of: + </para> + <variablelist> + <variable name="TRYSTATUS"> + <value name="SUCCESS"> + If the application returned zero. + </value> + <value name="FAILED"> + If the application returned non-zero. + </value> + <value name="NOAPP"> + If the application was not found or was not specified. + </value> + </variable> + </variablelist> + </description> + </application> + <application name="ExecIf" language="en_US"> + <synopsis> + Executes dialplan application, conditionally. + </synopsis> + <syntax argsep="?"> + <parameter name="expression" required="true" /> + <parameter name="execapp" required="true" argsep=":"> + <argument name="appiftrue" required="true" hasparams="true"> + <argument name="args" required="true" /> + </argument> + <argument name="appiffalse" required="false" hasparams="true"> + <argument name="args" required="true" /> + </argument> + </parameter> + </syntax> + <description> + <para>If <replaceable>expr</replaceable> is true, execute and return the + result of <replaceable>appiftrue(args)</replaceable>.</para> + <para>If <replaceable>expr</replaceable> is true, but <replaceable>appiftrue</replaceable> is not found, + then the application will return a non-zero value.</para> + </description> + </application> + ***/ + /* Maximum length of any variable */ #define MAXRESULT 1024 @@ -52,35 +126,8 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") */ static char *app_exec = "Exec"; -static char *exec_synopsis = "Executes dialplan application"; -static char *exec_descrip = -" Exec(appname(arguments)):\n" -"Allows an arbitrary application to be invoked even when not\n" -"hardcoded into the dialplan. If the underlying application\n" -"terminates the dialplan, or if the application cannot be found,\n" -"Exec will terminate the dialplan.\n" -" To invoke external applications, see the application System.\n" -" If you would like to catch any error instead, see TryExec.\n"; - static char *app_tryexec = "TryExec"; -static char *tryexec_synopsis = "Executes dialplan application, always returning"; -static char *tryexec_descrip = -" TryExec(appname(arguments)):\n" -"Allows an arbitrary application to be invoked even when not\n" -"hardcoded into the dialplan. To invoke external applications\n" -"see the application System. Always returns to the dialplan.\n" -"The channel variable TRYSTATUS will be set to one of:\n" -" SUCCESS if the application returned zero\n" -" FAILED if the application returned non-zero\n" -" NOAPP if the application was not found or was not specified\n"; - static char *app_execif = "ExecIf"; -static char *execif_synopsis = "Executes dialplan application, conditionally"; -static char *execif_descrip = -" ExecIF (<expr>?<appiftrue>(<args>)[:<appiffalse>(<args>)])\n" -"If <expr> is true, execute and return the result of <appiftrue>(<args>).\n" -"If <expr> is true, but <appiftrue> is not found, then the application\n" -"will return a non-zero value.\n"; static int exec_exec(struct ast_channel *chan, void *data) { @@ -237,9 +284,9 @@ static int unload_module(void) static int load_module(void) { - int res = ast_register_application(app_exec, exec_exec, exec_synopsis, exec_descrip); - res |= ast_register_application(app_tryexec, tryexec_exec, tryexec_synopsis, tryexec_descrip); - res |= ast_register_application(app_execif, execif_exec, execif_synopsis, execif_descrip); + int res = ast_register_application_xml(app_exec, exec_exec); + res |= ast_register_application_xml(app_tryexec, tryexec_exec); + res |= ast_register_application_xml(app_execif, execif_exec); return res; } diff --git a/apps/app_fax.c b/apps/app_fax.c index 9d72f3fe1..41d76b4bf 100644 --- a/apps/app_fax.c +++ b/apps/app_fax.c @@ -41,60 +41,105 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/manager.h" -static char *app_sndfax_name = "SendFAX"; -static char *app_sndfax_synopsis = "Send a FAX"; -static char *app_sndfax_desc = -" SendFAX(filename[|options]):\n" -"Send a given TIFF file to the channel as a FAX.\n" -"The option string may contain zero or more of the following characters:\n" -" 'a' - makes the application behave as an answering machine\n" -" The default behaviour is to behave as a calling machine.\n" -"\n" -"This application uses following variables:\n" -" LOCALSTATIONID to identify itself to the remote end.\n" -" LOCALHEADERINFO to generate a header line on each page.\n" -"\n" -"This application sets the following channel variables upon completion:\n" -" FAXSTATUS - status of operation:\n" -" SUCCESS | FAILED\n" -" FAXERROR - Error when FAILED\n" -" FAXMODE - Mode used:\n" -" audio | T38\n" -" REMOTESTATIONID - CSID of the remote side.\n" -" FAXPAGES - number of pages sent.\n" -" FAXBITRATE - transmition rate.\n" -" FAXRESOLUTION - resolution.\n" -"\n" -"Returns -1 in case of user hang up or any channel error.\n" -"Returns 0 on success.\n"; +/*** DOCUMENTATION + <application name="SendFAX" language="en_US"> + <synopsis> + Send a Fax + </synopsis> + <syntax> + <parameter name="filename" required="true"> + <para>Filename of TIFF file to fax</para> + </parameter> + <parameter name="a" required="false"> + <para>Makes the application behave as the answering machine</para> + <para>(Default behavior is as calling machine)</para> + </parameter> + </syntax> + <description> + <para>Send a given TIFF file to the channel as a FAX.</para> + <para>This application sets the following channel variables:</para> + <variablelist> + <variable name="LOCALSTATIONID"> + <para>To identify itself to the remote end</para> + </variable> + <variable name="LOCALHEADERINFO"> + <para>To generate a header line on each page</para> + </variable> + <variable name="FAXSTATUS"> + <value name="SUCCESS"/> + <value name="FAILED"/> + </variable> + <variable name="FAXERROR"> + <para>Cause of failure</para> + </variable> + <variable name="REMOTESTATIONID"> + <para>The CSID of the remote side</para> + </variable> + <variable name="FAXPAGES"> + <para>Number of pages sent</para> + </variable> + <variable name="FAXBITRATE"> + <para>Transmission rate</para> + </variable> + <variable name="FAXRESOLUTION"> + <para>Resolution of sent fax</para> + </variable> + </variablelist> + </description> + </application> + <application name="ReceiveFAX" language="en_US"> + <synopsis> + Receive a Fax + </synopsis> + <syntax> + <parameter name="filename" required="true"> + <para>Filename of TIFF file save incoming fax</para> + </parameter> + <parameter name="c" required="false"> + <para>Makes the application behave as the calling machine</para> + <para>(Default behavior is as answering machine)</para> + </parameter> + </syntax> + <description> + <para>Receives a FAX from the channel into the given filename + overwriting the file if it already exists.</para> + <para>File created will be in TIFF format.</para> + + <para>This application sets the following channel variables:</para> + <variablelist> + <variable name="LOCALSTATIONID"> + <para>To identify itself to the remote end</para> + </variable> + <variable name="LOCALHEADERINFO"> + <para>To generate a header line on each page</para> + </variable> + <variable name="FAXSTATUS"> + <value name="SUCCESS"/> + <value name="FAILED"/> + </variable> + <variable name="FAXERROR"> + <para>Cause of failure</para> + </variable> + <variable name="REMOTESTATIONID"> + <para>The CSID of the remote side</para> + </variable> + <variable name="FAXPAGES"> + <para>Number of pages sent</para> + </variable> + <variable name="FAXBITRATE"> + <para>Transmission rate</para> + </variable> + <variable name="FAXRESOLUTION"> + <para>Resolution of sent fax</para> + </variable> + </variablelist> + </description> + </application> + + ***/ +static char *app_sndfax_name = "SendFAX"; static char *app_rcvfax_name = "ReceiveFAX"; -static char *app_rcvfax_synopsis = "Receive a FAX"; -static char *app_rcvfax_desc = -" ReceiveFAX(filename[|options]):\n" -"Receives a fax from the channel into the given filename overwriting\n" -"the file if it already exists. File created will have TIFF format.\n" -"The option string may contain zero or more of the following characters:\n" -" 'c' -- makes the application behave as a calling machine\n" -" The default behaviour is to behave as an answering machine.\n" -"\n" -"This application uses following variables:\n" -" LOCALSTATIONID to identify itself to the remote end.\n" -" LOCALHEADERINFO to generate a header line on each page.\n" -"\n" -"This application sets the following channel variables upon completion:\n" -" FAXSTATUS - status of operation:\n" -" SUCCESS | FAILED\n" -" FAXERROR - Error when FAILED\n" -" FAXMODE - Mode used:\n" -" audio | T38\n" -" REMOTESTATIONID - CSID of the remote side.\n" -" FAXPAGES - number of pages sent.\n" -" FAXBITRATE - transmition rate.\n" -" FAXRESOLUTION - resolution.\n" -"\n" -"Returns -1 in case of user hang up or any channel error.\n" -"Returns 0 on success.\n"; #define MAX_SAMPLES 240 @@ -753,8 +798,8 @@ static int load_module(void) { int res ; - res = ast_register_application(app_sndfax_name, sndfax_exec, app_sndfax_synopsis, app_sndfax_desc); - res |= ast_register_application(app_rcvfax_name, rcvfax_exec, app_rcvfax_synopsis, app_rcvfax_desc); + res = ast_register_application_xml(app_sndfax_name, sndfax_exec); + res |= ast_register_application_xml(app_rcvfax_name, rcvfax_exec); /* The default SPAN message handler prints to stderr. It is something we do not want */ span_set_message_handler(NULL); diff --git a/apps/app_festival.c b/apps/app_festival.c index 4a929a3e5..82f1bddc5 100644 --- a/apps/app_festival.c +++ b/apps/app_festival.c @@ -53,15 +53,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define MAXLEN 180 #define MAXFESTLEN 2048 -static char *app = "Festival"; - -static char *synopsis = "Say text to the user"; - -static char *descrip = -" Festival(text[,intkeys]): Connect to Festival, send the argument, get back the waveform,\n" -"play it to the user, allowing any given interrupt keys to immediately terminate and return\n" -"the value, or 'any' to allow any number back (useful in dialplan)\n"; +/*** DOCUMENTATION + <application name="Festival" language="en_US"> + <synopsis> + Say text to the user. + </synopsis> + <syntax> + <parameter name="text" required="true" /> + <parameter name="intkeys" /> + </syntax> + <description> + <para>Connect to Festival, send the argument, get back the waveform, play it to the user, + allowing any given interrupt keys to immediately terminate and return the value, or + <literal>any</literal> to allow any number back (useful in dialplan).</para> + </description> + </application> + ***/ +static char *app = "Festival"; static char *socket_receive_file_to_buff(int fd, int *size) { @@ -526,7 +535,7 @@ static int load_module(void) return AST_MODULE_LOAD_DECLINE; } ast_config_destroy(cfg); - return ast_register_application(app, festival_exec, synopsis, descrip); + return ast_register_application_xml(app, festival_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Simple Festival Interface"); diff --git a/apps/app_getcpeid.c b/apps/app_getcpeid.c index 6ff051899..9c1009242 100644 --- a/apps/app_getcpeid.c +++ b/apps/app_getcpeid.c @@ -36,15 +36,20 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/adsi.h" +/*** DOCUMENTATION + <application name="GetCPEID" language="en_US"> + <synopsis> + Get ADSI CPE ID. + </synopsis> + <syntax /> + <description> + <para>Obtains and displays ADSI CPE ID and other information in order + to properly setup <filename>dahdi.conf</filename> for on-hook operations.</para> + </description> + </application> + ***/ static char *app = "GetCPEID"; -static char *synopsis = "Get ADSI CPE ID"; - -static char *descrip = -" GetCPEID(): Obtains and displays ADSI CPE ID and other information in order\n" -"to properly setup dahdi.conf for on-hook operations.\n"; - - static int cpeid_setstatus(struct ast_channel *chan, char *stuff[], int voice) { int justify[5] = { ADSI_JUST_CENT, ADSI_JUST_LEFT, ADSI_JUST_LEFT, ADSI_JUST_LEFT }; @@ -124,7 +129,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, cpeid_exec, synopsis, descrip); + return ast_register_application_xml(app, cpeid_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Get ADSI CPE ID"); diff --git a/apps/app_ices.c b/apps/app_ices.c index 1da17369b..4126ad7e9 100644 --- a/apps/app_ices.c +++ b/apps/app_ices.c @@ -45,21 +45,30 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/translate.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="ICES" language="en_US"> + <synopsis> + Encode and stream using 'ices'. + </synopsis> + <syntax> + <parameter name="config" required="true"> + <para>ICES configuration file.</para> + </parameter> + </syntax> + <description> + <para>Streams to an icecast server using ices (available separately). + A configuration file must be supplied for ices (see contrib/asterisk-ices.xml).</para> + <note><para>ICES version 2 cient and server required.</para></note> + </description> + </application> + + ***/ + #define path_BIN "/usr/bin/" #define path_LOCAL "/usr/local/bin/" static char *app = "ICES"; -static char *synopsis = "Encode and stream using 'ices'"; - -static char *descrip = -" ICES(config.xml) Streams to an icecast server using ices\n" -"(available separately). A configuration file must be supplied\n" -"for ices (see contrib/asterisk-ices.xml). \n" -"\n" -"- ICES version 2 cient and server required.\n"; - - static int icesencode(char *filename, int fd) { int res; @@ -199,7 +208,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, ices_exec, synopsis, descrip); + return ast_register_application_xml(app, ices_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Encode and Stream via icecast and ices"); diff --git a/apps/app_image.c b/apps/app_image.c index ac44495e3..e74397c0d 100644 --- a/apps/app_image.c +++ b/apps/app_image.c @@ -35,16 +35,35 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "SendImage"; -static char *synopsis = "Send an image file"; - -static char *descrip = -" SendImage(filename): Sends an image on a channel.\n" -"Result of transmission will be stored in SENDIMAGESTATUS\n" -"channel variable:\n" -" SUCCESS Transmission succeeded\n" -" FAILURE Transmission failed\n" -" UNSUPPORTED Image transmission not supported by channel\n"; - +/*** DOCUMENTATION + <application name="SendImage" language="en_US"> + <synopsis> + Sends an image file. + </synopsis> + <syntax> + <parameter name="filename" required="true"> + <para>Path of the filename (image) to send.</para> + </parameter> + </syntax> + <description> + <para>Send an image file on a channel supporting it.</para> + <para>Result of transmission will be stored in <variable>SENDIMAGESTATUS</variable></para> + <variablelist> + <variable name="SENDIMAGESTATUS"> + <value name="SUCCESS"> + Transmission succeeded. + </value> + <value name="FAILURE"> + Transmission failed. + </value> + <value name="UNSUPPORTED"> + Image transmission not supported by channel. + </value> + </variable> + </variablelist> + </description> + </application> + ***/ static int sendimage_exec(struct ast_channel *chan, void *data) { @@ -76,7 +95,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, sendimage_exec, synopsis, descrip); + return ast_register_application_xml(app, sendimage_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Image Transmission Application"); diff --git a/apps/app_jack.c b/apps/app_jack.c index 4da4c9f8b..14546b3c4 100644 --- a/apps/app_jack.c +++ b/apps/app_jack.c @@ -73,18 +73,46 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") " running.\n" \ " c(<name>) - By default, Asterisk will use the channel name for the jack client\n" \ " name. Use this option to specify a custom client name.\n" - +/*** DOCUMENTATION + <application name="JACK" language="en_US"> + <synopsis> + Jack Audio Connection Kit + </synopsis> + <syntax> + <parameter name="options" required="false"> + <optionlist> + <option name="s"> + <argument name="name" required="true"> + <para>Connect to the specified jack server name</para> + </argument> + </option> + <option name="i"> + <argument name="name" required="true"> + <para>Connect the output port that gets created to the specified jack input port</para> + </argument> + </option> + <option name="o"> + <argument name="name" required="true"> + <para>Connect the input port that gets created to the specified jack output port</para> + </argument> + </option> + <option name="c"> + <argument name="name" required="true"> + <para>By default, Asterisk will use the channel name for the jack client name.</para> + <para>Use this option to specify a custom client name.</para> + </argument> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>When executing this application, two jack ports will be created; + one input and one output. Other applications can be hooked up to + these ports to access audio coming from, or being send to the channel.</para> + </description> + </application> + ***/ static char *jack_app = "JACK"; -static char *jack_synopsis = -"JACK (Jack Audio Connection Kit) Application"; -static char *jack_desc = -"JACK([options])\n" -" When this application is executed, two jack ports will be created; one input\n" -"and one output. Other applications can be hooked up to these ports to access\n" -"the audio coming from, or being sent to the channel.\n" -" Valid options:\n" -COMMON_OPTIONS -""; struct jack_data { AST_DECLARE_STRING_FIELDS( @@ -982,7 +1010,7 @@ static int unload_module(void) static int load_module(void) { - if (ast_register_application(jack_app, jack_exec, jack_synopsis, jack_desc)) { + if (ast_register_application_xml(jack_app, jack_exec)) { return AST_MODULE_LOAD_DECLINE; } diff --git a/apps/app_milliwatt.c b/apps/app_milliwatt.c index 89063096c..4c6a9ea4c 100644 --- a/apps/app_milliwatt.c +++ b/apps/app_milliwatt.c @@ -37,16 +37,29 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/pbx.h" -static char *app = "Milliwatt"; - -static char *synopsis = "Generate a Constant 1004Hz tone at 0dbm (mu-law)"; +/*** DOCUMENTATION + <application name="Milliwatt" language="en_US"> + <synopsis> + Generate a Constant 1004Hz tone at 0dbm (mu-law). + </synopsis> + <syntax> + <parameter name="options"> + <optionlist> + <option name="o"> + <para>Generate the tone at 1000Hz like previous version.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>Previous versions of this application generated the tone at 1000Hz. If for + some reason you would prefer that behavior, supply the <literal>o</literal> option to get the + old behavior.</para> + </description> + </application> + ***/ -static char *descrip = -" Milliwatt([options]): Generate a Constant 1004Hz tone at 0dbm.\n" -"Previous versions of this application generated the tone at 1000Hz. If for\n" -"some reason you would prefer that behavior, supply the 'o' option to get the\n" -"old behavior.\n" -""; +static char *app = "Milliwatt"; static char digital_milliwatt[] = {0x1e,0x0b,0x0b,0x1e,0x9e,0x8b,0x8b,0x9e} ; @@ -161,7 +174,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, milliwatt_exec, synopsis, descrip); + return ast_register_application_xml(app, milliwatt_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Digital Milliwatt (mu-law) Test Application"); diff --git a/apps/app_mixmonitor.c b/apps/app_mixmonitor.c index 0adaa62fe..2955455d3 100644 --- a/apps/app_mixmonitor.c +++ b/apps/app_mixmonitor.c @@ -46,38 +46,78 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/channel.h" +/*** DOCUMENTATION + <application name="MixMonitor" language="en_US"> + <synopsis> + Record a call and mix the audio during the recording. + </synopsis> + <syntax> + <parameter name="file" required="true" argsep="."> + <argument name="filename" required="true"> + <para>If <replaceable>filename</replaceable> is an absolute path, uses that path, otherwise + creates the file in the configured monitoring directory from <filename>asterisk.conf.</filename></para> + </argument> + <argument name="extension" required="true" /> + </parameter> + <parameter name="options"> + <optionlist> + <option name="a"> + <para>Append to the file instead of overwriting it.</para> + </option> + <option name="b"> + <para>Only save audio to the file while the channel is bridged.</para> + <note><para>Does not include conferences or sounds played to each bridged party</para></note> + </option> + <option name="v"> + <para>Adjust the <emphasis>heard</emphasis> volume by a factor of <replaceable>x</replaceable> + (range <literal>-4</literal> to <literal>4</literal>)</para> + <argument name="x" required="true" /> + </option> + <option name="V"> + <para>Adjust the <emphasis>spoken</emphasis> volume by a factor + of <replaceable>x</replaceable> (range <literal>-4</literal> to <literal>4</literal>)</para> + <argument name="x" required="true" /> + </option> + <option name="W"> + <para>Adjust both, <emphasis>heard and spoken</emphasis> volumes by a factor + of <replaceable>x</replaceable> (range <literal>-4</literal> to <literal>4</literal>)</para> + <argument name="x" required="true" /> + </option> + </optionlist> + </parameter> + <parameter name="command"> + <para>Will be executed when the recording is over.</para> + <para>Any strings matching <literal>^{X}</literal> will be unescaped to <variable>X</variable>.</para> + <para>All variables will be evaluated at the time MixMonitor is called.</para> + </parameter> + </syntax> + <description> + <para>Records the audio on the current channel to the specified file.</para> + <variablelist> + <variable name="MIXMONITOR_FILENAME"> + <para>Will contain the filename used to record.</para> + </variable> + </variablelist> + </description> + </application> + <application name="StopMixMonitor" language="en_US"> + <synopsis> + Stop recording a call through MixMonitor. + </synopsis> + <syntax /> + <description> + <para>Stops the audio recording that was started with a call to <literal>MixMonitor()</literal> + on the current channel.</para> + </description> + </application> + + ***/ + #define get_volfactor(x) x ? ((x > 0) ? (1 << x) : ((1 << abs(x)) * -1)) : 0 static const char *app = "MixMonitor"; -static const char *synopsis = "Record a call and mix the audio during the recording"; -static const char *desc = "" -" MixMonitor(<file>.<ext>[,<options>[,<command>]]):\n" -"Records the audio on the current channel to the specified file.\n" -"If the filename is an absolute path, uses that path, otherwise\n" -"creates the file in the configured monitoring directory from\n" -"asterisk.conf.\n\n" -"Valid options:\n" -" a - Append to the file instead of overwriting it.\n" -" b - Only save audio to the file while the channel is bridged.\n" -" Note: Does not include conferences or sounds played to each bridged\n" -" party.\n" -" v(<x>) - Adjust the heard volume by a factor of <x> (range -4 to 4)\n" -" V(<x>) - Adjust the spoken volume by a factor of <x> (range -4 to 4)\n" -" W(<x>) - Adjust the both heard and spoken volumes by a factor of <x>\n" -" (range -4 to 4)\n\n" -"<command> will be executed when the recording is over\n" -"Any strings matching ^{X} will be unescaped to ${X}.\n" -"All variables will be evaluated at the time MixMonitor is called.\n" -"The variable MIXMONITOR_FILENAME will contain the filename used to record.\n" -""; static const char *stop_app = "StopMixMonitor"; -static const char *stop_synopsis = "Stop recording a call through MixMonitor"; -static const char *stop_desc = "" -" StopMixMonitor():\n" -"Stops the audio recording that was started with a call to MixMonitor()\n" -"on the current channel.\n" -""; struct module_symbols *me; @@ -415,8 +455,8 @@ static int load_module(void) int res; ast_cli_register_multiple(cli_mixmonitor, sizeof(cli_mixmonitor) / sizeof(struct ast_cli_entry)); - res = ast_register_application(app, mixmonitor_exec, synopsis, desc); - res |= ast_register_application(stop_app, stop_mixmonitor_exec, stop_synopsis, stop_desc); + res = ast_register_application_xml(app, mixmonitor_exec); + res |= ast_register_application_xml(stop_app, stop_mixmonitor_exec); return res; } diff --git a/apps/app_morsecode.c b/apps/app_morsecode.c index 455ee04c1..f9005296a 100644 --- a/apps/app_morsecode.c +++ b/apps/app_morsecode.c @@ -34,18 +34,33 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/indications.h" +/*** DOCUMENTATION + <application name="Morsecode" language="en_US"> + <synopsis> + Plays morse code + </synopsis> + <syntax> + <parameter name="string" required="true"> + <para>String to playback as morse code to channel</para> + </parameter> + </syntax> + <description> + <para>Plays the Morse code equivalent of the passed string.</para> + + <para>This application uses the following variables:</para> + <variablelist> + <variable name="MORSEDITLEN"> + <para>Use this value in (ms) for length of dit</para> + </variable> + <variable name="MORSETONE"> + <para>The pitch of the tone in (Hz), default is 800</para> + </variable> + </variablelist> + </description> + </application> + ***/ static char *app_morsecode = "Morsecode"; -static char *morsecode_synopsis = "Plays morse code"; - -static char *morsecode_descrip = -" Morsecode(<string>):\n" -"Plays the Morse code equivalent of the passed string. If the variable\n" -"MORSEDITLEN is set, it will use that value for the length (in ms) of the dit\n" -"(defaults to 80). Additionally, if MORSETONE is set, it will use that tone\n" -"(in Hz). The tone default is 800.\n"; - - static char *morsecode[] = { "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", /* 0-15 */ "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", /* 16-31 */ @@ -159,7 +174,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app_morsecode, morsecode_exec, morsecode_synopsis, morsecode_descrip); + return ast_register_application_xml(app_morsecode, morsecode_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Morse code"); diff --git a/apps/app_mp3.c b/apps/app_mp3.c index 23db94fbc..688be6a00 100644 --- a/apps/app_mp3.c +++ b/apps/app_mp3.c @@ -44,16 +44,26 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #define LOCAL_MPG_123 "/usr/local/bin/mpg123" #define MPG_123 "/usr/bin/mpg123" +/*** DOCUMENTATION + <application name="MP3Player" language="en_US"> + <synopsis> + Play an MP3 file or stream. + </synopsis> + <syntax> + <parameter name="Location" required="true"> + <para>Location of the file to be played. + (argument passed to mpg123)</para> + </parameter> + </syntax> + <description> + <para>Executes mpg123 to play the given location, which typically would be a filename or a URL. + User can exit by pressing any key on the dialpad, or by hanging up.</para> + </description> + </application> + + ***/ static char *app = "MP3Player"; -static char *synopsis = "Play an MP3 file or stream"; - -static char *descrip = -" MP3Player(location): Executes mpg123 to play the given location,\n" -"which typically would be a filename or a URL. User can exit by pressing\n" -"any key on the dialpad, or by hanging up."; - - static int mp3play(char *filename, int fd) { int res; @@ -221,7 +231,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, mp3_exec, synopsis, descrip); + return ast_register_application_xml(app, mp3_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Silly MP3 Application"); diff --git a/apps/app_nbscat.c b/apps/app_nbscat.c index 5bc920f50..dd071ef0e 100644 --- a/apps/app_nbscat.c +++ b/apps/app_nbscat.c @@ -43,6 +43,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/translate.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="NBScat" language="en_US"> + <synopsis> + Play an NBS local stream. + </synopsis> + <syntax /> + <description> + <para>Executes nbscat to listen to the local NBS stream. + User can exit by pressing any key.</para> + </description> + </application> + ***/ + #define LOCAL_NBSCAT "/usr/local/bin/nbscat8k" #define NBSCAT "/usr/bin/nbscat8k" @@ -52,13 +65,6 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") static char *app = "NBScat"; -static char *synopsis = "Play an NBS local stream"; - -static char *descrip = -" NBScat(): Executes nbscat to listen to the local NBS stream.\n" -"User can exit by pressing any key.\n"; - - static int NBScatplay(int fd) { int res; @@ -204,7 +210,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, NBScat_exec, synopsis, descrip); + return ast_register_application_xml(app, NBScat_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Silly NBS Stream Application"); diff --git a/apps/app_page.c b/apps/app_page.c index 33ff1b489..7aacbd9d6 100644 --- a/apps/app_page.c +++ b/apps/app_page.c @@ -44,24 +44,57 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/devicestate.h" #include "asterisk/dial.h" +/*** DOCUMENTATION + <application name="Page" language="en_US"> + <synopsis> + Page series of phones + </synopsis> + <syntax> + <parameter name="Technology/Resource" required="true" argsep="&"> + <argument name="Technology/Resource" required="true"> + <para>Specification of the device(s) to dial. These must be in the format of + <literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable> + represents a particular channel driver, and <replaceable>Resource</replaceable> represents a resource + available to that particular channel driver.</para> + </argument> + <argument name="Technology2/Resource2" multiple="true"> + <para>Optional extra devices to dial inparallel</para> + <para>If you need more then one enter them as Technology2/Resource2& + Technology3/Resourse3&.....</para> + </argument> + </parameter> + <parameter name="options"> + <optionlist> + <option name="d"> + <para>Full duplex audio</para> + </option> + <option name="q"> + <para>Quiet, do not play beep to caller</para> + </option> + <option name="r"> + <para>Record the page into a file (meetme option <literal>r</literal>)</para> + </option> + <option name="s"> + <para>Only dial channel if devicestate says its <literal>notinuse</literal></para> + </option> + </optionlist> + </parameter> + <parameter name="timeout"> + <para>Specify the length of time that the system will attempt to connect a call. + After this duration, any intercom calls that have not been answered will be hung up by the + system.</para> + </parameter> + </syntax> + <description> + <para>Places outbound calls to the given <replaceable>technology</replaceable>/<replaceable>resource</replaceable> + and dumps them into a conference bridge as muted participants. The original + caller is dumped into the conference as a speaker and the room is + destroyed when the original callers leaves.</para> + </description> + </application> + ***/ static const char *app_page= "Page"; -static const char *page_synopsis = "Pages phones"; - -static const char *page_descrip = -"Page(Technology/Resource&Technology2/Resource2[,options][,timeout])\n" -" Places outbound calls to the given technology / resource and dumps\n" -"them into a conference bridge as muted participants. The original\n" -"caller is dumped into the conference as a speaker and the room is\n" -"destroyed when the original caller leaves. Valid options are:\n" -" d - full duplex audio\n" -" q - quiet, do not play beep to caller\n" -" r - record the page into a file (see 'r' for app_meetme)\n" -" s - only dial channel if devicestate says it is not in use\n" -"The timeout parameter specifies the length of time that the system\n" -"will attempt to connect a call. After this duration, any intercom\n" -"calls that have not been answered will be hung up by the system.\n"; - enum { PAGE_DUPLEX = (1 << 0), PAGE_QUIET = (1 << 1), @@ -216,7 +249,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app_page, page_exec, page_synopsis, page_descrip); + return ast_register_application_xml(app_page, page_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Page Multiple Phones"); diff --git a/apps/app_playback.c b/apps/app_playback.c index 4e6c3f530..63dd30857 100644 --- a/apps/app_playback.c +++ b/apps/app_playback.c @@ -39,26 +39,49 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" /* provides config-file based 'say' functions */ #include "asterisk/cli.h" -static char *app = "Playback"; - -static char *synopsis = "Play a file"; - -static char *descrip = -" Playback(filename[&filename2...][,option]): Plays back given filenames (do not put\n" -"extension). Options may also be included following a comma.\n" -"The 'skip' option causes the playback of the message to be skipped if the channel\n" -"is not in the 'up' state (i.e. it hasn't been answered yet). If 'skip' is \n" -"specified, the application will return immediately should the channel not be\n" -"off hook. Otherwise, unless 'noanswer' is specified, the channel will\n" -"be answered before the sound is played. Not all channels support playing\n" -"messages while still on hook.\n" -"This application sets the following channel variable upon completion:\n" -" PLAYBACKSTATUS The status of the playback attempt as a text string, one of\n" -" SUCCESS | FAILED\n" -"See Also: Background (application) -- for playing soundfiles that are interruptible\n" -" WaitExten (application) -- wait for digits from caller, optionally play music on hold\n" -; +/*** DOCUMENTATION + <application name="Playback" language="en_US"> + <synopsis> + Play a file. + </synopsis> + <syntax> + <parameter name="filenames" required="true" argsep="&"> + <argument name="filename" required="true" /> + <argument name="filename2" multiple="true" /> + </parameter> + <parameter name="options"> + <para>Comma separated list of options</para> + <optionlist> + <option name="skip"> + <para>Do not play if not answered</para> + </option> + <option name="noanswer"> + <para>Playback without answering, otherwise the channel will + be answered before the sound is played.</para> + <note><para>Not all channel types support playing messages while still on hook.</para></note> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>Plays back given filenames (do not put extension of wav/alaw etc). + The playback command answer the channel if no options are specified. + If the file is non-existant it will fail</para> + <para>This application sets the following channel variable 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> + <para>See Also: Background (application) -- for playing soundfiles that are interruptible</para> + <para>WaitExten (application) -- wait for digits from caller, optionally play music on hold</para> + </description> + </application> + ***/ +static char *app = "Playback"; static struct ast_config *say_cfg = NULL; /* save the say' api calls. @@ -520,7 +543,7 @@ static int load_module(void) } ast_cli_register_multiple(cli_playback, sizeof(cli_playback) / sizeof(struct ast_cli_entry)); - return ast_register_application(app, playback_exec, synopsis, descrip); + return ast_register_application_xml(app, playback_exec); } AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Sound File Playback Application", diff --git a/apps/app_privacy.c b/apps/app_privacy.c index 09f698861..71811de1c 100644 --- a/apps/app_privacy.c +++ b/apps/app_privacy.c @@ -41,25 +41,41 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/config.h" -static char *app = "PrivacyManager"; - -static char *synopsis = "Require phone number to be entered, if no CallerID sent"; +/*** DOCUMENTATION + <application name="PrivacyManager" language="en_US"> + <synopsis> + Require phone number to be entered, if no CallerID sent + </synopsis> + <syntax> + <parameter name="maxretries"> + <para>Total tries caller is allowed to input a callerid. Defaults to <literal>3</literal>.</para> + </parameter> + <parameter name="minlength"> + <para>Minimum allowable digits in the input callerid number. Defaults to <literal>10</literal>.</para> + </parameter> + <parameter name="context"> + <para>Context to check the given callerid against patterns.</para> + </parameter> + </syntax> + <description> + <para>If no Caller*ID is sent, PrivacyManager answers the channel and asks + the caller to enter their phone number. The caller is given + <replaceable>maxretries</replaceable> attempts to do so. The application does + <emphasis>nothing</emphasis> if Caller*ID was received on the channel.</para> + <para>The application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="PRIVACYMGRSTATUS"> + <para>The status of the privacy manager's attempt to collect a phone number from the user.</para> + <value name="SUCCESS"/> + <value name="FAILED"/> + </variable> + </variablelist> + </description> + </application> + ***/ -static char *descrip = - " PrivacyManager([maxretries][,minlength][,context]): If no Caller*ID \n" - "is sent, PrivacyManager answers the channel and asks the caller to\n" - "enter their phone number. The caller is given 'maxretries' attempts to do so.\n" - "The application does nothing if Caller*ID was received on the channel.\n" - " maxretries default 3 -maximum number of attempts the caller is allowed \n" - " to input a callerid.\n" - " minlength default 10 -minimum allowable digits in the input callerid number.\n" - " context context to check the given Caller*ID against patterns.\n" - "The application sets the following channel variable upon completion: \n" - "PRIVACYMGRSTATUS The status of the privacy manager's attempt to collect \n" - " a phone number from the user. A text string that is either:\n" - " SUCCESS | FAILED \n" -; +static char *app = "PrivacyManager"; static int privacy_exec (struct ast_channel *chan, void *data) { @@ -178,7 +194,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, privacy_exec, synopsis, descrip); + return ast_register_application_xml(app, privacy_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Require phone number to be entered, if no CallerID sent"); diff --git a/apps/app_queue.c b/apps/app_queue.c index 5733d0bc4..bc04deb46 100644 --- a/apps/app_queue.c +++ b/apps/app_queue.c @@ -108,6 +108,344 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") * to this order! */ +/*** DOCUMENTATION + <application name="Queue" language="en_US"> + <synopsis> + Queue a call for a call queue. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="options"> + <optionlist> + <option name="c"> + <para>Continue in the dialplan if the callee hangs up.</para> + </option> + <option name="d"> + <para>data-quality (modem) call (minimum delay).</para> + </option> + <option name="h"> + <para>Allow <emphasis>callee</emphasis> to hang up by pressing <literal>*</literal>.</para> + </option> + <option name="H"> + <para>Allow <emphasis>caller</emphasis> to hang up by pressing <literal>*</literal>.</para> + </option> + <option name="n"> + <para>No retries on the timeout; will exit this application and + go to the next step.</para> + </option> + <option name="i"> + <para>Ignore call forward requests from queue members and do nothing + when they are requested.</para> + </option> + <option name="r"> + <para>Ring instead of playing MOH. Periodic Announcements are still made, if applicable.</para> + </option> + <option name="t"> + <para>Allow the <emphasis>called</emphasis> user to transfer the calling user.</para> + </option> + <option name="T"> + <para>Allow the <emphasis>calling</emphasis> user to transfer the call.</para> + </option> + <option name="w"> + <para>Allow the <emphasis>called</emphasis> user to write the conversation to + disk via Monitor.</para> + </option> + <option name="W"> + <para>Allow the <emphasis>calling</emphasis> user to write the conversation to + disk via Monitor.</para> + </option> + <option name="k"> + <para>Allow the <emphasis>called</emphasis> party to enable parking of the call by sending + the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para> + </option> + <option name="K"> + <para>Allow the <emphasis>calling</emphasis> party to enable parking of the call by sending + the DTMF sequence defined for call parking in <filename>features.conf</filename>.</para> + </option> + <option name="x"> + <para>Allow the <emphasis>called</emphasis> user to write the conversation + to disk via MixMonitor.</para> + </option> + <option name="X"> + <para>Allow the <emphasis>calling</emphasis> user to write the conversation to + disk via MixMonitor.</para> + </option> + </optionlist> + </parameter> + <parameter name="URL"> + <para><replaceable>URL</replaceable> will be sent to the called party if the channel supports it.</para> + </parameter> + <parameter name="announceoverride" /> + <parameter name="timeout"> + <para>Will cause the queue to fail out after a specified number of + seconds, checked between each <filename>queues.conf</filename> <replaceable>timeout</replaceable> and + <replaceable>retry</replaceable> cycle.</para> + </parameter> + <parameter name="AGI"> + <para>Will setup an AGI script to be executed on the calling party's channel once they are + connected to a queue member.</para> + </parameter> + <parameter name="macro"> + <para>Will run a macro on the calling party's channel once they are connected to a queue member.</para> + </parameter> + <parameter name="gosub"> + <para>Will run a gosub on the calling party's channel once they are connected to a queue member.</para> + </parameter> + <parameter name="rule"> + <para>Will cause the queue's defaultrule to be overridden by the rule specified.</para> + </parameter> + </syntax> + <description> + <para>In addition to transferring the call, a call may be parked and then picked + up by another user.</para> + <para>This application will return to the dialplan if the queue does not exist, or + any of the join options cause the caller to not enter the queue.</para> + <para>This application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="QUEUESTATUS"> + <para>The status of the call as a text string.</para> + <value name="TIMEOUT" /> + <value name="FULL" /> + <value name="JOINEMPTY" /> + <value name="LEAVEEMPTY" /> + <value name="JOINUNAVAIL" /> + <value name="LEAVEUNAVAIL" /> + <value name="CONTINUE" /> + </variable> + </variablelist> + </description> + </application> + <application name="AddQueueMember" language="en_US"> + <synopsis> + Dynamically adds queue members. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="interface" /> + <parameter name="penalty" /> + <parameter name="options" /> + <parameter name="membername" /> + <parameter name="stateinterface" /> + </syntax> + <description> + <para>Dynamically adds interface to an existing queue. If the interface is + already in the queue it will return an error.</para> + <para>This application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="AQMSTATUS"> + <para>The status of the attempt to add a queue member as a text string.</para> + <value name="ADDED" /> + <value name="MEMBERALREADY" /> + <value name="NOSUCHQUEUE" /> + </variable> + </variablelist> + </description> + </application> + <application name="RemoveQueueMember" language="en_US"> + <synopsis> + Dynamically removes queue members. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="interface" /> + <parameter name="options" /> + </syntax> + <description> + <para>If the interface is <emphasis>NOT</emphasis> in the queue it will return an error.</para> + <para>This application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="RQMSTATUS"> + <value name="REMOVED" /> + <value name="NOTINQUEUE" /> + <value name="NOSUCHQUEUE" /> + </variable> + </variablelist> + <para>Example: RemoveQueueMember(techsupport,SIP/3000)</para> + </description> + </application> + <application name="PauseQueueMember" language="en_US"> + <synopsis> + Pauses a queue member. + </synopsis> + <syntax> + <parameter name="queuename" /> + <parameter name="interface" required="true" /> + <parameter name="options" /> + <parameter name="reason"> + <para>Is used to add extra information to the appropriate queue_log entries and manager events.</para> + </parameter> + </syntax> + <description> + <para>Pauses (blocks calls for) a queue member. The given interface will be paused in the given queue. + This prevents any calls from being sent from the queue to the interface until it is + unpaused with UnpauseQueueMember or the manager interface. If no queuename is given, + the interface is paused in every queue it is a member of. The application will fail if the + interface is not found.</para> + <para>This application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="PQMSTATUS"> + <para>The status of the attempt to pause a queue member as a text string.</para> + <value name="PAUSED" /> + <value name="NOTFOUND" /> + </variable> + </variablelist> + <para>Example: PauseQueueMember(,SIP/3000)</para> + </description> + </application> + <application name="UnpauseQueueMember" language="en_US"> + <synopsis> + Unpauses a queue member. + </synopsis> + <syntax> + <parameter name="queuename" /> + <parameter name="interface" required="true" /> + <parameter name="options" /> + <parameter name="reason"> + <para>Is used to add extra information to the appropriate queue_log entries and manager events.</para> + </parameter> + </syntax> + <description> + <para>Unpauses (resumes calls to) a queue member. This is the counterpart to <literal>PauseQueueMember()</literal> + and operates exactly the same way, except it unpauses instead of pausing the given interface.</para> + <para>This application sets the following channel variable upon completion:</para> + <variablelist> + <variable name="UPQMSTATUS"> + <para>The status of the attempt to unpause a queue member as a text string.</para> + <value name="UNPAUSED" /> + <value name="NOTFOUND" /> + </variable> + </variablelist> + <para>Example: UnpauseQueueMember(,SIP/3000)</para> + </description> + </application> + <application name="QueueLog" language="en_US"> + <synopsis> + Writes to the queue_log file. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="uniqueid" required="true" /> + <parameter name="agent" required="true" /> + <parameter name="event" required="true" /> + <parameter name="additionalinfo" /> + </syntax> + <description> + <para>Allows you to write your own events into the queue log.</para> + <para>Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</para> + </description> + </application> + <function name="QUEUE_VARIABLES" language="en_US"> + <synopsis> + Return Queue information in variables. + </synopsis> + <syntax> + <parameter name="queuename" required="true"> + <enumlist> + <enum name="QUEUEMAX"> + <para>Maxmimum number of calls allowed.</para> + </enum> + <enum name="QUEUESTRATEGY"> + <para>The strategy of the queue.</para> + </enum> + <enum name="QUEUECALLS"> + <para>Number of calls currently in the queue.</para> + </enum> + <enum name="QUEUEHOLDTIME"> + <para>Current average hold time.</para> + </enum> + <enum name="QUEUECOMPLETED"> + <para>Number of completed calls for the queue.</para> + </enum> + <enum name="QUEUEABANDONED"> + <para>Number of abandoned calls.</para> + </enum> + <enum name="QUEUESRVLEVEL"> + <para>Queue service level.</para> + </enum> + <enum name="QUEUESRVLEVELPERF"> + <para>Current service level performance.</para> + </enum> + </enumlist> + </parameter> + </syntax> + <description> + <para>Makes the following queue variables available.</para> + <para>Returns <literal>0</literal> if queue is found and setqueuevar is defined, <literal>-1</literal> otherwise.</para> + </description> + </function> + <function name="QUEUE_MEMBER" language="en_US"> + <synopsis> + Count number of members answering a queue. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="option" required="true"> + <enumlist> + <enum name="logged"> + <para>Returns the number of logged-in members for the specified queue.</para> + </enum> + <enum name="free"> + <para>Returns the number of logged-in members for the specified queue available to take a call.</para> + </enum> + <enum name="count"> + <para>Returns the total number of members for the specified queue.</para> + </enum> + </enumlist> + </parameter> + </syntax> + <description> + <para>Returns the number of members currently associated with the specified <replaceable>queuename</replaceable>.</para> + </description> + </function> + <function name="QUEUE_MEMBER_COUNT" language="en_US"> + <synopsis> + Count number of members answering a queue. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + </syntax> + <description> + <para>Returns the number of members currently associated with the specified <replaceable>queuename</replaceable>.</para> + <warning><para>This function has been deprecated in favor of the <literal>QUEUE_MEMBER()</literal> function</para></warning> + </description> + </function> + <function name="QUEUE_WAITING_COUNT" language="en_US"> + <synopsis> + Count number of calls currently waiting in a queue. + </synopsis> + <syntax> + <parameter name="queuename" /> + </syntax> + <description> + <para>Returns the number of callers currently waiting in the specified <replaceable>queuename</replaceable>.</para> + </description> + </function> + <function name="QUEUE_MEMBER_LIST" language="en_US"> + <synopsis> + Returns a list of interfaces on a queue. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + </syntax> + <description> + <para>Returns a comma-separated list of members associated with the specified <replaceable>queuename</replaceable>.</para> + </description> + </function> + <function name="QUEUE_MEMBER_PENALTY" language="en_US"> + <synopsis> + Gets or sets queue members penalty. + </synopsis> + <syntax> + <parameter name="queuename" required="true" /> + <parameter name="interface" required="true" /> + </syntax> + <description> + <para>Gets or sets queue members penalty.</para> + </description> + </function> + + ***/ + enum { QUEUE_STRATEGY_RINGALL = 0, QUEUE_STRATEGY_LEASTRECENT, @@ -150,128 +488,15 @@ static struct ast_taskprocessor *devicestate_tps; static char *app = "Queue"; -static char *synopsis = "Queue a call for a call queue"; - -static char *descrip = -" Queue(queuename[,options[,URL][,announceoverride][,timeout][,AGI][,macro][,gosub][,rule]):\n" -"Queues an incoming call in a particular call queue as defined in queues.conf.\n" -"This application will return to the dialplan if the queue does not exist, or\n" -"any of the join options cause the caller to not enter the queue.\n" -"The option string may contain zero or more of the following characters:\n" -" 'c' -- continue in the dialplan if the callee hangs up.\n" -" 'd' -- data-quality (modem) call (minimum delay).\n" -" 'h' -- allow callee to hang up by hitting '*', or whatver disconnect sequence\n" -" that is defined in the featuremap section in features.conf.\n" -" 'H' -- allow caller to hang up by hitting '*', or whatever disconnect sequence\n" -" that is defined in the featuremap section in features.conf.\n" -" 'n' -- no retries on the timeout; will exit this application and \n" -" go to the next step.\n" -" 'i' -- ignore call forward requests from queue members and do nothing\n" -" when they are requested.\n" -" 'r' -- ring instead of playing MOH. Periodic Announcements are still made, if applicable.\n" -" 't' -- allow the called user transfer the calling user by pressing '#' or\n" -" whatever blindxfer sequence defined in the featuremap section in\n" -" features.conf\n" -" 'T' -- to allow the calling user to transfer the call by pressing '#' or\n" -" whatever blindxfer sequence defined in the featuremap section in\n" -" features.conf\n" -" 'w' -- allow the called user to write the conversation to disk via Monitor\n" -" by pressing the automon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'W' -- allow the calling user to write the conversation to disk via Monitor\n" -" by pressing the automon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'k' -- Allow the called party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in features.conf.\n" -" 'K' -- Allow the calling party to enable parking of the call by sending\n" -" the DTMF sequence defined for call parking in features.conf.\n" -" 'x' -- allow the called user to write the conversation to disk via MixMonitor\n" -" by pressing the automixmon sequence defined in the featuremap section in\n" -" features.conf\n" -" 'X' -- allow the calling user to write the conversation to disk via MixMonitor\n" -" by pressing the automixmon sequence defined in the featuremap section in\n" -" features.conf\n" -" The optional URL will be sent to the called party if the channel supports\n" -"it.\n" -" The optional AGI parameter will setup an AGI script to be executed on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional macro parameter will run a macro on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional gosub parameter will run a gosub on the \n" -"calling party's channel once they are connected to a queue member.\n" -" The optional rule parameter will cause the queue's defaultrule to be\n" -"overridden by the rule specified.\n" -" The timeout will cause the queue to fail out after a specified number of\n" -"seconds, checked between each queues.conf 'timeout' and 'retry' cycle.\n" -" This application sets the following channel variable upon completion:\n" -" QUEUESTATUS The status of the call as a text string, one of\n" -" TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL | CONTINUE\n"; - static char *app_aqm = "AddQueueMember" ; -static char *app_aqm_synopsis = "Dynamically adds queue members" ; -static char *app_aqm_descrip = -" AddQueueMember(queuename[,interface[,penalty[,options[,membername[,stateinterface]]]]]):\n" -"Dynamically adds interface to an existing queue.\n" -"If the interface is already in the queue it will return an error.\n" -" This application sets the following channel variable upon completion:\n" -" AQMSTATUS The status of the attempt to add a queue member as a \n" -" text string, one of\n" -" ADDED | MEMBERALREADY | NOSUCHQUEUE \n" -"Example: AddQueueMember(techsupport,SIP/3000)\n" -""; static char *app_rqm = "RemoveQueueMember" ; -static char *app_rqm_synopsis = "Dynamically removes queue members" ; -static char *app_rqm_descrip = -" RemoveQueueMember(queuename[,interface[,options]]):\n" -"Dynamically removes interface to an existing queue\n" -"If the interface is NOT in the queue it will return an error.\n" -" This application sets the following channel variable upon completion:\n" -" RQMSTATUS The status of the attempt to remove a queue member as a\n" -" text string, one of\n" -" REMOVED | NOTINQUEUE | NOSUCHQUEUE \n" -"Example: RemoveQueueMember(techsupport,SIP/3000)\n" -""; static char *app_pqm = "PauseQueueMember" ; -static char *app_pqm_synopsis = "Pauses a queue member" ; -static char *app_pqm_descrip = -" PauseQueueMember([queuename],interface[,options[,reason]]):\n" -"Pauses (blocks calls for) a queue member.\n" -"The given interface will be paused in the given queue. This prevents\n" -"any calls from being sent from the queue to the interface until it is\n" -"unpaused with UnpauseQueueMember or the manager interface. If no\n" -"queuename is given, the interface is paused in every queue it is a\n" -"member of. The application will fail if the interface is not found.\n" -"The reason string is entirely optional and is used to add extra information\n" -"to the appropriate queue_log entries and manager events.\n" -" This application sets the following channel variable upon completion:\n" -" PQMSTATUS The status of the attempt to pause a queue member as a\n" -" text string, one of\n" -" PAUSED | NOTFOUND\n" -"Example: PauseQueueMember(,SIP/3000)\n"; static char *app_upqm = "UnpauseQueueMember" ; -static char *app_upqm_synopsis = "Unpauses a queue member" ; -static char *app_upqm_descrip = -" UnpauseQueueMember([queuename],interface[,options[,reason]]):\n" -"Unpauses (resumes calls to) a queue member.\n" -"This is the counterpart to PauseQueueMember and operates exactly the\n" -"same way, except it unpauses instead of pausing the given interface.\n" -"The reason string is entirely optional and is used to add extra information\n" -"to the appropriate queue_log entries and manager events.\n" -" This application sets the following channel variable upon completion:\n" -" UPQMSTATUS The status of the attempt to unpause a queue \n" -" member as a text string, one of\n" -" UNPAUSED | NOTFOUND\n" -"Example: UnpauseQueueMember(,SIP/3000)\n"; static char *app_ql = "QueueLog" ; -static char *app_ql_synopsis = "Writes to the queue_log" ; -static char *app_ql_descrip = -" QueueLog(queuename,uniqueid,agent,event[,additionalinfo]):\n" -"Allows you to write your own events into the queue log\n" -"Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)\n"; /*! \brief Persistent Members astdb family */ static const char *pm_family = "Queue/PersistentMembers"; @@ -5088,69 +5313,31 @@ static int queue_function_memberpenalty_write(struct ast_channel *chan, const ch static struct ast_custom_function queuevar_function = { .name = "QUEUE_VARIABLES", - .synopsis = "Return Queue information in variables", - .syntax = "QUEUE_VARIABLES(<queuename>)", - .desc = -"Makes the following queue variables available.\n" -"QUEUEMAX maxmimum number of calls allowed\n" -"QUEUESTRATEGY the strategy of the queue\n" -"QUEUECALLS number of calls currently in the queue\n" -"QUEUEHOLDTIME current average hold time\n" -"QUEUECOMPLETED number of completed calls for the queue\n" -"QUEUEABANDONED number of abandoned calls\n" -"QUEUESRVLEVEL queue service level\n" -"QUEUESRVLEVELPERF current service level performance\n" -"Returns 0 if queue is found and setqueuevar is defined, -1 otherwise", .read = queue_function_var, }; static struct ast_custom_function queuemembercount_function = { .name = "QUEUE_MEMBER", - .synopsis = "Count number of members answering a queue", - .syntax = "QUEUE_MEMBER(<queuename>, <option>)", - .desc = -"Returns the number of members currently associated with the specified queue.\n" -"One of three options may be passed to determine the count returned:\n" - "\"logged\" - Returns the number of logged-in members for the specified queue\n" - "\"free\" - Returns the number of logged-in members for the specified queue available to take a call\n" - "\"count\" - Returns the total number of members for the specified queue\n", .read = queue_function_qac, }; static struct ast_custom_function queuemembercount_dep = { .name = "QUEUE_MEMBER_COUNT", - .synopsis = "Count number of members answering a queue", - .syntax = "QUEUE_MEMBER_COUNT(<queuename>)", - .desc = -"Returns the number of members currently associated with the specified queue.\n\n" -"This function has been deprecated in favor of the QUEUE_MEMBER function\n", .read = queue_function_qac_dep, }; static struct ast_custom_function queuewaitingcount_function = { .name = "QUEUE_WAITING_COUNT", - .synopsis = "Count number of calls currently waiting in a queue", - .syntax = "QUEUE_WAITING_COUNT(<queuename>)", - .desc = -"Returns the number of callers currently waiting in the specified queue.\n", .read = queue_function_queuewaitingcount, }; static struct ast_custom_function queuememberlist_function = { .name = "QUEUE_MEMBER_LIST", - .synopsis = "Returns a list of interfaces on a queue", - .syntax = "QUEUE_MEMBER_LIST(<queuename>)", - .desc = -"Returns a comma-separated list of members associated with the specified queue.\n", .read = queue_function_queuememberlist, }; static struct ast_custom_function queuememberpenalty_function = { .name = "QUEUE_MEMBER_PENALTY", - .synopsis = "Gets or sets queue members penalty.", - .syntax = "QUEUE_MEMBER_PENALTY(<queuename>,<interface>)", - .desc = -"Gets or sets queue members penalty\n", .read = queue_function_memberpenalty_read, .write = queue_function_memberpenalty_write, }; @@ -6430,12 +6617,12 @@ static int load_module(void) reload_queue_members(); ast_cli_register_multiple(cli_queue, sizeof(cli_queue) / sizeof(struct ast_cli_entry)); - res = ast_register_application(app, queue_exec, synopsis, descrip); - res |= ast_register_application(app_aqm, aqm_exec, app_aqm_synopsis, app_aqm_descrip); - res |= ast_register_application(app_rqm, rqm_exec, app_rqm_synopsis, app_rqm_descrip); - res |= ast_register_application(app_pqm, pqm_exec, app_pqm_synopsis, app_pqm_descrip); - res |= ast_register_application(app_upqm, upqm_exec, app_upqm_synopsis, app_upqm_descrip); - res |= ast_register_application(app_ql, ql_exec, app_ql_synopsis, app_ql_descrip); + res = ast_register_application_xml(app, queue_exec); + res |= ast_register_application_xml(app_aqm, aqm_exec); + res |= ast_register_application_xml(app_rqm, rqm_exec); + res |= ast_register_application_xml(app_pqm, pqm_exec); + res |= ast_register_application_xml(app_upqm, upqm_exec); + res |= ast_register_application_xml(app_ql, ql_exec); res |= ast_manager_register("Queues", 0, manager_queues_show, "Queues"); res |= ast_manager_register("QueueStatus", 0, manager_queues_status, "Queue Status"); res |= ast_manager_register("QueueSummary", 0, manager_queues_summary, "Queue Summary"); diff --git a/apps/app_readexten.c b/apps/app_readexten.c index 93ca4e670..e54741ffa 100644 --- a/apps/app_readexten.c +++ b/apps/app_readexten.c @@ -36,6 +36,82 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/indications.h" #include "asterisk/channel.h" +/*** DOCUMENTATION + <application name="ReadExten" language="en_US"> + <synopsis> + Read an extension into a variable. + </synopsis> + <syntax> + <parameter name="variable" required="true" /> + <parameter name="filename"> + <para>File to play before reading digits or tone with option <literal>i</literal></para> + </parameter> + <parameter name="context"> + <para>Context in which to match extensions.</para> + </parameter> + <parameter name="option"> + <optionlist> + <option name="s"> + <para>Return immediately if the channel is not answered.</para> + </option> + <option name="i"> + <para>Play <replaceable>filename</replaceable> as an indication tone from your + <filename>indications.conf</filename></para> + </option> + <option name="n"> + <para>Read digits even if the channel is not answered.</para> + </option> + </optionlist> + </parameter> + <parameter name="timeout"> + <para>An integer number of seconds to wait for a digit response. If + greater than <literal>0</literal>, that value will override the default timeout.</para> + </parameter> + </syntax> + <description> + <para>Reads a <literal>#</literal> terminated string of digits from the user into the given variable.</para> + <para>Will set READEXTENSTATUS on exit with one of the following statuses:</para> + <variablelist> + <variable name="READEXTENSTATUS"> + <value name="OK"> + A valid extension exists in ${variable}. + </value> + <value name="TIMEOUT"> + No extension was entered in the specified time. + </value> + <value name="INVALID"> + An invalid extension, ${INVALID_EXTEN}, was entered. + </value> + <value name="SKIP"> + Line was not up and the option 's' was specified. + </value> + <value name="ERROR"> + Invalid arguments were passed. + </value> + </variable> + </variablelist> + </description> + </application> + <function name="VALID_EXTEN" language="en_US"> + <synopsis> + Determine whether an extension exists or not. + </synopsis> + <syntax> + <parameter name="context"> + <para>Defaults to the current context</para> + </parameter> + <parameter name="extension" required="true" /> + <parameter name="priority"> + <para>Priority defaults to <literal>1</literal>.</para> + </parameter> + </syntax> + <description> + <para>Returns a true value if the indicated <replaceable>context</replaceable>, + <replaceable>extension</replaceable>, and <replaceable>priority</replaceable> exist.</para> + </description> + </function> + ***/ + enum { OPT_SKIP = (1 << 0), OPT_INDICATION = (1 << 1), @@ -50,28 +126,6 @@ AST_APP_OPTIONS(readexten_app_options, { static char *app = "ReadExten"; -static char *synopsis = "Read an extension into a variable"; - -static char *descrip = -" ReadExten(<variable>[,[<filename>][,[<context>][,[<option>][,<timeout>]]]])\n\n" -"Reads a #-terminated string of digits from the user into the given variable.\n" -" filename file to play before reading digits or tone with option i\n" -" context context in which to match extensions\n" -" option options are:\n" -" s - Return immediately if the channel is not answered,\n" -" i - Play filename as an indication tone from your\n" -" indications.conf\n" -" n - Read digits even if the channel is not answered.\n" -" timeout An integer number of seconds to wait for a digit response. If\n" -" greater than 0, that value will override the default timeout.\n\n" -"ReadExten will set READEXTENSTATUS on exit with one of the following statuses:\n" -" OK A valid extension exists in ${variable}\n" -" TIMEOUT No extension was entered in the specified time\n" -" INVALID An invalid extension, ${INVALID_EXTEN}, was entered\n" -" SKIP Line was not up and the option 's' was specified\n" -" ERROR Invalid arguments were passed\n"; - - static int readexten_exec(struct ast_channel *chan, void *data) { int res = 0; @@ -232,11 +286,6 @@ static int acf_isexten_exec(struct ast_channel *chan, const char *cmd, char *par static struct ast_custom_function acf_isexten = { .name = "VALID_EXTEN", - .synopsis = "Determine whether an extension exists or not", - .syntax = "VALID_EXTEN([<context>],<extension>[,<priority>])", - .desc = -"Returns a true value if the indicated context, extension, and priority exist.\n" -"Context defaults to the current context, priority defaults to 1.\n", .read = acf_isexten_exec, }; @@ -250,7 +299,7 @@ static int unload_module(void) static int load_module(void) { - int res = ast_register_application(app, readexten_exec, synopsis, descrip); + int res = ast_register_application_xml(app, readexten_exec); res |= ast_custom_function_register(&acf_isexten); return res; } diff --git a/apps/app_readfile.c b/apps/app_readfile.c index 8762ef860..c5234089f 100644 --- a/apps/app_readfile.c +++ b/apps/app_readfile.c @@ -35,16 +35,33 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/module.h" -static char *app_readfile = "ReadFile"; - -static char *readfile_synopsis = "Read the contents of a text file into a channel variable"; - -static char *readfile_descrip = -"ReadFile(varname=file,length)\n" -" varname - Result stored here.\n" -" file - The name of the file to read.\n" -" length - Maximum number of characters to capture.\n"; +/*** DOCUMENTATION + <application name="ReadFile" language="en_US"> + <synopsis> + Read the contents of a text file into a channel variable. + </synopsis> + <syntax argsep="="> + <parameter name="varname" required="true"> + <para>Result stored here.</para> + </parameter> + <parameter name="fileparams" required="true"> + <argument name="file" required="true"> + <para>The name of the file to read.</para> + </argument> + <argument name="length" required="false"> + <para>Maximum number of characters to capture.</para> + <para>If not specified defaults to max.</para> + </argument> + </parameter> + </syntax> + <description> + <para>Read the contents of a text file into channel variable <replaceable>varname</replaceable></para> + <warning><para>ReadFile has been deprecated in favor of Set(varname=${FILE(file,0,length)})</para></warning> + </description> + </application> + ***/ +static char *app_readfile = "ReadFile"; static int readfile_exec(struct ast_channel *chan, void *data) { @@ -101,7 +118,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app_readfile, readfile_exec, readfile_synopsis, readfile_descrip); + return ast_register_application_xml(app_readfile, readfile_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Stores output of file into a variable"); diff --git a/apps/app_record.c b/apps/app_record.c index 8afafc93d..a575efdbe 100644 --- a/apps/app_record.c +++ b/apps/app_record.c @@ -36,35 +36,66 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/dsp.h" /* use dsp routines for silence detection */ +/*** DOCUMENTATION + <application name="Record" language="en_US"> + <synopsis> + Record to a file. + </synopsis> + <syntax> + <parameter name="filename" required="true" argsep="."> + <argument name="filename" required="true" /> + <argument name="format" required="true"> + <para>Is the format of the file type to be recorded (wav, gsm, etc).</para> + </argument> + </parameter> + <parameter name="silence"> + <para>Is the number of seconds of silence to allow before returning.</para> + </parameter> + <parameter name="maxduration"> + <para>Is the maximum recording duration in seconds. If missing + or 0 there is no maximum.</para> + </parameter> + <parameter name="options"> + <optionlist> + <option name="a"> + <para>Append to existing recording rather than replacing.</para> + </option> + <option name="n"> + <para>Do not answer, but record anyway if line not yet answered.</para> + </option> + <option name="q"> + <para>quiet (do not play a beep tone).</para> + </option> + <option name="s"> + <para>skip recording if the line is not yet answered.</para> + </option> + <option name="t"> + <para>use alternate '*' terminator key (DTMF) instead of default '#'</para> + </option> + <option name="x"> + <para>Ignore all terminator keys (DTMF) and keep recording until hangup.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>If filename contains <literal>%d</literal>, these characters will be replaced with a number + incremented by one each time the file is recorded. + Use <astcli>core show file formats</astcli> to see the available formats on your system + User can press <literal>#</literal> to terminate the recording and continue to the next priority. + If the user hangup during a recording, all data will be lost and the application will teminate.</para> + <variablelist> + <variable name="RECORDED_FILE"> + <para>Will be set to the final filename of the recording.</para> + </variable> + </variablelist> + </description> + </application> + + ***/ static char *app = "Record"; -static char *synopsis = "Record to a file"; - -static char *descrip = -" Record(filename.format,silence[,maxduration][,options])\n\n" -"Records from the channel into a given filename. If the file exists it will\n" -"be overwritten.\n" -"- 'format' is the format of the file type to be recorded (wav, gsm, etc).\n" -"- 'silence' is the number of seconds of silence to allow before returning.\n" -"- 'maxduration' is the maximum recording duration in seconds. If missing\n" -"or 0 there is no maximum.\n" -"- 'options' may contain any of the following letters:\n" -" 'a' : append to existing recording rather than replacing\n" -" 'n' : do not answer, but record anyway if line not yet answered\n" -" 'q' : quiet (do not play a beep tone)\n" -" 's' : skip recording if the line is not yet answered\n" -" 't' : use alternate '*' terminator key (DTMF) instead of default '#'\n" -" 'x' : ignore all terminator keys (DTMF) and keep recording until hangup\n" -"\n" -"If filename contains '%d', these characters will be replaced with a number\n" -"incremented by one each time the file is recorded. A channel variable\n" -"named RECORDED_FILE will also be set, which contains the final filemname.\n\n" -"Use 'core show file formats' to see the available formats on your system\n\n" -"User can press '#' to terminate the recording and continue to the next priority.\n\n" -"If the user should hangup during a recording, all data will be lost and the\n" -"application will teminate. \n"; - enum { OPTION_APPEND = (1 << 0), OPTION_NOANSWER = (1 << 1), @@ -359,7 +390,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, record_exec, synopsis, descrip); + return ast_register_application_xml(app, record_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Trivial Record Application"); diff --git a/apps/app_sayunixtime.c b/apps/app_sayunixtime.c index d0e23449e..f6122e40d 100644 --- a/apps/app_sayunixtime.c +++ b/apps/app_sayunixtime.c @@ -36,29 +36,54 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/say.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="SayUnixTime" language="en_US"> + <synopsis> + Says a specified time in a custom format. + </synopsis> + <syntax> + <parameter name="unixtime"> + <para>time, in seconds since Jan 1, 1970. May be negative. Defaults to now.</para> + </parameter> + <parameter name="timezone"> + <para>timezone, see <directory>/usr/share/zoneinfo</directory> for a list. Defaults to machine default.</para> + </parameter> + <parameter name="format"> + <para>a format the time is to be said in. See <filename>voicemail.conf</filename>. + Defaults to <literal>ABdY "digits/at" IMp</literal></para> + </parameter> + </syntax> + <description> + <para>Uses some of the sound files stored in <directory>/var/lib/asterisk/sounds</directory> to construct a phrase + saying the specified date and/or time in the specified format. </para> + </description> + </application> + <application name="DateTime" language="en_US"> + <synopsis> + Says a specified time in a custom format. + </synopsis> + <syntax> + <parameter name="unixtime"> + <para>time, in seconds since Jan 1, 1970. May be negative. Defaults to now.</para> + </parameter> + <parameter name="timezone"> + <para>timezone, see <filename>/usr/share/zoneinfo</filename> for a list. Defaults to machine default.</para> + </parameter> + <parameter name="format"> + <para>a format the time is to be said in. See <filename>voicemail.conf</filename>. + Defaults to <literal>ABdY "digits/at" IMp</literal></para> + </parameter> + </syntax> + <description> + <para>Say the date and time in a specified format.</para> + </description> + </application> + + ***/ + static char *app_sayunixtime = "SayUnixTime"; static char *app_datetime = "DateTime"; -static char *sayunixtime_synopsis = "Says a specified time in a custom format"; - -static char *sayunixtime_descrip = -"SayUnixTime([unixtime][,[timezone][,format]])\n" -" unixtime - time, in seconds since Jan 1, 1970. May be negative.\n" -" defaults to now.\n" -" timezone - timezone, see /usr/share/zoneinfo for a list.\n" -" defaults to machine default.\n" -" format - a format the time is to be said in. See voicemail.conf.\n" -" defaults to \"ABdY 'digits/at' IMp\"\n"; -static char *datetime_descrip = -"DateTime([unixtime][,[timezone][,format]])\n" -" unixtime - time, in seconds since Jan 1, 1970. May be negative.\n" -" defaults to now.\n" -" timezone - timezone, see /usr/share/zoneinfo for a list.\n" -" defaults to machine default.\n" -" format: - a format the time is to be said in. See voicemail.conf.\n" -" defaults to \"ABdY 'digits/at' IMp\"\n"; - - static int sayunixtime_exec(struct ast_channel *chan, void *data) { AST_DECLARE_APP_ARGS(args, @@ -103,8 +128,8 @@ static int load_module(void) { int res; - res = ast_register_application(app_sayunixtime, sayunixtime_exec, sayunixtime_synopsis, sayunixtime_descrip); - res |= ast_register_application(app_datetime, sayunixtime_exec, sayunixtime_synopsis, datetime_descrip); + res = ast_register_application_xml(app_sayunixtime, sayunixtime_exec); + res |= ast_register_application_xml(app_datetime, sayunixtime_exec); return res; } diff --git a/apps/app_senddtmf.c b/apps/app_senddtmf.c index 9863ce012..bd92230bd 100644 --- a/apps/app_senddtmf.c +++ b/apps/app_senddtmf.c @@ -35,19 +35,30 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/manager.h" #include "asterisk/channel.h" +/*** DOCUMENTATION + <application name="SendDTMF" language="en_US"> + <synopsis> + Sends arbitrary DTMF digits + </synopsis> + <syntax> + <parameter name="digits" required="true"> + <para>List of digits 0-9,*#,abcd</para> + </parameter> + <parameter name="timeout_ms" required="false"> + <para>Amount of time to wait in ms between tones. (defaults to .25s)</para> + </parameter> + <parameter name="duration_ms" required="false"> + <para>Duration of each digit</para> + </parameter> + </syntax> + <description> + <para>DTMF digits sent to a channel with half second pause</para> + <para>It will pass all digits or terminate if it encounters an error.</para> + </description> + </application> + ***/ static char *app = "SendDTMF"; -static char *synopsis = "Sends arbitrary DTMF digits"; - -static char *descrip = -" SendDTMF(digits[,[timeout_ms][,duration_ms]]): Sends DTMF digits on a channel. \n" -" Accepted digits: 0-9, *#abcd, (default .25s pause between digits)\n" -" The application will either pass the assigned digits or terminate if it\n" -" encounters an error.\n" -" Optional Params: \n" -" timeout_ms: pause between digits.\n" -" duration_ms: duration of each digit.\n"; - static int senddtmf_exec(struct ast_channel *chan, void *vdata) { int res = 0; @@ -121,7 +132,7 @@ static int load_module(void) int res; res = ast_manager_register2( "PlayDTMF", EVENT_FLAG_CALL, manager_play_dtmf, "Play DTMF signal on a specific channel.", mandescr_playdtmf ); - res |= ast_register_application(app, senddtmf_exec, synopsis, descrip); + res |= ast_register_application_xml(app, senddtmf_exec); return res; } diff --git a/apps/app_sendtext.c b/apps/app_sendtext.c index e95ff6158..53306aa5a 100644 --- a/apps/app_sendtext.c +++ b/apps/app_sendtext.c @@ -37,19 +37,36 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/app.h" -static const char *app = "SendText"; - -static const char *synopsis = "Send a Text Message"; +/*** DOCUMENTATION + <application name="SendText" language="en_US"> + <synopsis> + Send a Text Message. + </synopsis> + <syntax> + <parameter name="text" required="true" /> + </syntax> + <description> + <para>Sends <replaceable>text</replaceable> to current channel (callee).</para> + <para>Result of transmission will be stored in the <variable>SENDTEXTSTATUS</variable></para> + <variablelist> + <variable name="SENDTEXTSTATUS"> + <value name="SUCCESS"> + Transmission succeeded. + </value> + <value name="FAILURE"> + Transmission failed. + </value> + <value name="UNSUPPORTED"> + Text transmission not supported by channel. + </value> + </variable> + </variablelist> + <note><para>At this moment, text is supposed to be 7 bit ASCII in most channels.</para></note> + </description> + </application> + ***/ -static const char *descrip = -" SendText(text): Sends text to current channel (callee).\n" -"Result of transmission will be stored in the SENDTEXTSTATUS\n" -"channel variable:\n" -" SUCCESS Transmission succeeded\n" -" FAILURE Transmission failed\n" -" UNSUPPORTED Text transmission not supported by channel\n" -"\n" -"At this moment, text is supposed to be 7 bit ASCII in most channels.\n"; +static const char *app = "SendText"; static int sendtext_exec(struct ast_channel *chan, void *data) { @@ -91,7 +108,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, sendtext_exec, synopsis, descrip); + return ast_register_application_xml(app, sendtext_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Send Text Applications"); diff --git a/apps/app_setcallerid.c b/apps/app_setcallerid.c index f1c9df3cb..6592249b4 100644 --- a/apps/app_setcallerid.c +++ b/apps/app_setcallerid.c @@ -38,26 +38,51 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/image.h" #include "asterisk/callerid.h" -static char *app2 = "SetCallerPres"; - -static char *synopsis2 = "Set CallerID Presentation"; +/*** DOCUMENTATION + <application name="SetCallerPres" language="en_US"> + <synopsis> + Set CallerID Presentation. + </synopsis> + <syntax> + <parameter name="presentation" required="true"> + <enumlist> + <enum name="allowed_not_screened"> + <para>Presentation Allowed, Not Screened.</para> + </enum> + <enum name="allowed_passed_screen"> + <para>Presentation Allowed, Passed Screen.</para> + </enum> + <enum name="allowed_failed_screen"> + <para>Presentation Allowed, Failed Screen.</para> + </enum> + <enum name="allowed"> + <para>Presentation Allowed, Network Number.</para> + </enum> + <enum name="prohib_not_screened"> + <para>Presentation Prohibited, Not Screened.</para> + </enum> + <enum name="prohib_passed_screen"> + <para>Presentation Prohibited, Passed Screen.</para> + </enum> + <enum name="prohib_failed_screen"> + <para>Presentation Prohibited, Failed Screen.</para> + </enum> + <enum name="prohib"> + <para>Presentation Prohibited, Network Number.</para> + </enum> + <enum name="unavailable"> + <para>Number Unavailable.</para> + </enum> + </enumlist> + </parameter> + </syntax> + <description> + <para>Set Caller*ID presentation on a call.</para> + </description> + </application> + ***/ - -static char *descrip2 = -" SetCallerPres(presentation): Set Caller*ID presentation on a call.\n" -" Valid presentations are:\n" -"\n" -" allowed_not_screened : Presentation Allowed, Not Screened\n" -" allowed_passed_screen : Presentation Allowed, Passed Screen\n" -" allowed_failed_screen : Presentation Allowed, Failed Screen\n" -" allowed : Presentation Allowed, Network Number\n" -" prohib_not_screened : Presentation Prohibited, Not Screened\n" -" prohib_passed_screen : Presentation Prohibited, Passed Screen\n" -" prohib_failed_screen : Presentation Prohibited, Failed Screen\n" -" prohib : Presentation Prohibited, Network Number\n" -" unavailable : Number Unavailable\n" -"\n" -; +static char *app2 = "SetCallerPres"; static int setcallerid_pres_exec(struct ast_channel *chan, void *data) { @@ -91,7 +116,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app2, setcallerid_pres_exec, synopsis2, descrip2); + return ast_register_application_xml(app2, setcallerid_pres_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Set CallerID Presentation Application"); diff --git a/apps/app_skel.c b/apps/app_skel.c index 44bf152aa..338a32f8a 100644 --- a/apps/app_skel.c +++ b/apps/app_skel.c @@ -44,11 +44,35 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/lock.h" #include "asterisk/app.h" +/*** DOCUMENTATION + <application name="Skel" language="en_US"> + <synopsis> + Simple one line explaination. + </synopsis> + <syntax> + <parameter name="dummy" required="true"/> + <parameter name="options"> + <optionlist> + <option name="a"> + <para>Option A.</para> + </option> + <option name="b"> + <para>Option B.</para> + </option> + <option name="c"> + <para>Option C.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>This application is a template to build other applications from. + It shows you the basic structure to create your own Asterisk applications.</para> + </description> + </application> + ***/ + static char *app = "Skel"; -static char *synopsis = -"Skeleton application."; -static char *descrip = "This application is a template to build other applications from.\n" - " It shows you the basic structure to create your own Asterisk applications.\n"; enum { OPTION_A = (1 << 0), @@ -122,7 +146,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, app_exec, synopsis, descrip) ? + return ast_register_application_xml(app, app_exec) ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS; } diff --git a/apps/app_softhangup.c b/apps/app_softhangup.c index 7af852560..a7ba753fd 100644 --- a/apps/app_softhangup.c +++ b/apps/app_softhangup.c @@ -36,13 +36,28 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/lock.h" #include "asterisk/app.h" -static char *synopsis = "Soft Hangup Application"; - -static char *desc = " SoftHangup(Technology/resource[,options]):\n" -"Hangs up the requested channel. If there are no channels to hangup,\n" -"the application will report it.\n" -" Options:\n" -" 'a' - hang up all channels on a specified device instead of a single resource\n"; +/*** DOCUMENTATION + <application name="SoftHangup" language="en_US"> + <synopsis> + Hangs up the requested channel. + </synopsis> + <syntax> + <parameter name="Technology/Resource" required="true" /> + <parameter name="options"> + <optionlist> + <option name="a"> + <para>Hang up all channels on a specified device instead of a single resource</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>Hangs up the requested channel. If there are no channels to + hangup, the application will report it.</para> + </description> + </application> + + ***/ static char *app = "SoftHangup"; @@ -114,7 +129,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, softhangup_exec, synopsis, desc); + return ast_register_application_xml(app, softhangup_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Hangs up the requested channel"); diff --git a/apps/app_stack.c b/apps/app_stack.c index 2e5e6de9e..599c5f1d4 100644 --- a/apps/app_stack.c +++ b/apps/app_stack.c @@ -40,6 +40,70 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" #include "asterisk/agi.h" +/*** DOCUMENTATION + <application name="Gosub" language="en_US"> + <synopsis> + Jump to label, saving return address. + </synopsis> + <syntax> + <parameter name="context" /> + <parameter name="exten" /> + <parameter name="priority" required="true" hasparams="optional"> + <argument name="arg1" multiple="true" required="true" /> + <argument name="argN" /> + </parameter> + </syntax> + <description> + <para>Jumps to the label specified, saving the return address.</para> + </description> + </application> + <application name="GosubIf" language="en_US"> + <synopsis> + Conditionally jump to label, saving return address. + </synopsis> + <syntax argsep="?"> + <parameter name="condition" required="true" /> + <parameter name="destination" required="true" argsep=":"> + <argument name="labeliftrue" hasparams="optional"> + <argument name="arg1" required="true" multiple="true" /> + <argument name="argN" /> + </argument> + <argument name="labeliffalse" hasparams="optional"> + <argument name="arg1" required="true" multiple="true" /> + <argument name="argN" /> + </argument> + </parameter> + </syntax> + <description> + <para>If the condition is true, then jump to labeliftrue. If false, jumps to + labeliffalse, if specified. In either case, a jump saves the return point + in the dialplan, to be returned to with a Return.</para> + </description> + </application> + <application name="Return" language="en_US"> + <synopsis> + Return from gosub routine. + </synopsis> + <syntax> + <parameter name="value"> + <para>Return value.</para> + </parameter> + </syntax> + <description> + <para>Jumps to the last label on the stack, removing it. The return <replaceable>value</replaceable>, if + any, is saved in the channel variable <variable>GOSUB_RETVAL</variable>.</para> + </description> + </application> + <application name="StackPop" language="en_US"> + <synopsis> + Remove one address from gosub stack. + </synopsis> + <syntax /> + <description> + <para>Removes last label on the stack, discarding it.</para> + </description> + </application> + ***/ static int agi_loaded = 0; static const char *app_gosub = "Gosub"; @@ -47,27 +111,6 @@ static const char *app_gosubif = "GosubIf"; static const char *app_return = "Return"; static const char *app_pop = "StackPop"; -static const char *gosub_synopsis = "Jump to label, saving return address"; -static const char *gosubif_synopsis = "Conditionally jump to label, saving return address"; -static const char *return_synopsis = "Return from gosub routine"; -static const char *pop_synopsis = "Remove one address from gosub stack"; - -static const char *gosub_descrip = -" Gosub([[context,]exten,]priority[(arg1[,...][,argN])]):\n" -"Jumps to the label specified, saving the return address.\n"; -static const char *gosubif_descrip = -" GosubIf(condition?labeliftrue[(arg1[,...])][:labeliffalse[(arg1[,...])]]):\n" -"If the condition is true, then jump to labeliftrue. If false, jumps to\n" -"labeliffalse, if specified. In either case, a jump saves the return point\n" -"in the dialplan, to be returned to with a Return.\n"; -static const char *return_descrip = -" Return([return-value]):\n" -"Jumps to the last label on the stack, removing it. The return value, if\n" -"any, is saved in the channel variable GOSUB_RETVAL.\n"; -static const char *pop_descrip = -" StackPop():\n" -"Removes last label on the stack, discarding it.\n"; - static void gosub_free(void *data); static struct ast_datastore_info stack_info = { @@ -530,10 +573,10 @@ static int load_module(void) ast_agi_register(ast_module_info->self, &gosub_agi_command); } - ast_register_application(app_pop, pop_exec, pop_synopsis, pop_descrip); - ast_register_application(app_return, return_exec, return_synopsis, return_descrip); - ast_register_application(app_gosubif, gosubif_exec, gosubif_synopsis, gosubif_descrip); - ast_register_application(app_gosub, gosub_exec, gosub_synopsis, gosub_descrip); + ast_register_application_xml(app_pop, pop_exec); + ast_register_application_xml(app_return, return_exec); + ast_register_application_xml(app_gosubif, gosubif_exec); + ast_register_application_xml(app_gosub, gosub_exec); ast_custom_function_register(&local_function); return 0; diff --git a/apps/app_system.c b/apps/app_system.c index 1f39c5a4e..688a649da 100644 --- a/apps/app_system.c +++ b/apps/app_system.c @@ -34,31 +34,68 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/channel.h" /* autoservice */ +/*** DOCUMENTATION + <application name="System" language="en_US"> + <synopsis> + Execute a system command. + </synopsis> + <syntax> + <parameter name="command" required="true"> + <para>Command to execute</para> + </parameter> + </syntax> + <description> + <para>Executes a command by using system(). If the command + fails, the console should report a fallthrough.</para> + <para>Result of execution is returned in the <variable>SYSTEMSTATUS</variable> channel variable:</para> + <variablelist> + <variable name="SYSTEMSTATUS"> + <value name="FAILURE"> + Could not execute the specified command. + </value> + <value name="SUCCESS"> + Specified command successfully executed. + </value> + </variable> + </variablelist> + </description> + </application> + <application name="TrySystem" language="en_US"> + <synopsis> + Try executing a system command. + </synopsis> + <syntax> + <parameter name="command" required="true"> + <para>Command to execute</para> + </parameter> + </syntax> + <description> + <para>Executes a command by using system().</para> + <para>Result of execution is returned in the <variable>SYSTEMSTATUS</variable> channel variable:</para> + <variablelist> + <variable name="SYSTEMSTATUS"> + <value name="FAILURE"> + Could not execute the specified command. + </value> + <value name="SUCCESS"> + Specified command successfully executed. + </value> + <value name="APPERROR"> + Specified command successfully executed, but returned error code. + </value> + </variable> + </variablelist> + </description> + </application> + + ***/ + static char *app = "System"; static char *app2 = "TrySystem"; -static char *synopsis = "Execute a system command"; - -static char *synopsis2 = "Try executing a system command"; - static char *chanvar = "SYSTEMSTATUS"; -static char *descrip = -" System(command): Executes a command by using system(). If the command\n" -"fails, the console should report a fallthrough. \n" -"Result of execution is returned in the SYSTEMSTATUS channel variable:\n" -" FAILURE Could not execute the specified command\n" -" SUCCESS Specified command successfully executed\n"; - -static char *descrip2 = -" TrySystem(command): Executes a command by using system().\n" -"on any situation.\n" -"Result of execution is returned in the SYSTEMSTATUS channel variable:\n" -" FAILURE Could not execute the specified command\n" -" SUCCESS Specified command successfully executed\n" -" APPERROR Specified command successfully executed, but returned error code\n"; - static int system_exec_helper(struct ast_channel *chan, void *data, int failmode) { int res = 0; @@ -120,8 +157,8 @@ static int load_module(void) { int res; - res = ast_register_application(app2, trysystem_exec, synopsis2, descrip2); - res |= ast_register_application(app, system_exec, synopsis, descrip); + res = ast_register_application_xml(app2, trysystem_exec); + res |= ast_register_application_xml(app, system_exec); return res; } diff --git a/apps/app_talkdetect.c b/apps/app_talkdetect.c index 9bc5e84dd..a0236b8fc 100644 --- a/apps/app_talkdetect.c +++ b/apps/app_talkdetect.c @@ -39,21 +39,39 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/dsp.h" #include "asterisk/app.h" -static char *app = "BackgroundDetect"; - -static char *synopsis = "Background a file with talk detect"; - -static char *descrip = -" BackgroundDetect(<filename>[,<sil>[,<min>[,<max>[,<analysistime>]]]]):\n" -"Plays back <filename>, waiting for interruption from a given digit (the digit\n" -"must start the beginning of a valid extension, or it will be ignored). During\n" -"the playback of the file, audio is monitored in the receive direction, and if\n" -"a period of non-silence which is greater than <min> ms yet less than <max> ms\n" -"is followed by silence for at least <sil> ms, which occurs during the first\n" -"<analysistime> ms, then the audio playback is aborted and processing jumps to\n" -"the <talk> extension, if available. If unspecified, <sil>, <min>, <max>, and\n" -"<analysistime> default to 1000, 100, infinity, and infinity respectively.\n"; +/*** DOCUMENTATION + <application name="BackGroundDetect" language="en_US"> + <synopsis> + Background a file with talk detect. + </synopsis> + <syntax> + <parameter name="filename" required="true" /> + <parameter name="sil"> + <para>If not specified, defaults to <literal>1000</literal>.</para> + </parameter> + <parameter name="min"> + <para>If not specified, defaults to <literal>100</literal>.</para> + </parameter> + <parameter name="max"> + <para>If not specified, defaults to <literal>infinity</literal>.</para> + </parameter> + <parameter name="analysistime"> + <para>If not specified, defaults to <literal>infinity</literal>.</para> + </parameter> + </syntax> + <description> + <para>Plays back <replaceable>filename</replaceable>, waiting for interruption from a given digit (the digit + must start the beginning of a valid extension, or it will be ignored). During + the playback of the file, audio is monitored in the receive direction, and if + a period of non-silence which is greater than <replaceable>min</replaceable> ms yet less than + <replaceable>max</replaceable> ms is followed by silence for at least <replaceable>sil</replaceable> ms, + which occurs during the first <replaceable>analysistime</replaceable> ms, then the audio playback is + aborted and processing jumps to the <replaceable>talk</replaceable> extension, if available.</para> + </description> + </application> + ***/ +static char *app = "BackgroundDetect"; static int background_detect_exec(struct ast_channel *chan, void *data) { @@ -227,7 +245,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, background_detect_exec, synopsis, descrip); + return ast_register_application_xml(app, background_detect_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Playback with Talk Detection"); diff --git a/apps/app_transfer.c b/apps/app_transfer.c index df0c5392b..e1452bb59 100644 --- a/apps/app_transfer.c +++ b/apps/app_transfer.c @@ -36,23 +36,44 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/channel.h" +/*** DOCUMENTATION + <application name="Transfer" language="en_US"> + <synopsis> + Transfer caller to remote extension. + </synopsis> + <syntax> + <parameter name="dest" required="true" argsep="/"> + <argument name="Tech" /> + <argument name="destination" required="true" /> + </parameter> + </syntax> + <description> + <para>Requests the remote caller be transferred + to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only + an incoming call with the same channel technology will be transfered. + Note that for SIP, if you transfer before call is setup, a 302 redirect + SIP message will be returned to the caller.</para> + <para>The result of the application will be reported in the <variable>TRANSFERSTATUS</variable> + channel variable:</para> + <variablelist> + <variable name="TRANSFERSTATUS"> + <value name="SUCCESS"> + Transfer succeeded. + </value> + <value name="FAILURE"> + Transfer failed. + </value> + <value name="UNSUPPORTED"> + Transfer unsupported by channel driver. + </value> + </variable> + </variablelist> + </description> + </application> + ***/ static const char *app = "Transfer"; -static const char *synopsis = "Transfer caller to remote extension"; - -static const char *descrip = -" Transfer([Tech/]dest): Requests the remote caller be transferred\n" -"to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only\n" -"an incoming call with the same channel technology will be transfered.\n" -"Note that for SIP, if you transfer before call is setup, a 302 redirect\n" -"SIP message will be returned to the caller.\n" -"\nThe result of the application will be reported in the TRANSFERSTATUS\n" -"channel variable:\n" -" SUCCESS Transfer succeeded\n" -" FAILURE Transfer failed\n" -" UNSUPPORTED Transfer unsupported by channel driver\n"; - static int transfer_exec(struct ast_channel *chan, void *data) { int res; @@ -115,7 +136,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, transfer_exec, synopsis, descrip); + return ast_register_application_xml(app, transfer_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Transfers a caller to another extension"); diff --git a/apps/app_url.c b/apps/app_url.c index f71b32fd0..e20159f5a 100644 --- a/apps/app_url.c +++ b/apps/app_url.c @@ -34,24 +34,49 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/channel.h" -static char *app = "SendURL"; - -static char *synopsis = "Send a URL"; +/*** DOCUMENTATION + <application name="SendURL" language="en_US"> + <synopsis> + Send a URL. + </synopsis> + <syntax> + <parameter name="URL" required="true" /> + <parameter name="option"> + <optionlist> + <option name="w"> + <para>Execution will wait for an acknowledgement that the + URL has been loaded before continuing.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>Requests client go to <replaceable>URL</replaceable> (IAX2) or sends the + URL to the client (other channels).</para> + <para>Result is returned in the <variable>SENDURLSTATUS</variable> channel variable:</para> + <variablelist> + <variable name="SENDURLSTATUS"> + <value name="SUCCESS"> + URL successfully sent to client. + </value> + <value name="FAILURE"> + Failed to send URL. + </value> + <value name="NOLOAD"> + Client failed to load URL (wait enabled). + </value> + <value name="UNSUPPORTED"> + Channel does not support URL transport. + </value> + </variable> + </variablelist> + <para>SendURL continues normally if the URL was sent correctly or if the channel + does not support HTML transport. Otherwise, the channel is hung up.</para> + </description> + </application> + ***/ -static char *descrip = -" SendURL(URL[,option]): Requests client go to URL (IAX2) or sends the \n" -"URL to the client (other channels).\n" -"Result is returned in the SENDURLSTATUS channel variable:\n" -" SUCCESS URL successfully sent to client\n" -" FAILURE Failed to send URL\n" -" NOLOAD Client failed to load URL (wait enabled)\n" -" UNSUPPORTED Channel does not support URL transport\n" -"\n" -"If the option 'w' is specified, execution will wait for an\n" -"acknowledgement that the URL has been loaded before continuing\n" -"\n" -"SendURL continues normally if the URL was sent correctly or if the channel\n" -"does not support HTML transport. Otherwise, the channel is hung up.\n"; +static char *app = "SendURL"; enum { OPTION_WAIT = (1 << 0), @@ -143,7 +168,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, sendurl_exec, synopsis, descrip); + return ast_register_application_xml(app, sendurl_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Send URL Applications"); diff --git a/apps/app_userevent.c b/apps/app_userevent.c index 91d067d54..6d6354af6 100644 --- a/apps/app_userevent.c +++ b/apps/app_userevent.c @@ -30,21 +30,31 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/manager.h" #include "asterisk/app.h" -static char *app = "UserEvent"; - -static char *synopsis = "Send an arbitrary event to the manager interface"; - -static char *descrip = -" UserEvent(eventname[,body]): Sends an arbitrary event to the manager\n" -"interface, with an optional body representing additional arguments. The\n" -"body may be specified as a | delimeted list of headers. Each additional\n" -"argument will be placed on a new line in the event. The format of the\n" -"event will be:\n" -" Event: UserEvent\n" -" UserEvent: <specified event name>\n" -" [body]\n" -"If no body is specified, only Event and UserEvent headers will be present.\n"; +/*** DOCUMENTATION + <application name="UserEvent" language="en_US"> + <synopsis> + Send an arbitrary event to the manager interface. + </synopsis> + <syntax> + <parameter name="eventname" required="true" /> + <parameter name="body" /> + </syntax> + <description> + <para>Sends an arbitrary event to the manager interface, with an optional + <replaceable>body</replaceable> representing additional arguments. The + <replaceable>body</replaceable> may be specified as + a <literal>|</literal> delimeted list of headers. Each additional + argument will be placed on a new line in the event. The format of the + event will be:</para> + <para> Event: UserEvent</para> + <para> UserEvent: <specified event name></para> + <para> [body]</para> + <para>If no <replaceable>body</replaceable> is specified, only Event and UserEvent headers will be present.</para> + </description> + </application> + ***/ +static char *app = "UserEvent"; static int userevent_exec(struct ast_channel *chan, void *data) { @@ -83,7 +93,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, userevent_exec, synopsis, descrip); + return ast_register_application_xml(app, userevent_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Custom User Event Application"); diff --git a/apps/app_verbose.c b/apps/app_verbose.c index 525cc1c55..b4c6a6384 100644 --- a/apps/app_verbose.c +++ b/apps/app_verbose.c @@ -33,16 +33,43 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/channel.h" static char *app_verbose = "Verbose"; -static char *verbose_synopsis = "Send arbitrary text to verbose output"; -static char *verbose_descrip = -"Verbose([<level>,]<message>)\n" -" level must be an integer value. If not specified, defaults to 0.\n"; - static char *app_log = "Log"; -static char *log_synopsis = "Send arbitrary text to a selected log level"; -static char *log_descrip = -"Log(<level>,<message>)\n" -" level must be one of ERROR, WARNING, NOTICE, DEBUG, VERBOSE, DTMF\n"; + +/*** DOCUMENTATION + <application name="Verbose" language="en_US"> + <synopsis> + Send arbitrary text to verbose output. + </synopsis> + <syntax> + <parameter name="level"> + <para>Must be an integer value. If not specified, defaults to 0.</para> + </parameter> + <parameter name="message" required="true"> + <para>Output text message.</para> + </parameter> + </syntax> + <description> + <para>Sends an arbitrary text message to verbose output.</para> + </description> + </application> + <application name="Log" language="en_US"> + <synopsis> + Send arbitrary text to a selected log level. + </synopsis> + <syntax> + <parameter name="level"> + <para>Level must be one of <literal>ERROR</literal>, <literal>WARNING</literal>, <literal>NOTICE</literal>, + <literal>DEBUG</literal>, <literal>VERBOSE</literal> or <literal>DTMF</literal>.</para> + </parameter> + <parameter name="message" required="true"> + <para>Output text message.</para> + </parameter> + </syntax> + <description> + <para>Sends an arbitrary text message to a selected log level.</para> + </description> + </application> + ***/ static int verbose_exec(struct ast_channel *chan, void *data) @@ -149,8 +176,8 @@ static int load_module(void) { int res; - res = ast_register_application(app_log, log_exec, log_synopsis, log_descrip); - res |= ast_register_application(app_verbose, verbose_exec, verbose_synopsis, verbose_descrip); + res = ast_register_application_xml(app_log, log_exec); + res |= ast_register_application_xml(app_verbose, verbose_exec); return res; } diff --git a/apps/app_waituntil.c b/apps/app_waituntil.c index 8b903b0ba..0b6ccc677 100644 --- a/apps/app_waituntil.c +++ b/apps/app_waituntil.c @@ -34,15 +34,38 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/pbx.h" #include "asterisk/module.h" +/*** DOCUMENTATION + <application name="WaitUntil" language="en_US"> + <synopsis> + Wait (sleep) until the current time is the given epoch. + </synopsis> + <syntax> + <parameter name="epoch" required="true" /> + </syntax> + <description> + <para>Waits until the given <replaceable>epoch</replaceable>.</para> + <para>Sets <variable>WAITUNTILSTATUS</variable> to one of the following values:</para> + <variablelist> + <variable name="WAITUNTILSTATUS"> + <value name="OK"> + Wait succeeded. + </value> + <value name="FAILURE"> + Invalid argument. + </value> + <value name="HANGUP"> + Channel hungup before time elapsed. + </value> + <value name="PAST"> + Time specified had already past. + </value> + </variable> + </variablelist> + </description> + </application> + ***/ + static char *app = "WaitUntil"; -static char *synopsis = "Wait (sleep) until the current time is the given epoch"; -static char *descrip = -" WaitUntil(<epoch>): Waits until the given time. Sets WAITUNTILSTATUS to\n" -"one of the following values:\n" -" OK Wait succeeded\n" -" FAILURE Invalid argument\n" -" HANGUP Channel hung up before time elapsed\n" -" PAST The time specified was already past\n"; static int waituntil_exec(struct ast_channel *chan, void *data) { @@ -89,7 +112,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, waituntil_exec, synopsis, descrip); + return ast_register_application_xml(app, waituntil_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Wait until specified time"); diff --git a/apps/app_while.c b/apps/app_while.c index 822458663..796244702 100644 --- a/apps/app_while.c +++ b/apps/app_while.c @@ -33,29 +33,72 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/channel.h" -static char *start_app = "While"; -static char *start_desc = -" While(<expr>): Start a While Loop. Execution will return to this\n" -"point when EndWhile() is called until expr is no longer true.\n"; - -static char *start_synopsis = "Start a while loop"; - +/*** DOCUMENTATION + <application name="While" language="en_US"> + <synopsis> + Start a while loop. + </synopsis> + <syntax> + <parameter name="expr" required="true" /> + </syntax> + <description> + <para>Start a While Loop. Execution will return to this point when + <literal>EndWhile()</literal> is called until expr is no longer true.</para> + </description> + <see-also> + <ref type="application">EndWhile</ref> + <ref type="application">ExitWhile</ref> + <ref type="application">ContinueWhile</ref> + </see-also> + </application> + <application name="EndWhile" language="en_US"> + <synopsis> + End a while loop. + </synopsis> + <syntax /> + <description> + <para>Return to the previous called <literal>While()</literal>.</para> + </description> + <see-also> + <ref type="application">While</ref> + <ref type="application">ExitWhile</ref> + <ref type="application">ContinueWhile</ref> + </see-also> + </application> + <application name="ExitWhile" language="en_US"> + <synopsis> + End a While loop. + </synopsis> + <syntax /> + <description> + <para>Exits a <literal>While()</literal> loop, whether or not the conditional has been satisfied.</para> + </description> + <see-also> + <ref type="application">While</ref> + <ref type="application">EndWhile</ref> + <ref type="application">ContinueWhile</ref> + </see-also> + </application> + <application name="ContinueWhile" language="en_US"> + <synopsis> + Restart a While loop. + </synopsis> + <syntax /> + <description> + <para>Returns to the top of the while loop and re-evaluates the conditional.</para> + </description> + <see-also> + <ref type="application">While</ref> + <ref type="application">EndWhile</ref> + <ref type="application">ExitWhile</ref> + </see-also> + </application> + ***/ +static char *start_app = "While"; static char *stop_app = "EndWhile"; -static char *stop_desc = -" EndWhile(): Return to the previous called While()\n"; - -static char *stop_synopsis = "End a while loop"; - static char *exit_app = "ExitWhile"; -static char *exit_desc = -" ExitWhile(): Exits a While() loop, whether or not the conditional has been satisfied.\n"; -static char *exit_synopsis = "End a While loop"; - static char *continue_app = "ContinueWhile"; -static char *continue_desc = -" ContinueWhile(): Returns to the top of the while loop and re-evaluates the conditional.\n"; -static char *continue_synopsis = "Restart a While loop"; #define VAR_SIZE 64 @@ -295,10 +338,10 @@ static int load_module(void) { int res; - res = ast_register_application(start_app, while_start_exec, start_synopsis, start_desc); - res |= ast_register_application(stop_app, while_end_exec, stop_synopsis, stop_desc); - res |= ast_register_application(exit_app, while_exit_exec, exit_synopsis, exit_desc); - res |= ast_register_application(continue_app, while_continue_exec, continue_synopsis, continue_desc); + res = ast_register_application_xml(start_app, while_start_exec); + res |= ast_register_application_xml(stop_app, while_end_exec); + res |= ast_register_application_xml(exit_app, while_exit_exec); + res |= ast_register_application_xml(continue_app, while_continue_exec); return res; } diff --git a/apps/app_zapateller.c b/apps/app_zapateller.c index 2641e69b4..bf9408090 100644 --- a/apps/app_zapateller.c +++ b/apps/app_zapateller.c @@ -37,23 +37,42 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/translate.h" #include "asterisk/app.h" -static char *app = "Zapateller"; - -static char *synopsis = "Block telemarketers with SIT"; - -static char *descrip = -" Zapateller(options): Generates special information tone to block\n" -"telemarketers from calling you. Options is a pipe-delimited list of\n" -"options. The following options are available:\n" -" 'answer' - causes the line to be answered before playing the tone,\n" -" 'nocallerid' - causes Zapateller to only play the tone if there is no\n" -" callerid information available. Options should be\n" -" separated by , characters\n\n" -" This application will set the following channel variable upon completion:\n" -" ZAPATELLERSTATUS - This will contain the last action accomplished by the\n" -" Zapateller application. Possible values include:\n" -" NOTHING | ANSWERED | ZAPPED\n\n"; +/*** DOCUMENTATION + <application name="Zapateller" language="en_US"> + <synopsis> + Block telemarketers with SIT. + </synopsis> + <syntax> + <parameter name="options" required="true"> + <para>Comma delimited list of options.</para> + <optionlist> + <option name="answer"> + <para>Causes the line to be answered before playing the tone.</para> + </option> + <option name="nocallerid"> + <para>Causes Zapateller to only play the tone if there is no + callerid information available.</para> + </option> + </optionlist> + </parameter> + </syntax> + <description> + <para>Generates special information tone to block telemarketers from calling you.</para> + <para>This application will set the following channel variable upon completion:</para> + <variablelist> + <variable name="ZAPATELLERSTATUS"> + <para>This will contain the last action accomplished by the + Zapateller application. Possible values include:</para> + <value name="NOTHING" /> + <value name="ANSWERED" /> + <value name="ZAPPED" /> + </variable> + </variablelist> + </description> + </application> + ***/ +static char *app = "Zapateller"; static int zapateller_exec(struct ast_channel *chan, void *data) { @@ -107,7 +126,7 @@ static int unload_module(void) static int load_module(void) { - return ((ast_register_application(app, zapateller_exec, synopsis, descrip)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); + return ((ast_register_application_xml(app, zapateller_exec)) ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_SUCCESS); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Block Telemarketers with Special Information Tone"); |