[Asterisk-doc] docs volume-one.xml,1.1,1.2
websmith
asterisk-doc@lists.digium.com
Fri, 13 Aug 2004 06:01:19 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22141
Modified Files:
volume-one.xml
Log Message:
Added more information to the dialplan chapter, and commented out a lot
of material that wasn't appropriate for volume one. Also cleaned up
several of the examples and reworded a bunch of paragraphs.
Index: volume-one.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/volume-one.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** volume-one.xml 11 Aug 2004 14:04:01 -0000 1.1
--- volume-one.xml 13 Aug 2004 06:01:13 -0000 1.2
***************
*** 891,895 ****
<sect2>
! <title>The <function>Dial()</function> application</title>
<!-- <para>
[Add to our movie theater example, and make it so that if someone presses 0
--- 891,895 ----
<sect2>
! <title>Calling channels with the <function>Dial()</function> application</title>
<!-- <para>
[Add to our movie theater example, and make it so that if someone presses 0
***************
*** 901,919 ****
<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
! channels see Chapter 3.
</para>
<informalexample>
<programlisting>
[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)
</programlisting>
--- 901,918 ----
<para>
We are going to add to our movie theatre example by showing the use of the
! <function>Dial()</function> application. If the caller 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 set up.
</para>
<informalexample>
<programlisting>
[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)
</programlisting>
***************
*** 921,930 ****
<para>
! 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
! probably has attached to it a telephone and an operator to answer the phone.
</para>
--- 920,932 ----
<para>
! If you compare this example with the previous one, it should be quite obvious that
! all we've done is add 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 channel using the format of [technology]/[resource]. In this
! instance we are calling the first channel on our Zaptel interface (identified
! as "Zap/1"), which is most likely connected to an analog telephone. When the
! caller presses <keycap>0</keycap> at the voice menu, the phone will ring.
! If the operator answers the call, he or she will be connected to the caller.
</para>
***************
*** 944,947 ****
--- 946,954 ----
fully grasp the concepts which will be explored further.
</para>
+ <para>
+ With just a basic understanding of extensions, priorities and applications it is
+ quite simple to create a basic dialplan. In the next few sections, we'll add
+ on to this foundation and make our dialplan even more powerful.
+ </para>
</sect2>
</sect1>
***************
*** 949,952 ****
--- 956,963 ----
<sect1>
<title>Adding Additional Functionality</title>
+ <!--
+ I've commented out this section, because I've already covered most of this in the
+ above examples. I've left it here for now just in case we want to reuse some
+ wording, etc.
<para>
Asterisk has the ability to ring multiple phones for the same call. Using the
***************
*** 970,974 ****
<para>
! We are using the 's' extension in our example which as we know allows these
commands to be executed automatically. Our first priority will answer the line,
the second priority will playback the welcome message. The <function>Dial()
--- 981,985 ----
<para>
! We are using the 's' extension in our example, which as we know allows these
commands to be executed automatically. Our first priority will answer the line,
the second priority will playback the welcome message. The <function>Dial()
***************
*** 980,989 ****
<sect2>
<title>Creating Voice Menus</title>
! <!-- <para>
[Explain what IVR is, and why we want it in our dial plan]
[The <filename>menu</filename> file is a voice recording saying "Press 1 for
the Operator or 2 to speak with John"]
</para>
! -->
<para>
With Asterisk we have the ability to very simply develop custom IVR systems.
--- 991,1004 ----
<sect2>
<title>Creating Voice Menus</title>
! <para>
[Explain what IVR is, and why we want it in our dial plan]
[The <filename>menu</filename> file is a voice recording saying "Press 1 for
the Operator or 2 to speak with John"]
</para>
! <para>
! [ We need to rewrite this to be about simple auto-attendant style voice menus,
! and not complex database-driven IVRs. Besides, didn't we just cover voice menus
! a few paragraphs ago? ]
! </para>
<para>
With Asterisk we have the ability to very simply develop custom IVR systems.
***************
*** 1000,1011 ****
</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()]
</para>
- -->
<para>
The <function>Background()</function> application allows us to play a pre-recorded
--- 1015,1025 ----
</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()]
</para>
<para>
The <function>Background()</function> application allows us to play a pre-recorded
***************
*** 1023,1031 ****
<sect2>
<title>Adding a Voice Menu</title>
- <!-- <para>
[Now that we understand IVR and the Background() app,
let's use them in our example.]
</para>
- -->
<para>
--- 1037,1043 ----
***************
*** 1056,1093 ****
they will be redirected to either channel Zap/2 or Zap/3 respectfully.
</para>
-
</sect2>
<sect2>
! <title>Handling Calls Between Internal Users</title>
<para>
[Explain that we're going to add a second context,
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>
<programlisting>
[incoming]
! exten => s,1,Answer()<lineannotation> ; Answer the line</lineannotation>
! exten => s,2,Playback(welcome)<lineannotation> ; Play back the 'welcome' sound file</lineannotation>
! exten => s,3,Background(menu)<lineannotation> ; Play 'menu' file and accept input from caller</lineannotation>
! exten => 1,1,Dial(Zap/2)<lineannotation> ; Dial channels Zap/2 if the user dials 1</lineannotation>
! exten => 2,1,Dial(Zap/3)<lineannotation> ; Dial channels Zap/3 if the user dials 2</lineannotation>
[internal]
! exten => 1001,1,Dial(Zap/2)<lineannotation> ; Dialing extension 1001 calls channel Zap/2</lineannotation>
! exten => 1002,1,Dial(Zap/3)<lineannotation> ; Dialing extension 1002 calls channel Zap/3</lineannotation>
</programlisting>
</informalexample>
--- 1068,1116 ----
they will be redirected to either channel Zap/2 or Zap/3 respectfully.
</para>
</sect2>
+ -->
<sect2>
! <title>Handling Calls Between Internal Users</title>
! <!--
<para>
[Explain that we're going to add a second context,
and use it for calling between internal extensions.]
</para>
! -->
<para>
! In our examples thus far we have limited ourselves to a single context.
It is probably fair to assume that most installations will have more than
! one context. One great use of contexts is to give outside callers a different
! experience than people calling from inside extensions. Besides providing a
! different user experience, contexts are also used a a mechanism to seperate
! privileges for different classes of callers, where the privilege might be
! making long-distance calls, or calling certain extensions.
!
! In our next example, we'll create a simple dialplan with two internal
! phone extensions, and set up the ability for these two extension to call each
! other. To accomplish this, let's create a new context called [internal].
</para>
!
! <note>
! <para>
! As in previous examples, we're assuming that the Zaptel channels have already been
! configured. We're also assuming that any calls originated by these channels begin
! in the [internal] context.
! </para>
! </note>
!
<informalexample>
<programlisting>
[incoming]
! exten => s,1,Answer()
! exten => s,2,Playback(welcome)
! exten => s,3,Background(menu)
! exten => 1,1,Dial(Zap/1)
! exten => 2,1,Dial(Zap/2)
[internal]
! exten => 1001,1,Dial(Zap/1)
! exten => 1002,1,Dial(Zap/2)
</programlisting>
</informalexample>
***************
*** 1095,1102 ****
<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>
--- 1118,1125 ----
<para>
The above example shows that incoming calls to the [incoming] context can dial
! channel Zap/2 by selecting the option <keycap>1</keycap> from our menu. However i
! we would like to standardize the internal extensions with 4 digit numbers. As we
! have it set up, the caller on channel Zap/1 can call channel Zap/2 by dialing 1002,
! and Zap/2 can call Zap/1 by dialing extension 1001.
</para>
</sect2>
***************
*** 1106,1127 ****
<title>Variables</title>
<para>
! Variables can be used for many things. They can be used to help reduce typing,
! or they can be used to limit looping in an error condition too long. When
! using the value of a variable, you denote it with a dollar sign and the
! variable name surrounded by curly braces.
</para>
<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>
<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>
--- 1129,1155 ----
<title>Variables</title>
<para>
! Variables are very useful tools in a dialplan. They can be used to help reduce typing,
! add clarity, or add additional logic to a dialplan. Think of variables as a container.
! When we make reference to a variable, what we really want is the value that the
! variable contains. For example, the variable ${JOHN} might be
! assigned the name of the channel assigned to someone named John. In our dialplan, we could
! refer to the channel as ${JOHN}, and Asterisk will automatically
! replace it with whatever value has been assigned to the variable. References to
! variables are denoted by a dollar sign, an opening curly brace, the name of the
! variable, and a closing curly brace.
</para>
<para>
There are two types of variables, namely global variables and call variables.
! As their names imply, global variables apply to all extensions in all contexts,
! while call variables only apply to the current call in progress.
</para>
<note>
<para>
! The terms arguments and variables are often used interchangably 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 containers which are assigned a particular value. They
can either be used by the user or, much more frequently, by Asterisk itself.
</para>
***************
*** 1131,1139 ****
<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, 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>
</sect2>
--- 1159,1166 ----
<title>Global Variables</title>
<para>
! Global variables are denoted using the form VARIABLE_NAME=value, and should
! be placed in the [globals] context. Global variables are useful as they
! allow us to use them within our dialplan to make it more readable. They
! can also greatly simplify the task of updating a dialplan.
</para>
</sect2>
***************
*** 1141,1144 ****
--- 1168,1179 ----
<sect2>
<title>Call Variables</title>
+ <!--
+ <para>
+ [My goodness! Let's not scare off the poor saps! There's no reason to go into
+ "simple" expressions before we've even used explained why call variables are
+ different than global variables. Let's put this section on variable expressions
+ in another chapter and/or volume!]
+ </para>
+
<para>
It is also possible to do simple expressions. These expressions are evaluated
***************
*** 1156,1165 ****
source code.
</para>
</sect2>
-
<sect2>
<title>Adding Variables</title>
<para>
! [Take our Widgets Inc. example and add variables for
${RECEPTIONIST}, etc.]
</para>
--- 1191,1204 ----
source code.
</para>
+ -->
+ <para>
+ [Explain in one paragraph how call variables are different than global variables,
+ and why they're useful.]
+ </para>
</sect2>
<sect2>
<title>Adding Variables</title>
<para>
! [Take the Widgets Inc. example (which we don't have anymore) and add variables for
${RECEPTIONIST}, etc.]
</para>
***************
*** 1193,1196 ****
--- 1232,1238 ----
</sect1>
+ <!-- Macros probably don't deserve mention in Volume One. They'd make a good part of
+ Volume Two. -->
+ <!--
<sect1>
<title>Macros</title>
***************
*** 1337,1341 ****
</sect2>
</sect1>
!
<sect1>
<title>Call Flow</title>
--- 1379,1383 ----
</sect2>
</sect1>
! -->
<sect1>
<title>Call Flow</title>
***************
*** 1505,1512 ****
</sect2>
- <sect2>
- <title>Using Goto and GotoIf</title>
- <para/>
- </sect2>
</sect1>
</chapter>
--- 1547,1550 ----