[Asterisk-code-review] app dial/app queue: Update application option documentation (asterisk[16])
Richard Mudgett
asteriskteam at digium.com
Thu Oct 18 17:22:46 CDT 2018
Richard Mudgett has uploaded this change for review. ( https://gerrit.asterisk.org/10517
Change subject: app_dial/app_queue: Update application option documentation
......................................................................
app_dial/app_queue: Update application option documentation
* Update the post-answer documentation and example. The Dial example was
incorrect and misleading for the post-answer subroutine useage.
* Fix note and warning paragraphs in option descriptions. They don't show
up in the wiki.
Change-Id: I81019a1fd75d5b9151f76b52c38e2a90da682d14
---
M apps/app_dial.c
M apps/app_queue.c
2 files changed, 44 insertions(+), 67 deletions(-)
git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/17/10517/1
diff --git a/apps/app_dial.c b/apps/app_dial.c
index 6c6547d..e4689e1 100644
--- a/apps/app_dial.c
+++ b/apps/app_dial.c
@@ -142,11 +142,9 @@
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>
- <note>
- <para>Many SIP and ISDN phones cannot send DTMF digits until the call is
- connected. If you wish to use this option with these phones, you
- can use the <literal>Answer</literal> application before dialing.</para>
- </note>
+ <para>NOTE: Many SIP and ISDN phones cannot send DTMF digits until the call is
+ connected. If you wish to use this option with these phones, you
+ can use the <literal>Answer</literal> application before dialing.</para>
</option>
<option name="D" argsep=":">
<argument name="called" />
@@ -177,21 +175,15 @@
<argument name="priority" required="true" />
<para>When the caller hangs up, transfer the <emphasis>called</emphasis> party
to the specified destination and <emphasis>start</emphasis> execution at that location.</para>
- <note>
- <para>Any channel variables you want the called channel to inherit from the caller channel must be
- prefixed with one or two underbars ('_').</para>
- </note>
+ <para>NOTE: Any channel variables you want the called channel to inherit from the caller channel must be
+ prefixed with one or two underbars ('_').</para>
</option>
<option name="F">
<para>When the caller hangs up, transfer the <emphasis>called</emphasis> party to the next priority of the current extension
and <emphasis>start</emphasis> execution at that location.</para>
- <note>
- <para>Any channel variables you want the called channel to inherit from the caller channel must be
- prefixed with one or two underbars ('_').</para>
- </note>
- <note>
- <para>Using this option from a Macro() or GoSub() might not make sense as there would be no return points.</para>
- </note>
+ <para>NOTE: Any channel variables you want the called channel to inherit from the caller channel must be
+ prefixed with one or two underbars ('_').</para>
+ <para>NOTE: Using this option from a Macro() or GoSub() might not make sense as there would be no return points.</para>
</option>
<option name="g">
<para>Proceed with dialplan execution at the next priority in the current extension if the
@@ -204,9 +196,7 @@
<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>
+ <para>NOTE: You cannot use any additional action post answer options in conjunction with this option.</para>
</option>
<option name="h">
<para>Allow the called party to hang up by sending the DTMF sequence
@@ -215,12 +205,10 @@
<option name="H">
<para>Allow the calling party to hang up by sending the DTMF sequence
defined for disconnect in <filename>features.conf</filename>.</para>
- <note>
- <para>Many SIP and ISDN phones cannot send DTMF digits until the call is
- connected. If you wish to allow DTMF disconnect before the dialed
- party answers with these phones, you can use the <literal>Answer</literal>
- application before dialing.</para>
- </note>
+ <para>NOTE: Many SIP and ISDN phones cannot send DTMF digits until the call is
+ connected. If you wish to allow DTMF disconnect before the dialed
+ party answers with these phones, you can use the <literal>Answer</literal>
+ application before dialing.</para>
</option>
<option name="i">
<para>Asterisk will ignore any forwarding requests it may receive on this dial attempt.</para>
@@ -316,18 +304,14 @@
</value>
</variable>
</variablelist>
- <note>
- <para>You cannot use any additional action post answer options in conjunction
- with this option. Also, pbx services are run on the peer (called) channel,
- so you will not be able to set timeouts via the <literal>TIMEOUT()</literal> function in this macro.</para>
- </note>
- <warning><para>Be aware of the limitations that macros have, specifically with regards to use of
+ <para>NOTE: You cannot use any additional action post answer options in conjunction
+ with this option. Also, pbx services are run on the peer (called) channel,
+ so you will not be able to set timeouts via the <literal>TIMEOUT()</literal> function in this macro.</para>
+ <para>WARNING: Be aware of the limitations that macros have, specifically with regards to use of
the <literal>WaitExten</literal> application. For more information, see the documentation for
- <literal>Macro()</literal>.</para></warning>
- <note>
- <para>Macros are deprecated, GoSub should be used instead,
- see the <literal>U</literal> option.</para>
- </note>
+ <literal>Macro()</literal>.</para>
+ <para>NOTE: Macros are deprecated, GoSub should be used instead,
+ see the <literal>U</literal> option.</para>
</option>
<option name="n">
<argument name="delete">
@@ -392,10 +376,8 @@
to send no cause. See the <filename>causes.h</filename> file for the
full list of valid causes and names.
</para>
- <note>
- <para>chan_sip does not support setting the cause on a CANCEL to anything
- other than ANSWERED_ELSEWHERE.</para>
- </note>
+ <para>NOTE: chan_sip does not support setting the cause on a CANCEL to anything
+ other than ANSWERED_ELSEWHERE.</para>
</option>
<option name="r">
<para>Default: Indicate ringing to the calling party, even if the called party isn't actually ringing. Pass no audio to the calling
@@ -430,7 +412,8 @@
</option>
<option name="U" argsep="^">
<argument name="x" required="true">
- <para>Name of the subroutine to execute via <literal>Gosub</literal></para>
+ <para>Name of the subroutine context to execute via <literal>Gosub</literal>.
+ The subroutine execution starts in the named context at the s exten and priority 1.</para>
</argument>
<argument name="arg" multiple="true" required="false">
<para>Arguments for the <literal>Gosub</literal> routine</para>
@@ -459,11 +442,9 @@
</value>
</variable>
</variablelist>
- <note>
- <para>You cannot use any additional action post answer options in conjunction
- with this option. Also, pbx services are run on the peer (called) channel,
- so you will not be able to set timeouts via the <literal>TIMEOUT()</literal> function in this routine.</para>
- </note>
+ <para>NOTE: You cannot use any additional action post answer options in conjunction
+ with this option. Also, pbx services are run on the <emphasis>called</emphasis> channel,
+ so you will not be able to set timeouts via the <literal>TIMEOUT()</literal> function in this routine.</para>
</option>
<option name="u">
<argument name = "x" required="true">
@@ -548,27 +529,29 @@
<example title="Dial with pre-dial subroutines">
[default]
- exten => callee_channel,1,NoOp()
+ exten => callee_channel,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Log(NOTICE, I'm called on channel ${CHANNEL} prior to it starting the dial attempt)
same => n,Return()
- exten => called_channel,1,NoOp()
+ exten => called_channel,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Log(NOTICE, I'm called on outbound channel ${CHANNEL} prior to it being used to dial someone)
same => n,Return()
exten => _X.,1,NoOp()
- same => n,Dial(PJSIP/alice,,b(default^called_channel^1)B(default^callee_channel^1))
+ same => n,Dial(PJSIP/alice,,b(default^called_channel^1(my_gosub_arg1^my_gosub_arg2))B(default^callee_channel^1(my_gosub_arg1^my_gosub_arg2)))
same => n,Hangup()
</example>
<example title="Dial with post-answer subroutine executed on outbound channel">
- [default]
+ [my_gosub_routine]
- exten => called_channel,1,NoOp()
+ exten => s,1,NoOp(ARG1=${ARG1} ARG2=${ARG2})
same => n,Playback(hello)
same => n,Return()
+ [default]
+
exten => _X.,1,NoOp()
- same => n,Dial(PJSIP/alice,,U(default^called_channel^1))
+ same => n,Dial(PJSIP/alice,,U(my_gosub_routine^my_gosub_arg1^my_gosub_arg2))
same => n,Hangup()
</example>
<example title="Dial into ConfBridge using 'G' option">
diff --git a/apps/app_queue.c b/apps/app_queue.c
index 3dc735a..1ddf79f 100644
--- a/apps/app_queue.c
+++ b/apps/app_queue.c
@@ -169,21 +169,15 @@
<argument name="priority" required="true" />
<para>When the caller hangs up, transfer the <emphasis>called member</emphasis>
to the specified destination and <emphasis>start</emphasis> execution at that location.</para>
- <note>
- <para>Any channel variables you want the called channel to inherit from the caller channel must be
- prefixed with one or two underbars ('_').</para>
- </note>
+ <para>NOTE: Any channel variables you want the called channel to inherit from the caller channel must be
+ prefixed with one or two underbars ('_').</para>
</option>
<option name="F">
<para>When the caller hangs up, transfer the <emphasis>called member</emphasis> to the next priority of
the current extension and <emphasis>start</emphasis> execution at that location.</para>
- <note>
- <para>Any channel variables you want the called channel to inherit from the caller channel must be
- prefixed with one or two underbars ('_').</para>
- </note>
- <note>
- <para>Using this option from a Macro() or GoSub() might not make sense as there would be no return points.</para>
- </note>
+ <para>NOTE: Any channel variables you want the called channel to inherit from the caller channel must be
+ prefixed with one or two underbars ('_').</para>
+ <para>NOTE: Using this option from a Macro() or GoSub() might not make sense as there would be no return points.</para>
</option>
<option name="h">
<para>Allow <emphasis>callee</emphasis> to hang up by pressing <literal>*</literal>.</para>
@@ -256,12 +250,12 @@
</parameter>
<parameter name="macro">
<para>Will run a macro on the called party's channel (the queue member) once the parties are connected.</para>
- <note>
- <para>Macros are deprecated, GoSub should be used instead.</para>
- </note>
+ <para>NOTE: Macros are deprecated, GoSub should be used instead.</para>
</parameter>
<parameter name="gosub">
- <para>Will run a gosub on the called party's channel (the queue member) once the parties are connected.</para>
+ <para>Will run a gosub on the called party's channel (the queue member)
+ once the parties are connected. The subroutine execution starts in the
+ named context at the s exten and priority 1.</para>
</parameter>
<parameter name="rule">
<para>Will cause the queue's defaultrule to be overridden by the rule specified.</para>
--
To view, visit https://gerrit.asterisk.org/10517
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-MessageType: newchange
Gerrit-Change-Id: I81019a1fd75d5b9151f76b52c38e2a90da682d14
Gerrit-Change-Number: 10517
Gerrit-PatchSet: 1
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20181018/6dba0af9/attachment-0001.html>
More information about the asterisk-code-review
mailing list