[svn-commits] mvanbaak: branch group/appdocsxml r129435 - in /team/group/appdocsxml: apps/ ...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Wed Jul 9 12:38:03 CDT 2008
Author: mvanbaak
Date: Wed Jul 9 12:38:02 2008
New Revision: 129435
URL: http://svn.digium.com/view/asterisk?view=rev&rev=129435
Log:
make the options/arguments/parameters documentation more consistent.
Idea from Jared Smith on the -dev list
ok russell and lmadsen
Modified:
team/group/appdocsxml/apps/app_dial.c
team/group/appdocsxml/doc/xmldocumentation.txt
Modified: team/group/appdocsxml/apps/app_dial.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/apps/app_dial.c?view=diff&rev=129435&r1=129434&r2=129435
==============================================================================
--- team/group/appdocsxml/apps/app_dial.c (original)
+++ team/group/appdocsxml/apps/app_dial.c Wed Jul 9 12:38:02 2008
@@ -112,275 +112,277 @@
</value>
<value name="INVALIDARGS" />
</variable>
- <option name="Technology/Resource" required="true" argsep="&">
+ <parameter name="Technology/Resource" required="true" argsep="&">
<argument name="Technology2/Resource2">
Optional extra 'devices' to dial.
If you need more then one enter them like this:
Technology2/Resource2&Technology3/Resourse3&.....
</argument>
Device to dial
- </option>
- <option name="A">
- <argument name="x" required="true">
- The file to play to the called party
- </argument>
- Play an announcement to the called party, using 'x' as the file
- </option>
- <option name="C">
- Reset the CDR for this call.
- </option>
- <option name="c">
- If DIAL cancels this call, always set the flag to tell the channel
- driver that the call is answered elsewhere.
- </option>
- <option name="d">
- 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 EXITCONTEXT variable,
- if it exists.
- </option>
- <option name="D" argsep=":">
- <argument name="called" />
- <argument name="calling" />
- Send the specified DTMF strings *after* the called\n
- party has answered, but before the call gets bridged. The 'called'
- DTMF string is sent to the called party, and the 'calling' DTMF
- string is sent to the calling party. Both parameters can be used
- alone.
- </option>
- <option name="e">
- execute the 'h' extension for peer after the call ends
- </option>
- <option name="f">
- Force the callerid of the *calling* channel to be set as the
- extension associated with the channel using a dialplan 'hint'.
- For example, some PSTNs do not allow CallerID to be set to anything
- other than the number assigned to the caller.
- </option>
- <option name="F" argsep="^">
- <argument name="context" />
- <argument name="exten" />
- <argument name="pri" required="true" />
- When the caller hangs up, transfer the called party
- to the specified context and extension and continue execution.
- </option>
- <option name="g">
- Proceed with dialplan execution at the current extension if the
- destination channel hangs up.
- </option>
- <option name="G" argsep="^">
- <argument name="context" />
- <argument name="exten" />
- <argument name="pri" required="true" />
- If the call is answered, transfer the calling party to
- the specified priority and the called party to the specified priority+1.
- Optionally, an extension, or extension and context may be specified.
- Otherwise, the current extension is used. You cannot use any additional
- action post answer options in conjunction with this option.
- </option>
- <option name="h">
- Allow the called party to hang up by sending the '*' DTMF digit.
- </option>
- <option name="H">
- Allow the calling party to hang up by hitting the '*' DTMF digit.
- </option>
- <option name="i">
- Asterisk will ignore any forwarding requests it may receive on this
- dial attempt.
- </option>
- <option name="k">
- Allow the called party to enable parking of the call by sending
- the DTMF sequence defined for call parking in features.conf.
- </option>
- <option name="K">
- Allow the calling party to enable parking of the call by sending
- the DTMF sequence defined for call parking in features.conf.
- </option>
- <option name="L" args="x,y,z" argsep=":">
- <argument name="x" required="true">
- Maximum calltime in miliseconds
- </argument>
- <argument name="y" />
- <argument name="z" />
- Limit the call to 'x' ms. Play a warning when 'y' ms are
- left. Repeat the warning every 'z' ms.
- <variable name="LIMIT_PLAYAUDIO_CALLER">
- <value name="yes" default="true" />
- <value name="no" />
- Play sounds to the caller.
- </variable>
- <variable name="LIMIT_PLAYAUDIO_CALLEE">
- <value name="yes" />
- <value name="no" />
- Play sounds to the callee.
- </variable>
- <variable name="LIMIT_TIMEOUT_FILE">
- <value name="filename">
- If not set, the time remaining will be said.
- </value>
- File to play when time is up.
- </variable>
- <variable name="LIMIT_CONNECT_FILE">
- <value name="filename">
- If not set, the time remaining will be said.
- </value>
- File to play when call begins.
- </variable>
- <variable name="LIMIT_WARNING_FILE">
- <value name="filename">
- If not set, the time remaining will be said.
- </value>
- File to play as warning if 'y' is defined.
- </variable>
- </option>
- <option name="m">
- <argument name="class" />
- Provide hold music to the calling party until a requested
- channel answers. A specific MusicOnHold class can be
- specified.
- </option>
- <option name="M" args="x,arg" argsep="^">
- <argument name="x" required="true">
- Macro name that should be executed.
- </argument>
- <argument name="arg">
- Macro arguments seperated by ^
- </argument>
- Execute the Macro for the *called* channel before connecting
- to the calling channel. Arguments can be specified to the Macro
- using '^' as a delimiter. The Macro can set the variable
- MACRO_RESULT to specify the following actions after the Macro is
- finished executing.
- <variable name="MACRO_RESULT">
- If set, this action will be taken after the macro finished executing.
- <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>
- <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>
- 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.
- </option>
- <option name="n">
- This option is a modifier for the screen/privacy mode. It specifies
- that no introductions are to be saved in the priv-callerintros
- directory.
- </option>
- <option name="N">
- This option is a modifier for the screen/privacy mode. It specifies
- that if callerID is present, do not screen the call.
- </option>
- <option name="o">
- Specify that the CallerID that was present on the *calling* channel
- be set as the CallerID on the *called* channel. This was the
- behavior of Asterisk 1.0 and earlier.
- </option>
- <option name="O">
- <argument name="x" />
- "Operator Services" mode (Zaptel channel to Zaptel channel
- only, if specified on non-Zaptel interface, 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 hangs up (the operator). Specified
- without an arg, or with 1 as an arg, the originator hanging up
- will cause the phone to ring back immediately. With a 2 specified,
- when the "operator" flashes the trunk, it will ring their phone
- back.
- </option>
- <option name="p">
- This option enables screening mode. This is basically Privacy mode
- without memory.
- </option>
- <option name="P">
- <argument name="x" />
- Enable privacy mode. Use 'x' as the family/key in the database if
- it is provided. The current extension is used if a database
- family/key is not specified.
- </option>
- <option name="r">
- Indicate ringing to the calling party. Pass no audio to the calling
- party until the called channel has answered.
- </option>
- <option name="S">
- <argument name="x" required="true" />
- Hang up the call after 'x' seconds *after* the called party has
- answered the call.
- </option>
- <option name="t">
- Allow the called party to transfer the calling party by sending the
- DTMF sequence defined in features.conf.
- </option>
- <option name="T">
- Allow the calling party to transfer the called party by sending the
- DTMF sequence defined in features.conf.
- </option>
- <option name="U" argsep="^">
- <argument name="x" required="true">
- routine to execute via Gosub
- </argument>
- <argument name="arg">
- Arguments for the Gosub routine
- </argument>
- Execute via Gosub the routine 'x' for the *called* channel before connecting
- to the calling channel. Arguments can be specified to the Gosub
- using '^' as a delimiter. The Gosub routine can set the variable
- GOSUB_RESULT to specify the following actions after the Gosub returns.
- <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>
- <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>
- 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.
- </option>
- <option name="w">
- Allow the called party to enable recording of the call by sending
- the DTMF sequence defined for one-touch recording in features.conf.
- </option>
- <option name="W">
- Allow the calling party to enable recording of the call by sending
- the DTMF sequence defined for one-touch recording in features.conf.
- </option>
- <option name="x">
- Allow the called party to enable recording of the call by sending
- the DTMF sequence defined for one-touch automixmonitor in features.conf
- </option>
- <option name="X">
- Allow the calling party to enable recording of the call by sending
- the DTMF sequence defined for one-touch automixmonitor in features.conf
- </option>
- <option name="URL">
+ </parameter>
+ <parameter name="options">
+ <option name="A">
+ <argument name="x" required="true">
+ The file to play to the called party
+ </argument>
+ Play an announcement to the called party, using 'x' as the file
+ </option>
+ <option name="C">
+ Reset the CDR for this call.
+ </option>
+ <option name="c">
+ If DIAL cancels this call, always set the flag to tell the channel
+ driver that the call is answered elsewhere.
+ </option>
+ <option name="d">
+ 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 EXITCONTEXT variable,
+ if it exists.
+ </option>
+ <option name="D" argsep=":">
+ <argument name="called" />
+ <argument name="calling" />
+ Send the specified DTMF strings *after* the called\n
+ party has answered, but before the call gets bridged. The 'called'
+ DTMF string is sent to the called party, and the 'calling' DTMF
+ string is sent to the calling party. Both parameters can be used
+ alone.
+ </option>
+ <option name="e">
+ execute the 'h' extension for peer after the call ends
+ </option>
+ <option name="f">
+ Force the callerid of the *calling* channel to be set as the
+ extension associated with the channel using a dialplan 'hint'.
+ For example, some PSTNs do not allow CallerID to be set to anything
+ other than the number assigned to the caller.
+ </option>
+ <option name="F" argsep="^">
+ <argument name="context" />
+ <argument name="exten" />
+ <argument name="pri" required="true" />
+ When the caller hangs up, transfer the called party
+ to the specified context and extension and continue execution.
+ </option>
+ <option name="g">
+ Proceed with dialplan execution at the current extension if the
+ destination channel hangs up.
+ </option>
+ <option name="G" argsep="^">
+ <argument name="context" />
+ <argument name="exten" />
+ <argument name="pri" required="true" />
+ If the call is answered, transfer the calling party to
+ the specified priority and the called party to the specified priority+1.
+ Optionally, an extension, or extension and context may be specified.
+ Otherwise, the current extension is used. You cannot use any additional
+ action post answer options in conjunction with this option.
+ </option>
+ <option name="h">
+ Allow the called party to hang up by sending the '*' DTMF digit.
+ </option>
+ <option name="H">
+ Allow the calling party to hang up by hitting the '*' DTMF digit.
+ </option>
+ <option name="i">
+ Asterisk will ignore any forwarding requests it may receive on this
+ dial attempt.
+ </option>
+ <option name="k">
+ Allow the called party to enable parking of the call by sending
+ the DTMF sequence defined for call parking in features.conf.
+ </option>
+ <option name="K">
+ Allow the calling party to enable parking of the call by sending
+ the DTMF sequence defined for call parking in features.conf.
+ </option>
+ <option name="L" args="x,y,z" argsep=":">
+ <argument name="x" required="true">
+ Maximum calltime in miliseconds
+ </argument>
+ <argument name="y" />
+ <argument name="z" />
+ Limit the call to 'x' ms. Play a warning when 'y' ms are
+ left. Repeat the warning every 'z' ms.
+ <variable name="LIMIT_PLAYAUDIO_CALLER">
+ <value name="yes" default="true" />
+ <value name="no" />
+ Play sounds to the caller.
+ </variable>
+ <variable name="LIMIT_PLAYAUDIO_CALLEE">
+ <value name="yes" />
+ <value name="no" />
+ Play sounds to the callee.
+ </variable>
+ <variable name="LIMIT_TIMEOUT_FILE">
+ <value name="filename">
+ If not set, the time remaining will be said.
+ </value>
+ File to play when time is up.
+ </variable>
+ <variable name="LIMIT_CONNECT_FILE">
+ <value name="filename">
+ If not set, the time remaining will be said.
+ </value>
+ File to play when call begins.
+ </variable>
+ <variable name="LIMIT_WARNING_FILE">
+ <value name="filename">
+ If not set, the time remaining will be said.
+ </value>
+ File to play as warning if 'y' is defined.
+ </variable>
+ </option>
+ <option name="m">
+ <argument name="class" />
+ Provide hold music to the calling party until a requested
+ channel answers. A specific MusicOnHold class can be
+ specified.
+ </option>
+ <option name="M" args="x,arg" argsep="^">
+ <argument name="x" required="true">
+ Macro name that should be executed.
+ </argument>
+ <argument name="arg">
+ Macro arguments seperated by ^
+ </argument>
+ Execute the Macro for the *called* channel before connecting
+ to the calling channel. Arguments can be specified to the Macro
+ using '^' as a delimiter. The Macro can set the variable
+ MACRO_RESULT to specify the following actions after the Macro is
+ finished executing.
+ <variable name="MACRO_RESULT">
+ If set, this action will be taken after the macro finished executing.
+ <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>
+ <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>
+ 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.
+ </option>
+ <option name="n">
+ This option is a modifier for the screen/privacy mode. It specifies
+ that no introductions are to be saved in the priv-callerintros
+ directory.
+ </option>
+ <option name="N">
+ This option is a modifier for the screen/privacy mode. It specifies
+ that if callerID is present, do not screen the call.
+ </option>
+ <option name="o">
+ Specify that the CallerID that was present on the *calling* channel
+ be set as the CallerID on the *called* channel. This was the
+ behavior of Asterisk 1.0 and earlier.
+ </option>
+ <option name="O">
+ <argument name="x" />
+ "Operator Services" mode (Zaptel channel to Zaptel channel
+ only, if specified on non-Zaptel interface, 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 hangs up (the operator). Specified
+ without an arg, or with 1 as an arg, the originator hanging up
+ will cause the phone to ring back immediately. With a 2 specified,
+ when the "operator" flashes the trunk, it will ring their phone
+ back.
+ </option>
+ <option name="p">
+ This option enables screening mode. This is basically Privacy mode
+ without memory.
+ </option>
+ <option name="P">
+ <argument name="x" />
+ Enable privacy mode. Use 'x' as the family/key in the database if
+ it is provided. The current extension is used if a database
+ family/key is not specified.
+ </option>
+ <option name="r">
+ Indicate ringing to the calling party. Pass no audio to the calling
+ party until the called channel has answered.
+ </option>
+ <option name="S">
+ <argument name="x" required="true" />
+ Hang up the call after 'x' seconds *after* the called party has
+ answered the call.
+ </option>
+ <option name="t">
+ Allow the called party to transfer the calling party by sending the
+ DTMF sequence defined in features.conf.
+ </option>
+ <option name="T">
+ Allow the calling party to transfer the called party by sending the
+ DTMF sequence defined in features.conf.
+ </option>
+ <option name="U" argsep="^">
+ <argument name="x" required="true">
+ routine to execute via Gosub
+ </argument>
+ <argument name="arg">
+ Arguments for the Gosub routine
+ </argument>
+ Execute via Gosub the routine 'x' for the *called* channel before connecting
+ to the calling channel. Arguments can be specified to the Gosub
+ using '^' as a delimiter. The Gosub routine can set the variable
+ GOSUB_RESULT to specify the following actions after the Gosub returns.
+ <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>
+ <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>
+ 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.
+ </option>
+ <option name="w">
+ Allow the called party to enable recording of the call by sending
+ the DTMF sequence defined for one-touch recording in features.conf.
+ </option>
+ <option name="W">
+ Allow the calling party to enable recording of the call by sending
+ the DTMF sequence defined for one-touch recording in features.conf.
+ </option>
+ <option name="x">
+ Allow the called party to enable recording of the call by sending
+ the DTMF sequence defined for one-touch automixmonitor in features.conf
+ </option>
+ <option name="X">
+ Allow the calling party to enable recording of the call by sending
+ the DTMF sequence defined for one-touch automixmonitor in features.conf
+ </option>
+ </parameter>
+ <parameter name="URL">
The optional URL will be sent to the called party if the channel supports it.
- </option>
+ </parameter>
</application>
<application name="RetryDial" language="en_US">
<synopsis>
Modified: team/group/appdocsxml/doc/xmldocumentation.txt
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/doc/xmldocumentation.txt?view=diff&rev=129435&r1=129434&r2=129435
==============================================================================
--- team/group/appdocsxml/doc/xmldocumentation.txt (original)
+++ team/group/appdocsxml/doc/xmldocumentation.txt Wed Jul 9 12:38:02 2008
@@ -13,10 +13,11 @@
description - required, longer description of the application
variable - optional, 1 or more nodes describing the dialplan variables this application uses
value - optional, 1 or more nodes describing the possible values of this variable
- option - optional, 1 or more nodes describing the application options
- argument - optional, 1 or more nodes describing the option arguments
- variable - optional, 1 or more nodes describing option specific variables
- value - optional, 1 or more nodes describing the possible values of this variable
+ parameter - optional, 1 or more nodes describing the application parameters
+ option - optional, 1 or more nodes describing the parameter options
+ argument - optional, 1 or more nodes describing the option arguments
+ variable - optional, 1 or more nodes describing option specific variables
+ value - optional, 1 or more nodes describing the possible values of this variable
Attributes per node:
application:
@@ -35,29 +36,24 @@
possible values:
false - This is not the default value. This is the default if the attribute is omitted.
true - This is the default value.
-option:
+parameter:
* name - required. The option name.
* argsep - optional, If the option takes arguments they will be seperated by this character
* required - optional, defines wether this option is required.
possible values:
false - This option is not required. This is the default if the attribute is omitted.
true - This option is required.
- argument:
- * name - required, The name of the option argument
- * required - optional, defines wether this argument is required.
- possible values:
- false - This argument is not required. This is the default if the attribute is omitted.
- true - This argument is required.
+ option:
+ * name - required, the option name
+ argument:
+ * name - required, The name of the option argument
+ * required - optional, defines wether this argument is required.
+ possible values:
+ false - This argument is not required. This is the default if the attribute is omitted.
+ true - This argument is required.
-There's a special option node for a lot of applications/functions.
-For example, Dial takes Technology/Resource[&Technology2/Resource2] as first, required argument.
-We decided to document this with an <option> tag in the following format:
-<option name="Technology/Resource" argsep="&" required="true">
- <argument name="Technology2/Resource2">
- Optional secondary 'device' to dial
- </argument>
- 'device' to dial
-</option>
+There's a special parameter node for the Options of an application/function
+This node has 1 or more <option name="foo"> children.
Example:
@@ -76,7 +72,7 @@
</value>
description of the variable
</variable>
- <option name="myoption" argsep="^" required="true">
+ <parameter name="myoption" argsep="^" required="true">
<argument name="foo" required="true">
argument description
</argument>
@@ -86,7 +82,7 @@
</value>
description
</variable>
- option description
- </option>
+ parameter description
+ </parameter>
</application>
***/
More information about the svn-commits
mailing list