[Asterisk-code-review] app dial/app queue: Update application option documentation (asterisk[13])
George Joseph
asteriskteam at digium.com
Wed Oct 24 07:47:10 CDT 2018
George Joseph has submitted this change and it was merged. ( https://gerrit.asterisk.org/10516 )
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, 41 insertions(+), 60 deletions(-)
Approvals:
George Joseph: Looks good to me, but someone else must approve; Approved for Submit
Benjamin Keith Ford: Looks good to me, but someone else must approve
Joshua Colp: Looks good to me, approved
diff --git a/apps/app_dial.c b/apps/app_dial.c
index 855945b..dbce62d 100644
--- a/apps/app_dial.c
+++ b/apps/app_dial.c
@@ -143,11 +143,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" />
@@ -178,21 +176,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
@@ -205,9 +197,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
@@ -216,12 +206,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>
@@ -317,14 +305,12 @@
</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>
+ <literal>Macro()</literal>.</para>
</option>
<option name="n">
<argument name="delete">
@@ -389,10 +375,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
@@ -427,7 +411,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>
@@ -456,11 +441,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">
@@ -545,27 +528,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 eb85c51..641debf 100644
--- a/apps/app_queue.c
+++ b/apps/app_queue.c
@@ -152,21 +152,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>
@@ -241,7 +235,9 @@
<para>Will run a macro on the called party's channel (the queue member) once the parties are connected.</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/10516
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 13
Gerrit-MessageType: merged
Gerrit-Change-Id: I81019a1fd75d5b9151f76b52c38e2a90da682d14
Gerrit-Change-Number: 10516
Gerrit-PatchSet: 1
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
Gerrit-Reviewer: Benjamin Keith Ford <bford at digium.com>
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Jenkins2 (1000185)
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20181024/0f1810db/attachment-0001.html>
More information about the asterisk-code-review
mailing list