[Asterisk-doc] docs extensions.xml,1.21,1.22
blitzrage
asterisk-doc@lists.digium.com
Wed, 14 Jul 2004 00:44:00 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv32367/docs
Modified Files:
extensions.xml
Log Message:
blitzrage
- add information about pattern matching
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** extensions.xml 13 Jul 2004 21:07:25 -0000 1.21
--- extensions.xml 14 Jul 2004 00:43:54 -0000 1.22
***************
*** 390,394 ****
dialplan. The format for <function>Goto()</function> is
(context,extension,priority). In our example <command>
! exten=>1,2,Goto(incoming,s,1)</command> we will send the user back to
the first priority of the 's' extension in our current context.
</para>
--- 390,394 ----
dialplan. The format for <function>Goto()</function> is
(context,extension,priority). In our example <command>
! exten => 1,2,Goto(incoming,s,1)</command> we will send the user back to
the first priority of the 's' extension in our current context.
</para>
***************
*** 423,431 ****
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
! exten=>s,2,Background('current-movies')<lineannotation> ; Play back the 'current movies' sound file</lineannotation>
exten=>s,3,Hangup()<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
! exten=>1,1,Playback('movie1')<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
exten=>1,2,Goto(incoming,s,1)<lineannotation> ; Now go back to the beginning</lineannotation>
! exten=>2,1,Playback('movie2')<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
exten=>2,2,Goto(incoming,s,1)<lineannotation> ; Now go back to the beginning</lineannotation>
exten=>0,1,Dial(Zap/1)
--- 423,431 ----
[incoming]
exten=>s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
! exten=>s,2,Background(current-movies)<lineannotation> ; Play back the 'current movies' sound file</lineannotation>
exten=>s,3,Hangup()<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
! exten=>1,1,Playback(movie1)<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
exten=>1,2,Goto(incoming,s,1)<lineannotation> ; Now go back to the beginning</lineannotation>
! exten=>2,1,Playback(movie2)<lineannotation> ; Now hangup the line if the caller doesn't press a key</lineannotation>
exten=>2,2,Goto(incoming,s,1)<lineannotation> ; Now go back to the beginning</lineannotation>
exten=>0,1,Dial(Zap/1)
***************
*** 598,602 ****
<para>
There are two types of variables, namely global variables and call variables.
! As their names imply, global variables apply to all extensions, while call
variables only apply to the current call in progress.
</para>
--- 598,602 ----
<para>
There are two types of variables, namely global variables and call variables.
! As their names imply, global variables apply to all extensions, while call
variables only apply to the current call in progress.
</para>
***************
*** 604,608 ****
<sect2>
<title>Global Variables</title>
! <para/>
</sect2>
--- 604,614 ----
<sect2>
<title>Global Variables</title>
! <para>
! Global variables are denoted using the form VARIABLE_NAME=value. Global
! variables are useful as they allow us to use them within our dialplan to make
! it more readable, as well as only requiring us to change the the value in
! a single place instead of multiple places in our dialplan helping to reduce
! the number of possible errors.
! </para>
</sect2>
***************
*** 809,818 ****
<title>Pattern Matching</title>
<para>
- [Patterns start with "_"]
- [More specific patterns take priority, don't they?]
[Explain the ${EXTEN} variable, along with the ${EXTEN:i:j} syntax]
[Example of a simple "outbound" context]
</para>
</sect2>
<sect2>
--- 815,915 ----
<title>Pattern Matching</title>
<para>
[Explain the ${EXTEN} variable, along with the ${EXTEN:i:j} syntax]
[Example of a simple "outbound" context]
</para>
+
+ <para>
+ In extensions.conf we are not limited simply to numbers. We are able to match
+ patterns of numbers to control our call flow. To do this we start an extension
+ "number" with an underscore symbol (_). Asterisk recognizes certain characters
+ to interpret special meaning when doing a pattern match. These characters
+ include:
+
+ <simplelist>
+ <member>X - matches any digit from 0-0</member>
+ <member>Z - matches any digit from 1-9</member>
+ <member>N - matches any digit from 2-9</member>
+ <member>[1237-9] - matches any digit or letter in the brackets (ex. 1,2,3,7,8,9)</member>
+ <member>. - wildcard match which matches one or more characters</member>
+ </simplelist>
+ </para>
</sect2>
+
+ <sect2>
+ <title>Pattern Sort Order</title>
+ <para>
+ When creating your patterns take note that the order in which you add them to
+ your extensions.conf is not necessarily the order in which they are executed.
+ Asterisk will sort your extensions in numerical order followed by alphabetical
+ order. Lets use an example to show how this works.
+ </para>
+
+ <informalexample>
+ <programlisting>
+ [sort-order]
+ exten => _1NXX.,1,Dial(SIP/${EXTEN})
+ exten => _1800.,1,Dial(SIP/${EXTEN})
+ exten => _.,1,Dial(SIP/${EXTEN})
+ exten => t,1,Hangup
+ </programlisting>
+ </informalexample>
+
+ <para>
+ We can check the order in which Asterisk sorted this example by doing a
+ "show dialplan sort-order".
+
+ <screen>
+ <prompt>*CLI> </prompt> <command>show dialplan sort-order</command>
+ [ Context 'sort-order' created by 'pbx_config' ]
+ '_.' => 1. Dial(SIP/${EXTEN}) [pbx_config]
+ '_1800.' => 1. Dial(SIP/${EXTEN}) [pbx_config]
+ '_1NXX.' => 1. Dial(SIP/${EXTEN}) [pbx_config]
+ 't' => 1. Hangup() [pbx_config]
+ </screen>
+ </para>
+
+ <para>
+ As we can see the order is different than that which we placed in our
+ extensions.conf. To control the order in which Asterisk will sort the pattern
+ matching we have to use includes. When using an include the extension
+ entries within the context are sorted first followed by the included extensions.
+ The includes are then tested in the order which you add them to the context.
+ </para>
+
+ <para>
+ The following example shows how we can move the wildcard pattern (_.) to the end
+ of the sort order.
+ </para>
+
+ <informalexample>
+ <programlisting>
+ [sort-order]
+ include => sort-order-wildcard
+ exten => _1NXX.,1,Dial(SIP/${EXTEN})
+ exten => _1800.,1,Dial(SIP/${EXTEN})
+ exten => t,1,Hangup
+
+ [sort-order-wildcard]
+ exten => _.,1,Dial(SIP/${EXTEN})
+ </programlisting>
+ </informalexample>
+
+ <para>
+ <screen>
+ <prompt>*CLI> </prompt> <command>show dialplan sort-order</command>
+ [ Context 'sort-order' created by 'pbx_config' ]
+ '_1800.' => 1. Dial(SIP/${EXTEN}) [pbx_config]
+ '_1NXX.' => 1. Dial(SIP/${EXTEN}) [pbx_config]
+ 't' => 1. Hangup() [pbx_config]
+
+ Include => 'sort-order-wildcard' [pbx_config]
+ </screen>
+
+ As we can see, the sort-order-wildcard has been moved to the end of our
+ dialplan. This allows us to control the order in which Asterisk will sort
+ our exten lines.
+ </para>
+ </sect2>
+
<sect2>