[asterisk-commits] mvanbaak: branch group/appdocsxml r129435 - in /team/group/appdocsxml: apps/ ...

SVN commits to the Asterisk project asterisk-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="&amp;">
+		<parameter name="Technology/Resource" required="true" argsep="&amp;">
 			<argument name="Technology2/Resource2">
 				Optional extra 'devices' to dial.
 				If you need more then one enter them like this:
 				Technology2/Resource2&amp;Technology3/Resourse3&amp;.....
 			</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:&lt;context&gt;^&lt;exten&gt;^&lt;priority&gt;">
-					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:&lt;context&gt;^&lt;exten&gt;^&lt;priority&gt;">
-					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:&lt;context&gt;^&lt;exten&gt;^&lt;priority&gt;">
+						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:&lt;context&gt;^&lt;exten&gt;^&lt;priority&gt;">
+						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 asterisk-commits mailing list