[Asterisk-doc] docs extensions.xml,1.23,1.24
websmith
asterisk-doc@lists.digium.com
Thu, 15 Jul 2004 04:21:52 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16567
Modified Files:
extensions.xml
Log Message:
More updates to chapter 4, mostly rewording the paragraphs leading up to the first example.
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -d -r1.23 -r1.24
*** extensions.xml 15 Jul 2004 01:28:49 -0000 1.23
--- extensions.xml 15 Jul 2004 04:21:46 -0000 1.24
***************
*** 118,128 ****
<sect2>
<title>Extensions</title>
- <!-- <para>
- [C'mon... we've got to change this. Odds are that the reader won't have any
- idea what a "subroutine" is, and I'd be willing to be they have no idea what
- "old BASIC programming" is like. Can't we explain this in plain english,
- and not programmer-speak?]
- </para>
- -->
<para>
Within each context, we will definie one or more extensions. Extensions
--- 118,121 ----
***************
*** 138,151 ****
</programlisting>
</informalexample>
! <!-- more extension syntax goes here -->
</para>
! <para>
! Applications allow us to perform various actions within our dial plan. These
! applications or "commands" can be passed information also referred to as
! "arguments". With this information the application is able to manipulate the
! call so that something happens. To see a listing of the possible
! applications that are built into Asterisk, see Appendix C.
!
<!-- The extension definitions are very much like subroutines in
programming. You will define them as the steps a call will take as
--- 131,152 ----
</programlisting>
</informalexample>
! This is followed by the number (or name) of the extension, a comma, the
! priority, another comma, and finally the application we'd like to call
! on the channel. We'll explain priorities and applications next, but first
! let's finish covering the syntax. The syntax looks like this:
! <informalexample>
! <programlisting>
! [<emphasis>context-name</emphasis>]
! exten=><emphasis>extension</emphasis>,<emphasis>priority</emphasis>,<emphasis>application</emphasis>
! </programlisting>
! </informalexample>
</para>
! <!--
! [C'mon... we've got to change this. Odds are that the reader won't have any
! idea what a "subroutine" is, and I'd be willing to be they have no idea what
! "old BASIC programming" is like. Can't we explain this in plain english,
! and not programmer-speak?]
! -->
<!-- The extension definitions are very much like subroutines in
programming. You will define them as the steps a call will take as
***************
*** 157,161 ****
the call to progress from one to the next. Here is an example of a
extension definition. -->
- </para>
</sect2>
--- 158,161 ----
***************
*** 171,183 ****
-->
<para>
! Priorities show which order functions are applied to a specified extension.
! Each priority calls one specific function per line. The priority numbers
! are the order in which the functions are applied. Typically these priority
numbers simply start at 1 and increment consecutively for each line in the
! context. However there are exceptions to this rule. For instance, if you
! use the Dial() function and the channel you are attempting to call is busy,
! then the next priority the context is going to attempt is the current
! priority number + 101. This allows you to perform a different set of
! functions when the line is busy, ie. go to voicemail.
</para>
</sect2>
--- 171,190 ----
-->
<para>
! Priorities are numbered steps in the execution of each extension.
! Each priority calls one specific application. Typically these priority
numbers simply start at 1 and increment consecutively for each line in the
! context. Priority numbers aren't <emphasis>always</emphasis> consecutive, but
! we'll worry about that later.
! </para>
! </sect2>
! <sect2>
! <title>Applications</title>
! <para>
! Applications perform certain actions on a voice channel, such as playing
! sounds, accepting touch-tone input, or hanging up the call. Options called
! arguments can be passed to applications to effect how they perform their
! actions. To see a listing of the possible applications that are
! built into Asterisk, see Appendix C. As we build our first dialplan
! below, you'll learn to use applications to your advantage.
</para>
</sect2>
***************
*** 187,195 ****
<title>A simple example</title>
<para>
! Let's create our first <filename>extensions.conf file</filename>. Because
! this is our first step, we'll start with a very simple example. We'll
! assume for this example that all Asterisk needs to do is to answer the phone,
! say "Goodbye", and then hangup. We'll use this simple example to point out
! the fundamentals of creating a dialplan.
</para>
--- 194,202 ----
<title>A simple example</title>
<para>
! Now we're ready to create our first <filename>extensions.conf</filename> file.
! Because this is our first step, we'll start with a very simple example. We'll
! assume for this example that all Asterisk needs to do is to answer the channel,
! play a sound file that says "Goodbye", and then hang up. We'll use this
! simple example to point out the fundamentals of creating a dialplan.
</para>
***************
*** 203,213 ****
-->
<para>
! The 's' extension is used when we do not have a specific extension we wish
! to call. This is used in a context which will be directed to when we answer
! a call. Incoming calls get directed to either a specified context or the
! default context. We use the 's' extension because there is no specific
! number we wish to use at this point. It can almost be thought about like
! an automatically executed extension. We use the 's' extension in contexts
! which get referenced in files like zapata.conf and sip.conf.
</para>
</sect2>
--- 210,218 ----
-->
<para>
! Before we get too far into our example, we need to cover a special extension
! called 's', which stands for "start". By default, calls will start in a
! context's 's' extension. (You can think of 's' as the extension that gets
! automatically executed.) In our example, we'll start by creating a dialplan
! with this 's' extension.
</para>
</sect2>
***************
*** 225,237 ****
-->
<para>
! The <function>Answer()</function> function is used to answer a channel
! which is ringing. This does the initial establishing of the call so that we
! can perform other functions. A few functions don't necessarily require that
! we <function>Answer()</function> the line first, such as <function>Playback()
! </function> and <function>Background()</function>, but it is a very good
! habit to properly <function>Answer()</function> the channel before doing
! anything else.
</para>
-
<!-- <para>
[A brief explanation of the Playback() function. Explain where it looks for
--- 230,241 ----
-->
<para>
! If we're going to answer the call, play a sound file, and then hang up,
! we'd better learn how to do just that. The <function>Answer()</function>
! application is used to answer a channel which is ringing. This does the
! initial setup for the call so that we can perform other functions. A few
! applications don't necessarily require that we <function>Answer()</function>
! the channel first, but it is a very good habit to properly
! <function>Answer()</function> the channel before doing anything else.
</para>
<!-- <para>
[A brief explanation of the Playback() function. Explain where it looks for
***************
*** 241,254 ****
-->
<para>
! The <function>Playback()</function> function is used for playing previously
! recorded files over a channel to the remote end. When using the
! <function>Playback()</function> function, input from the user while the file
! is being played is simply ignored. If you need to accept input during
! playback, use the <function>Background()</function> function. Asterisk
! comes with many professionally recorded sound files which can be 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>.
</para>
--- 245,260 ----
-->
<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 toaccept input during playback,
! use the <function>Background()</function> function. Asterisk
! comes with many professionally recorded sound files which are often
! 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
! default sounds directory.
</para>
***************
*** 276,286 ****
-->
<para>
! The following example is not meant to be a complete working, usable example.
! There are other configuration files in the <filename class='directory'>
! /etc/asterisk </filename> directory which need to be configured to correctly
! send the incoming call into the context. We are using this example to explain
! how things work in <filename>extensions.conf</filename>.
</para>
!
<informalexample>
<programlisting>
--- 282,303 ----
-->
<para>
! 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>
! <para>
! The following examples are not meant to be completely working and usable.
! We are simply using these examples to explain how dialplans work.
! For these examples to work, you should have already configured some Zap
! channels (using a Devkit from Digium, for example), and configured
! those channels so that incoming calls go to the [incoming] context.
! </para>
! </note>
!
! <para>
! After showing our first example, we'll explain each step.
<informalexample>
<programlisting>
***************
*** 291,294 ****
--- 308,312 ----
</programlisting>
</informalexample>
+ </para>
<!-- <para>
***************
*** 300,323 ****
-->
<para>
! When a call is sent into this context, it is going to execute the very first line
! of the context. The first thing we notice is that all three lines start with
! exten->. This means that we are referencing an extension of some sort.
! Extensions can include specific numbers such as a persons extension number.
! There are also several 'letter' extensions which have specific functions.
! This allows us to make the call do different things based on what circumstance
! we have. For now lets stick to the 's' extension in our example. As we learned
! earlier, the 's' extension is going to answer the line for us without having to
! specify any specific number; we just want to answer the phone. After our
! 's' extension we have the priority number. We have three lines in this context,
! hence we have the numbers 1, 2 and 3. As we moved to the next section of our
! first line we have the application we wish to use. This will perform some
! sort of action on the call, such as answering the line.
</para>
<para>
! Back to looking at what each line does. Our first line is going to perform the
! <function>Answer()</function> function. Asterisk will then take control of the
! line. After this happens, Asterisk will perform the next priority. On our second
! line we have the <function>Playback()</function> function. This will play a
sound file as specified by the filename. In our example we will play the file
<filename>vm-goodbye</filename>. The user will hear Allison saying "goodbye".
--- 318,336 ----
-->
<para>
! When a call is sent into this [incoming] context, it will first go to
! 's' extension. As we learned earlier, calls usually begin start in the
! 's' extension. We have three priorities in this context, numbered
! 1, 2 and 3. Each priority calls a particular application.
</para>
<para>
! Now let's look at what each priority does. Our first priority
! calls the <function>Answer()</function> application. Asterisk then
! takes control of the line and sets up the call. After answering the
! line, Asterisk goes on to the next priority. In our second
! priority, we call the <function>Playback()</function> application.
!
! <!-- continue editing from here -->
! This will play a
sound file as specified by the filename. In our example we will play the file
<filename>vm-goodbye</filename>. The user will hear Allison saying "goodbye".