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