[Asterisk-doc] New Docs Redux

Nicholas Bachmann asterisk-doc@lists.digium.com
Sat, 21 Feb 2004 00:52:37 -0500


This is a multi-part message in MIME format.
--------------040402080503010208030709
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Whoops... never mind that last attachment... it doesn't compile.  Here's 
a non-broken version.

Sorry folks!

--------------040402080503010208030709
Content-Type: text/plain;
 name="diff.new"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="diff.new"

Index: advanced-config.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/advanced-config.xml,v
retrieving revision 1.1
diff -r1.1 advanced-config.xml
642a643,754
> 	<sect1>
> 		<title>Auto-Dialout (Call Files)</title>
> 		<!-- Perhaps we should put this in the AGI chapter and rename the whole thing "Asterisk Scripting"? -->
> 		<para>
> 		Auto-Dialout is a feature that allows users to initiate calls through
> 		Asterisk.  By placing files in 
> 		<filename class='directory'>/var/spool/asterisk/outgoing/</filename>, 
> 		Asterisk can automatically initiate calls. Reported practical uses for 
> 		call files include automated surveys and automated voicemail callbacks.
> 		</para>
> 		<para>
> 		In general terms, call files specify an channel to call and an 
> 		extension or application to connect with the called channel. All call 
> 		files must have both to be valid.  Call files also may specify call
> 		options such as Caller*ID or set local <!--right word?--> variables. 
> 		Statements are made in format <function>directive: arguments</function>
> 		Here is a summary of available call file directives:
> 		<table frame='all'>
> 	                <title>Call File Directives</title>
>                         <tgroup cols='2' align='left' colsep='1' rowsep='1'>
>                         <thead>
>                                 <row>
>                                           <entry>Name</entry>
>                                           <entry>Explanation/Notes</entry>
>                                 </row>
>                         </thead>
>                         <tbody>
> 				<row>
> 					<entry>Channel: &lt;channel&gt;</entry>
> 					<entry>Outbound channel</entry>
> 				</row>
> 				<row>
> 					<entry>Callerid: &lt;id&gt;</entry>
> 					<entry>Caller*ID for outbound channel</entry>
> 				</row>
> 				<row>
> 					 <entry>Application: &lt;application&gt;</entry>
> 					 <entry>Application to bridge outbound channel with. Arguments are passed with a Data directive. See note about CDR below.</entry>
> 				</row>
>                                 <row>
>                                          <entry>Data: &lt;data&gt;</entry>
> 					 <entry>The data to be passed to an application</entry>
>                                 </row>
>                                 <row>
>                                          <entry>MaxRetries: &lt;integer&gt;</entry>
> 					 <entry>Number of times to retry outbound channel if it is busy or otherwise unavailable</entry>
>                                 </row>
>                                 <row>
>                                          <entry>Context: &lt;context&gt;</entry>
> 					 <entry>Context for an extension to bridge the outbound call to</entry>
>                                 </row>
>                                 <row>
>                                          <entry>Extension: &lt;extension&gt;</entry>
> 					 <entry>Extension in [&lt;context&gt;] to bridge to</entry>
>                                 </row>
>                                 <row>
>                                          <entry>Priority: &lt;integer&gt;</entry>
>                                          <entry>The priority in &lt;extension&gt;@[&lt;context&gt;] to connect to.</entry>
>                                 </row>
> 				<row>
>                                          <entry>RetryTime: &lt;seconds&gt;</entry>
>                                          <entry>Time between retries</entry>
>                                 </row>
>                                 <row>
>                                          <entry>WaitTime: &lt;seconds&gt;</entry>
>                                          <entry>How long to wait for an answer</entry>
>                                 </row>
> 
> 				<row>
>                                          <entry>Context: &lt;context&gt;</entry>
>                                          <entry>Context for an extension to bridge the outbound call to</entry>
>                                 </row>
> 				<row>
>                                          <entry>SetVar: &lt;name=value&gt;</entry>
>                                          <entry>Set a variable for the connecting dialplan or application logic to use</entry>
>                                 </row>
> 			</tbody>
> 			</tgroup>
> 		</table>	
> 		Here is an example call file:
> 		<programlisting>
> 		Channel: Zap/1g/12125558910
> 		MaxRetries: 3
> 		RetryTime: 40
> 		WaitTime: 25
> 		Context: surveys
> 		Extension: 212 
> 		Priority: 1
> 		</programlisting>	
> 		</para>
> 		<sect2>
> 			<title>Call File Caveats</title>
> 			<para>There a few things to watch out for:</para>
> 			<sect3>
> 				<title>No CDR Data From Applications</title>
> 				<para>
> 				If your call file directly connects to an application, and
> 				not an extension, no CDR data will be collected for that 
> 				call.  To circumvent this, just connect the call to an
> 				extension that starts the application.
> 				</para>
> 			</sect3>
>                         <sect3>
>                                 <title>Asterisk is Quick</title>
>                                 <para>
> 				When generating call files, create them in a staging directory and copy them into <filename class='directory'>/var/spool/asterisk/outgoing/</filename> when you are finished. 
> 				Otherwise, Asterisk may grab a half-way completed call file.
> 	                        </para>
>                         </sect3>
> 
> 		</sect2>
> 	</sect1>	
Index: agi.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/agi.xml,v
retrieving revision 1.1
diff -r1.1 agi.xml
17c17,19
< 		STDIN, and your script passes information back via STDOUT.
---
> 		STDIN, and your script passes information back via STDOUT. 
> 		Arguments passed to the <function>agi()</function>  application within 
> 		Asterisk appear like command line arguments to the script.
19c21
< 		language.
---
> 		language, just like CGI scripts.
26,27c28,129
< 		<title>AGI examples in various languages</title>
< 		<para/>
---
> 		<title>AGI Basics</title>
> 		<para>
> 		Communication between the AGI script and Asterisk is accomplished
> 		through the standard input, output, and error file descriptors of the AGI
> 		script. At initialization, Asterisk sends several important pieces of 
> 		initialization information to the AGI script.  This data needs to be read
> 		before any commands are passed to Asterisk; otherwise, it will not be
> 		available.
> 		</para>
> 		<table frame='all'>
> 			<title>Initialization Data</title>
> 			<tgroup cols='3' align='left' colsep='1' rowsep='1'>
> 			<thead>
> 				<row>
> 					  <entry>Name</entry>
> 					  <entry>Sample Value</entry>
> 					  <entry>Explanation/Notes</entry>
> 				</row>
> 			</thead>
> 			<tbody>
> 				<row>
> 					<entry>agi_accountcode</entry>
> 					<entry>123</entry>
> 					<entry>Set by SetAccount in the dialplan</entry>
> 				</row>
> 				<row>
> 					<entry>agi_callerid</entry>
> 					<entry>2128675309</entry>
> 					<entry>Remember, this may not always be a number</entry>
> 				</row>
> 				<row>
> 					<entry>agi_channel</entry>
> 					<entry>SIP/1001-6476</entry>
> 				</row>
> 				<row>
> 					<entry>agi_context</entry>
> 					<entry>default</entry>
> 				</row>
> 				<row>
> 					<entry>agi_dnid</entry>
> 					<entry>2890</entry>
> 					<entry>Dialed Number Identifier. More likely will show up as "unknown"</entry>
> 				</row>
> 				<row>
> 					<entry>agi_enhanced</entry>
> 					<entry>0.0</entry>
> 					<entry>Value is 1.0 if started as an EAGI script</entry>
> 				</row>
> 				<row>
> 					<entry>agi_extension</entry>
> 					<entry>100</entry>
> 				</row>
> 				<row>
> 					<entry>agi_language</entry>
> 					<entry>en</entry>
> 				</row>
> 				<row>
> 					<entry>agi_priority</entry>
> 					<entry>1</entry>
> 				</row>
> 				<row>
> 					<entry>agi_rdnis</entry>
> 					<entry>2494</entry>
> 					<entry>The current referring DNIS number from the Zaptel ISDN subsystem.</entry>
> 				</row>
> 				<row>
> 					<entry>agi_request</entry>
> 					<entry>myagi.agi</entry>
> 					<entry>???</entry>
> 				</row>
> 				<row>
> 					<entry>agi_type</entry>
> 					<entry>SIP</entry>
> 					<entry>Could also be ZAP, H323, etc. </entry>
> 				</row>
> 				<row>
> 					<entry>agi_uniqueid</entry>
> 					<entry>1077328545.0</entry>
> 					<entry>Note that uniqueids are based on Unix time.</entry>
> 				</row>
> 			</tbody>
> 			</tgroup>
> 		</table>
> 
> 		<para>
> 		Commands are passed to Asterisk in the format <command>
> 		[command] &lt;arg1&gt; &lt;arg2&gt; ... &lt;argn&gt;</command>.
> 		A list of available commands may be fetched with the Asterisk Console
> 		command <command>show agi</command>.
> 		</para>
> 		<para>
> 		The standard error channel can be used to send messages to the Asterisk
> 		console. The test AGI scripts included with Asterisk contain an example
> 		of this behavior.
> 		</para>
> 	</sect1>
> 	<sect1>
> 		<title>Language-specific AGI notes and examples</title>
> 		<para>
> 			Specific examples for languages can be found at 
> 			<ulink url="http://home.cogeco.ca/~camstuff/agi.html" type="url">http://home.cogeco.ca/~camstuff/agi.html</ulink>.
> 		</para>
34c136,188
< 			<para/>
---
> 			<para>
> 			Perl's propensity for data manipulation and quick scripting make 
> 			it a very popular <!-- The most?-->choice for AGI scripting.
> 			To make Perl AGI programming even easier, James Golovich created
> 			Asterisk::AGI, a module designed for simplifying AGI interaction.
> 			Asterisk::AGI is available from the author's web page at 
> 			<ulink url="http://asterisk.gnuinter.net/"type="http"></ulink>.
> 			</para>
> 			<para>
> 			Without using Asterisk::AGI, this is what a simple AGI script 
> 			to tell a user their phone number would look like.
> 			<programlisting>
> 			#!/usr/bin/perl -w
> 			
> 			use strict;
> 
> 			$|=1;
> 			
> 			#Get the initial data
> 			my %input;
> 			while(&lt;STDIN&gt;) {  
> 			        chomp;
> 			        last unless length($_);
> 			        if (/^agi_(\w+)\:\s+(.*)$/) {
> 		                	$input{$1} = $2;
> 		        	}
> 			}
> 
> 			print "stream file the-number-is";
> 			print "say digits $input{callerid}";
> 			print "exec WaitMusicOnHold 2";
> 			print "hangup";
> 			</programlisting>
> 			Note the <varname>$|</varname> set to force a buffer flush after
> 			each print.
> 			</para>
> 			<para>
> 			Using Asterisk::AGI, we can simplify the previous script a bit:
> 			<programlisting>
> 			#!/usr/bin/perl -w
> 
> 			use strict;
> 			use Asterisk::AGI;
> 			
> 			$AGI = new Asterisk::AGI;
> 			my %input = $AGI->ReadParse();  #Read in the initial data
> 			
> 			$AGI->stream_file('the-number-is');
> 			$AGI->say_digits($input{callerid});
> 			$AGI->exec('WaitMusicOnHold','2');
> 			$AGI->hangup();
> 			</programlisting>
> 			</para>
43a198,201
> 	</sect1>
> 	<sect1>
> 		<title>EAGI</title>
> 		<para/>

--------------040402080503010208030709--