<p>Richard Mudgett has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.asterisk.org/10517">View Change</a></p><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;">git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/17/10517/1</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/10517">change 10517</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/10517"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 16 </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: I81019a1fd75d5b9151f76b52c38e2a90da682d14 </div>
<div style="display:none"> Gerrit-Change-Number: 10517 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Richard Mudgett <rmudgett@digium.com> </div>