[Asterisk-doc] docs extensions.xml,1.27,1.28
blitzrage
asterisk-doc@lists.digium.com
Thu, 22 Jul 2004 22:59:24 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20425/docs
Modified Files:
extensions.xml
Log Message:
blitzrage
- read through chapter and corrected minor typos and grammar errors
- added some more information to the chapter
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** extensions.xml 20 Jul 2004 12:45:12 -0000 1.27
--- extensions.xml 22 Jul 2004 22:59:18 -0000 1.28
***************
*** 19,23 ****
<sect1>
! <title>Introduction to creating dialplans</title>
<para>
The majority of the dialplan is specified in the file
--- 19,23 ----
<sect1>
! <title>Introduction to Creating Dialplans</title>
<para>
The majority of the dialplan is specified in the file
***************
*** 41,49 ****
If you installed the Asterisk sample files, you probably have an existing
<filename>extensions.conf</filename> file. Instead of
! modifying the existing file, we recommend your from scratch in creating
your <filename>extensions.conf</filename> file, so that you can learn
! about how each part of the file plays a role in the dialplan. (You may
want to rename your existing <filename>extensions.conf</filename> file,
! and refer to it later.)
</para>
--- 41,51 ----
If you installed the Asterisk sample files, you probably have an existing
<filename>extensions.conf</filename> file. Instead of
! modifying the existing file, we recommend you start from scratch in creating
your <filename>extensions.conf</filename> file, so that you can learn
! about how each part of the file plays a role in the dialplan. The sample
! <filename>extensions.conf</filename> is an excellent resource for learning
! about many of the variables and other subleties of dialplans. You may
want to rename your existing <filename>extensions.conf</filename> file,
! and refer to it later.
</para>
***************
*** 119,126 ****
<title>Extensions</title>
<para>
! Within each context, we will definie one or more extensions. Extensions
determine how the call flows. Although extensions can be used to
specify phone extensions in the traditional sense (i.e. Please call John
! is at extension 153), they can be used for more than that in Asterisk.
In our <filename>extensions.conf</filename> file, an extensions is
declared by the word "exten", followed by an arrow formed by the equal
--- 121,128 ----
<title>Extensions</title>
<para>
! Within each context, we will define one or more extensions. Extensions
determine how the call flows. Although extensions can be used to
specify phone extensions in the traditional sense (i.e. Please call John
! at extension 153), they can be used for more than that in Asterisk.
In our <filename>extensions.conf</filename> file, an extensions is
declared by the word "exten", followed by an arrow formed by the equal
***************
*** 138,142 ****
<programlisting>
[<emphasis>context-name</emphasis>]
! exten=><emphasis>extension</emphasis>,<emphasis>priority</emphasis>,<emphasis>application</emphasis>
</programlisting>
</informalexample>
--- 140,144 ----
<programlisting>
[<emphasis>context-name</emphasis>]
! exten => <emphasis>extension</emphasis>,<emphasis>priority</emphasis>,<emphasis>application</emphasis>
</programlisting>
</informalexample>
***************
*** 192,196 ****
<sect1>
! <title>A simple example</title>
<para>
Now we're ready to create our first <filename>extensions.conf</filename> file.
--- 194,198 ----
<sect1>
! <title>A Simple Example</title>
<para>
Now we're ready to create our first <filename>extensions.conf</filename> file.
***************
*** 246,251 ****
<para>
The <function>Playback()</function> function is used for playing a
! previously recorded sound files over a channel. When using the
! <function>Playback()</function> function, input from the user
simply ignored. If you need to accept input during playback,
use the <function>Background()</function> function. Asterisk
--- 248,253 ----
<para>
The <function>Playback()</function> function is used for playing a
! previously recorded sound file over a channel. When using the
! <function>Playback()</function> function, input from the user is
simply ignored. If you need to accept input during playback,
use the <function>Background()</function> function. Asterisk
***************
*** 253,257 ****
found in <filename class='directory'>/var/lib/asterisk/sounds/</filename>.
<function>Playback()</function> is used by specifying the filename (without
! an extension) as the argument. For example,
<function>Playback(filename)</function> would play
the sound file called <emphasis>filename</emphasis>.gsm, located in the
--- 255,259 ----
found in <filename class='directory'>/var/lib/asterisk/sounds/</filename>.
<function>Playback()</function> is used by specifying the filename (without
! a file extension) as the argument. For example,
<function>Playback(filename)</function> would play
the sound file called <emphasis>filename</emphasis>.gsm, located in the
***************
*** 284,290 ****
Now we're ready to start our first example dialplan. Please pay
attention to the way that each priority calls an application.
! (Note that in this example, we only have one extension.
In later examples we'll add other extensions, and show how to
! move from one extension to another.)
</para>
<note>
--- 286,292 ----
Now we're ready to start our first example dialplan. Please pay
attention to the way that each priority calls an application.
! Note that in this example, we only have one extension.
In later examples we'll add other extensions, and show how to
! move from one extension to another.
</para>
<note>
***************
*** 346,351 ****
by learning about the <function>Background()</function> and
<function>Goto()</function> functions. These two functions will
! allows us to create more functional dialplan.
</para>
<para>
The key to interactive Asterisk systems is the
--- 348,354 ----
by learning about the <function>Background()</function> and
<function>Goto()</function> functions. These two functions will
! allows us to create a more functional dialplan.
</para>
+
<para>
The key to interactive Asterisk systems is the
***************
*** 355,358 ****
--- 358,362 ----
the extension that corresponds with what the caller dialed.
</para>
+
<para>
Another very useful application is called
***************
*** 365,376 ****
for us to pass the destination context, extension, and priority
as arguments to the application, like this:
<informalexample>
<programlisting>
! exten=><emphasis>extension</emphasis>,<emphasis>priority</emphasis>,
! Goto(<emphasis>context</emphasis>,<emphasis>extension</emphasis>,
! <emphasis>priority</emphasis>)
</programlisting>
</informalexample>
</para>
<para>
In this example, let's assume we've been asked by a local movie
--- 369,380 ----
for us to pass the destination context, extension, and priority
as arguments to the application, like this:
+
<informalexample>
<programlisting>
! exten => <emphasis>extension</emphasis>,<emphasis>priority</emphasis>,Goto(<emphasis>context</emphasis>,<emphasis>extension</emphasis>,<emphasis>priority</emphasis>)
</programlisting>
</informalexample>
</para>
+
<para>
In this example, let's assume we've been asked by a local movie
***************
*** 383,387 ****
We'll also assume that we have three pre-recorded sound files.
The first, called <filename>current-moves.gsm</filename>, says
! "Welcome to our movie theater. To hear what's playing on screen
one, press one. To hear what's playing on screen two, press two."
The other two sound files, named <filename>movie1.gsm</filename>
--- 387,391 ----
We'll also assume that we have three pre-recorded sound files.
The first, called <filename>current-moves.gsm</filename>, says
! "Welcome to our movie theatre. To hear what's playing on screen
one, press one. To hear what's playing on screen two, press two."
The other two sound files, named <filename>movie1.gsm</filename>
***************
*** 425,430 ****
with priority one. You may notice that the 's' extesion looks almost
identical to our first example. The difference is the use of
! the <function>Background()</function> function instead of the
! <function>Playback()</function>. With <function>Background()</function>
we are able to accept digits from the caller while the sound file
is being played. While the <filename>current-movies.gsm</filename>
--- 429,434 ----
with priority one. You may notice that the 's' extesion looks almost
identical to our first example. The difference is the use of
! the <function>Background()</function> application instead of the
! <function>Playback()</function> application. With <function>Background()</function>
we are able to accept digits from the caller while the sound file
is being played. While the <filename>current-movies.gsm</filename>
***************
*** 439,446 ****
priorities for extension 1, which end up being lines 4 and 5. The
first priority for extension 1 will use the
! <function>Playback()</function> function to play the movie details
for screen one. After the file finishes playing, it will execute
the second priority, which is a call to the <function>Goto()</function>
! application. This sends the caller
<function>Goto()</function> allows us to send the caller anywhere in our
dialplan. The format for <function>Goto()</function> is
--- 443,453 ----
priorities for extension 1, which end up being lines 4 and 5. The
first priority for extension 1 will use the
! <function>Playback()</function> application to play the movie details
for screen one. After the file finishes playing, it will execute
the second priority, which is a call to the <function>Goto()</function>
! application.
! </para>
!
! <para>
<function>Goto()</function> allows us to send the caller anywhere in our
dialplan. The format for <function>Goto()</function> is
***************
*** 460,464 ****
<sect2>
! <title>The <function>Dial()</function> function</title>
<!-- <para>
[Add to our movie theater example, and make it so that if someone presses 0
--- 467,471 ----
<sect2>
! <title>The <function>Dial()</function> application</title>
<!-- <para>
[Add to our movie theater example, and make it so that if someone presses 0
***************
*** 470,474 ****
<para>
We are going to add to our movie theatre example by showing the use of the
! <function>Dial()</function> function. If someone presses 0 during the playback
it will ring the ticket office. We are going to assume that the channel for
the ticket office has already been setup. For examples of how to setup
--- 477,481 ----
<para>
We are going to add to our movie theatre example by showing the use of the
! <function>Dial()</function> application. If someone presses 0 during playback
it will ring the ticket office. We are going to assume that the channel for
the ticket office has already been setup. For examples of how to setup
***************
*** 492,496 ****
Our example has stayed the same except for the addition of another extension to
our [incoming] context. We have added a 0 extension which will then execute
! the Dial command. The <function>Dial()</function> command allows us to call
a specified interface using the format of [technology]/[resource]. In this
instance we are calling the first channel on our Zaptel interface, which
--- 499,503 ----
Our example has stayed the same except for the addition of another extension to
our [incoming] context. We have added a 0 extension which will then execute
! the Dial application. The <function>Dial()</function> application allows us to call
a specified interface using the format of [technology]/[resource]. In this
instance we are calling the first channel on our Zaptel interface, which
***************
*** 505,514 ****
-->
<para>
! By this point in the chapter you should understand the basic workings of
several applications such as <function>Answer()</function>, <function>Playback()
</function>, <function>Background()</function>, <function>Hangup()</function>,
<function>GoTo()</function> and the basics of <function>Dial()</function>. If
you are still a little unclear of how these work, please go back and read this
! section again. The basic understanding of these applications is essencial to
fully grasp the concepts which will be explored further.
</para>
--- 512,521 ----
-->
<para>
! By this point in the chapter you should understand the use of
several applications such as <function>Answer()</function>, <function>Playback()
</function>, <function>Background()</function>, <function>Hangup()</function>,
<function>GoTo()</function> and the basics of <function>Dial()</function>. If
you are still a little unclear of how these work, please go back and read this
! section again. The basic understanding of these applications is essential to
fully grasp the concepts which will be explored further.
</para>
***************
*** 520,526 ****
<para>
Asterisk has the ability to ring multiple phones for the same call. Using the
! <function>Dial()</function> function we simply add an ampersand (&) between
the two or more channels we wish to ring. In our following example we are going
! to show how the <function>Dial()</function> function can ring multiple interfaces
at the same time. This would allow you to answer the incoming channel at either
one of the ringing interfaces.
--- 527,533 ----
<para>
Asterisk has the ability to ring multiple phones for the same call. Using the
! <function>Dial()</function> application we simply add an ampersand (&) between
the two or more channels we wish to ring. In our following example we are going
! to show how the <function>Dial()</function> application can ring multiple interfaces
at the same time. This would allow you to answer the incoming channel at either
one of the ringing interfaces.
***************
*** 543,548 ****
the second priority will playback the welcome message. The <function>Dial()
</function> application uses an ampersand (&) to build a list of channels
! (Zap/2 and Zap/3 respectively) which ring concurrently when an incoming call
! executes the <function>Dial()</function> function.
</para>
</sect2>
--- 550,554 ----
the second priority will playback the welcome message. The <function>Dial()
</function> application uses an ampersand (&) to build a list of channels
! (Zap/2 and Zap/3 respectively) which ring concurrently during an incoming call.
</para>
</sect2>
***************
*** 567,577 ****
You would recognize this as any system where an auto-attendent attempted to
route your call to an appropriate department by asking you to "Press 1 for Sales,
! Press 2 for Parts or Press 0 to speak to an Operator".
</para>
</sect2>
<sect2>
! <title>Accepting User Input with the <function>Background()</function>
! Function</title>
<!-- <para>
[Explain the Background() application, and how it's different than Playback()]
--- 573,583 ----
You would recognize this as any system where an auto-attendent attempted to
route your call to an appropriate department by asking you to "Press 1 for Sales,
! Press 2 for Parts or Press 0 to speak with an Operator".
</para>
</sect2>
<sect2>
! <title>Accepting User Input With The <function>Background()</function>
! Application</title>
<!-- <para>
[Explain the Background() application, and how it's different than Playback()]
***************
*** 584,588 ****
application which will not accept input from the user until the entire file
has finished playing. What <function>Background()</function> allows us to do is
! build a list of options into a single file, which we will call "menu", to give
a user calling our system multiple options. When a user hears the option they
wish to use, they can press the appropriate button on their touch tone phone
--- 590,594 ----
application which will not accept input from the user until the entire file
has finished playing. What <function>Background()</function> allows us to do is
! build a list of options into a single file, which we will call a "menu", to give
a user calling our system multiple options. When a user hears the option they
wish to use, they can press the appropriate button on their touch tone phone
***************
*** 616,619 ****
--- 622,635 ----
</programlisting>
</informalexample>
+
+ <para>
+ After we <function>Answer()</function> the channel, we <function>Playback()</function> the
+ 'welcome' sound file which will not accept any input from the user - they are forced to listen
+ to the entire file. After the 'welcome' message finishes we execute the <function>Background()
+ </function> application to play out 'menu' file. While this is being played to the user, Asterisk
+ will wait for input and will execute any applications which match the extension
+ numbers being dialed. In the above example, if either 1 or 2 are pressed by the user,
+ they will be redirected to either channel Zap/2 or Zap/3 respectfully.
+ </para>
</sect2>
***************
*** 625,628 ****
--- 641,656 ----
and use it for calling between internal extensions.]
</para>
+
+ <para>
+ So far we have limited ourselves to a single context for incoming calls.
+ It is probably fair to assume that most installations will have more than
+ one extension, and that we would want to call between them. For this we can
+ create a new context called [internal]. This context will contain the
+ extension numbers and what channel to associate with that number. The
+ following example demonstrates that we can associate different extension
+ numbers to the same channel name in different contexts. We assume that
+ these extensions are configured to have access to the [internal] extension
+ in their own configuration file.
+ </para>
<informalexample>
***************
*** 639,643 ****
exten => 1002,1,Dial(Zap/3)<lineannotation> ; Dialing extension 1002 calls channel Zap/3</lineannotation>
</programlisting>
! </informalexample>
</sect2>
</sect1>
--- 667,679 ----
exten => 1002,1,Dial(Zap/3)<lineannotation> ; Dialing extension 1002 calls channel Zap/3</lineannotation>
</programlisting>
! </informalexample>
!
! <para>
! The above example shows that incoming calls to the [incoming] context can dial
! Zap/2 by selecting the option "1" from our menu. However we would like to
! standardize the internal extensions with 4 digit numbers. As we can see, any
! extension with access to the [internal] context can access the Zap/2 and Zap/3
! channels via extension 1001 and 1002 respectfully.
! </para>
</sect2>
</sect1>
***************
*** 657,660 ****
--- 693,706 ----
variables only apply to the current call in progress.
</para>
+
+ <note>
+ <para>
+ The terms arguments and variables are often interchanged to mean the same thing.
+ For our purposes we are going to make a firm distinction between the two.
+ Arguments are values passed to the built in applications to tell them what
+ to do. Variables are named places where data that may change is held. They
+ can either be used by the user or, much more frequently, by Asterisk itself.
+ </para>
+ </note>
<sect2>
***************
*** 663,668 ****
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>
--- 709,714 ----
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, along with only requiring us to change the the value in
! a single place instead of multiple places, helping to reduce
the number of possible errors.
</para>
***************
*** 729,733 ****
<title>What are Macros?</title>
<para>
! Macros are used to reduce the amount of redundent code in your dialplan.
This works by allowing you to pass arguments to the macro which then perform
a certain set of actions which you specify. Once you have defined your
--- 775,779 ----
<title>What are Macros?</title>
<para>
! Macros are used to reduce the amount of redundent code in the dialplan.
This works by allowing you to pass arguments to the macro which then perform
a certain set of actions which you specify. Once you have defined your
***************
*** 743,747 ****
with "macro-". The 's' extension is used within macros since we want the
actions to be performed automatically when we call them. Information is
! passed to the Macro as variables such as ${ARGn} where 'n' is the variable
number.
</para>
--- 789,793 ----
with "macro-". The 's' extension is used within macros since we want the
actions to be performed automatically when we call them. Information is
! passed to the Macro as arguments such as ${ARGn} where 'n' is the argument
number.
</para>
***************
*** 767,777 ****
<para>
! Our simple macro above Dials an extension as supplied by the variable ${ARG1}
which is defined when we call the macro. If after 20 seconds the line is not
picked up, we go to our second priority which calls Voicemail using the
extension number that called the macro (as defined by ${MACRO_EXTEN}). Once
voicemail has completed, the call is Hungup. If the line was busy when the Dial
! command was executed, the macro would jump n+101 priorities to priority 102.
! The Voicemail command would then be executed, playing the busy message for
the extension which called the macro as defined by ${MACRO_EXTEN}.
</para>
--- 813,823 ----
<para>
! Our simple macro above Dials an extension as supplied by the argument ${ARG1}
which is defined when we call the macro. If after 20 seconds the line is not
picked up, we go to our second priority which calls Voicemail using the
extension number that called the macro (as defined by ${MACRO_EXTEN}). Once
voicemail has completed, the call is Hungup. If the line was busy when the Dial
! application was executed, the macro would jump n+101 priorities to priority 102.
! The Voicemail application would then be executed, playing the busy message for
the extension which called the macro as defined by ${MACRO_EXTEN}.
</para>
***************
*** 785,791 ****
<para>
! The macro is called using the 'Macro' command. The format for calling a macro
is Macro(<macro_name>,<ARG1>,<ARG2$gt;,<ARGn>). As we can
! see in our example, we are calling the 'stdexten' macro with the variable
'SIP/1000'. SIP/1000 is then used in the stdexten macro where you see ${ARG1}.
The ${MACRO_EXTEN} is a predefined local variable which passes the extension
--- 831,837 ----
<para>
! The macro is called using the 'Macro' application. The format for calling a macro
is Macro(<macro_name>,<ARG1>,<ARG2$gt;,<ARGn>). As we can
! see in our example, we are calling the 'stdexten' macro with the argument
'SIP/1000'. SIP/1000 is then used in the stdexten macro where you see ${ARG1}.
The ${MACRO_EXTEN} is a predefined local variable which passes the extension
***************
*** 834,841 ****
macro example will Dial() SIP/1000 for 20 seconds. After the Dial() command
has completed the status of the call is saved in the variable ${DIALSTATUS}.
On the second line we use a Goto() statement to jump to the associated extension.
The format for the extension name is "s-${DIALSTATUS}" where ${DIALSTATUS} is
equal to NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION or ANSWER. If our Dial()
! command rings for 20 seconds without an answer, the ${DIALSTATUS} will contain
NOANSWER. The s-NOANSWER extension will then execute all available priorities
in order starting with the Voicemail() command (line 3) and play the unavailable
--- 880,890 ----
macro example will Dial() SIP/1000 for 20 seconds. After the Dial() command
has completed the status of the call is saved in the variable ${DIALSTATUS}.
+ </para>
+
+ <para>
On the second line we use a Goto() statement to jump to the associated extension.
The format for the extension name is "s-${DIALSTATUS}" where ${DIALSTATUS} is
equal to NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION or ANSWER. If our Dial()
! command rings for 20 seconds without an answer, the ${DIALSTATUS} variable will contain
NOANSWER. The s-NOANSWER extension will then execute all available priorities
in order starting with the Voicemail() command (line 3) and play the unavailable
***************
*** 849,853 ****
the s- means to match anything that is returned. If neither NOANSWER or BUSY are
returned, then we will assume a NOANSWER and execute the Goto() statement. This
! will send us to the s-NOANSWER context, which as explained earlier, will execute
Voicemail and play the busy message.
</para>
--- 898,902 ----
the s- means to match anything that is returned. If neither NOANSWER or BUSY are
returned, then we will assume a NOANSWER and execute the Goto() statement. This
! will send us to the s-NOANSWER extension, which as explained earlier, will execute
Voicemail and play the busy message.
</para>
***************
*** 913,917 ****
<para>
We can check the order in which Asterisk sorted this example by doing a
! "show dialplan sort-order".
<screen>
--- 962,966 ----
<para>
We can check the order in which Asterisk sorted this example by doing a
! <command>show dialplan sort-order</command>.
<screen>
***************
*** 1022,1026 ****
<para>
! Absolute Timeout is a used when a call is being terminated for exceeding a
Absolute Timeout variable set. Be aware of the case difference from the
normal timeout. This can be used to warn a user that they exceeded some
--- 1071,1075 ----
<para>
! Absolute Timeout is a used when a call is being terminated for exceeding an
Absolute Timeout variable set. Be aware of the case difference from the
normal timeout. This can be used to warn a user that they exceeded some