[Asterisk-doc] docs extensions.xml,1.20,1.21
blitzrage
asterisk-doc@lists.digium.com
Tue, 13 Jul 2004 21:07:32 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv12377/docs
Modified Files:
extensions.xml
Log Message:
blitzrage
- information about using Macro's and the new ${DIALSTATUS}
Index: extensions.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/extensions.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** extensions.xml 11 Jul 2004 03:02:10 -0000 1.20
--- extensions.xml 13 Jul 2004 21:07:25 -0000 1.21
***************
*** 666,670 ****
<sect2>
<title>What are Macros?</title>
! <para/>
</sect2>
--- 666,676 ----
<sect2>
<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
! macro and the actions you wish it to perform, you can call it at any time
! within your dialplan with a single line.
! </para>
</sect2>
***************
*** 672,679 ****
<title>Attributes of Macros</title>
<para>
! [Macros start with "macro-"]
! [Macros are expanded in place]
! [Macros use the "s" extension]
! [Variables are passed in as <replaceable>ARG1</replaceable>, <replaceable>ARG2</replaceable>, etc.]
</para>
</sect2>
--- 678,686 ----
<title>Attributes of Macros</title>
<para>
! Macros are identified in the dialplan by starting a context name
! 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>
</sect2>
***************
*** 681,685 ****
<sect2>
<title>Adding Macros to our Dial Plan</title>
! <para/>
</sect2>
</sect1>
--- 688,803 ----
<sect2>
<title>Adding Macros to our Dial Plan</title>
! <para>
! As an example lets show how you can use a macro to limit the number of lines
! which are required to setup a new extension.
! </para>
!
! <informalexample>
! <programlisting>
! [macro-stdexten]
! exten => s,1,Dial(${ARG1},20)
! exten => s,2,Voicemail(u${MACRO_EXTEN}
! exten => s,3,Hangup
! exten => s,102,Voicemail(b${MACRO_EXTEN})
! exten => s,103,Hangup
! </programlisting>
! </informalexample>
!
! <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>
!
! <informalexample>
! <programlisting>
! [default]
! exten => 1000,1,Macro(stdexten,SIP/1000)
! </programlisting>
! </informalexample>
!
! <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
! number calling the macro. In our example above this would be extension 1000
! as defined in the [default] context.
! </para>
!
! <para>
! Some other local variables you can use in macros include:
!
! <simplelist>
! <member>${MACRO_CONTEXT} - The context of the extension which calls the macro</member>
! <member>${MACRO_PRIORITY} - The priority which the macro was called from</member>
! <member>${MACRO_OFFSET} - When complete, return to priority n + ${MACRO_OFFSET}</member>
! </simplelist>
! </para>
! </sect2>
!
! <sect2>
! <title>Jumping Between Priorities Based on Call Status</title>
! <para>
! Asterisk is able to jump to different priorities based on the status returned
! from Dial(). Using the ${DIALSTATUS} local variable we can perform different
! actions based on the returned status message. Valid status messages include
! NOANSWER, BUSY, CHANISUNAVAIL, CONGESTION and ANSWER. We can modify our
! stdexten macro above to demonstrate how this works.
! </para>
!
! <informalexample>
! <programlisting>
! [macro-stdexten]
! exten => s,1,Dial(${ARG1},20)
! exten => s,2,Goto(s-${DIALSTATUS},1)
! exten => s-NOANSWER,1,Voicemail(u${MACRO_EXTEN})
! exten => s-NOANSWER,2,Goto(default,s,1)
! exten => s-BUSY,1,Voicemail(b${MACRO_EXTEN})
! exten => s-BUSY,2,Goto(default,s,1)
! exten => s-.,1,Goto(s-NOANSWER,1)
! exten => a,1,VoicemailMain(${MACRO_EXTEN})
! </programlisting>
! </informalexample>
!
! <para>
! We can assume that we are going to call the macro using the same example as
! above (exten => 1000,1,Macro(stdexten,SIP/1000)). Our first line of this
! 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
! message. The second priority of the s-NOANSWER extension will execute a Goto()
! statement if the user presses "#" before Voicemail hangs up the line. Similarily
! the busy voicemail message will be played if a ${DIALSTATUS} of BUSY is returned.
! </para>
!
! <para>
! The second last line of our macro is a catch all statement. The period (.) after
! 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>
!
! <para>
! Our last line is another new extension type. The 'a' extension will execute if
! the user presses the asterisk (*) key while the unavailable or busy message is
! being played. When the asterisk key is pressed, it will execute the VoicemailMain()
! application and send it to the ${MACRO_EXTEN}. What this essentially does is
! send the user to their mailbox and prompts them for a password (if configured
! to require a password). This allows the user to check their voicemail without
! requiring them to login to a seperate extension.
! </para>
</sect2>
</sect1>