9.1. Fundamentals of AGI
Communication
Instead of releasing an API for programming, AGI
scripts communicate with Asterisk over communications channels
(file pointers , in programming
parlance) known as STDIN, STDOUT, and
STDERR. Most computer programmers will recognize these
channels, but just in case you're not familiar with them we'll
cover them here.
9.1.1. What Are STDIN, STDOUT, and
STDERR?
STDIN ,
STDOUT , and
STDERR are channels by which
programs in Unix-like environments receive information from and
send information to external programs. STDIN, or "standard
input," is the information that is sent to the program, either from
the keyboard or from another program. In our case, information
coming from Asterisk itself comes in on the program's
STDIN file handle. STDOUT, or "standard output,"
is the file handle that the AGI script uses to pass information
back to Asterisk. Finally, the AGI script can use the
STDERR ("standard error") file handle to write error
messages to the Asterisk console.
Let's sum up these three communications
concepts:
-
An AGI script reads from STDIN to get
information from Asterisk.
-
An AGI script writes data to STDOUT to
send information to Asterisk.
-
An AGI script may write data to STDERR
to send debug information to the Asterisk console.
|
At this time, writing to STDERR from
within your AGI script writes the information only to the
first Asterisk consolethat is, the
first Asterisk console started with the -c or -r
parameters.
This is rather unfortunate, and will hopefully
be remedied soon by the Asterisk developers.
If you're using the safe_asterisk program to start Asterisk (which
you probably are), it starts a remote console on TTY9 . (Try pressing
Ctrl-Alt-F9, and see if you get an Asterisk command-line
interface.) This means that all the AGI debug information will
print on only that remote console. You may want to disable this
console in safe_asterisk to allow
you to see the debug information in another console. (You may also
want to disable that console for security reasons, as you might not
want just anyone to be able to walk up to your Asterisk server and
have access to a console without any kind of authentication.)
|
|
9.1.2. The Standard Pattern of AGI
Communication
The communication between Asterisk and an AGI
script follows a predefined pattern. Let's enumerate the steps, and
then we'll walk through one of the sample AGI scripts that come
with Asterisk.
When an AGI script starts, Asterisk sends a list
of variables and their values to the AGI script. The variables
might look something like this:
agi_request: test.py
agi_channel: Zap/1-1
agi_language: en
agi_callerid:
agi_context: default
agi_extension: 123
agi_priority: 2
After sending these variables, Asterisk sends a
blank line. This is the signal that Asterisk is done sending the
variables and it is time for the AGI
script to control the dialplan.
At this point, the AGI script sends commands to
Asterisk by writing to STDOUT. After the script sends each
command, Asterisk sends a response that the AGI script should read.
This action (sending commands to Asterisk and reading the
responses) can continue for the duration of the AGI script.
You may be asking yourself what commands you can
use from within your AGI script. Good questionwe'll cover the basic
commands shortly.
9.1.3. Calling an AGI Script from the
Dialplan
In order to work properly, your AGI script must
be executable. To use an AGI script inside your dialplan, simply
call the AGI( ) application, with the name of the AGI
script as the argument, like this:
exten => 123,1,Answer( )
exten => 123,2,AGI(agi-test.agi)
AGI scripts often reside in the AGI directory
(usually located in /var/lib/asterisk/agi-bin), but you can
specify the complete path to the AGI script.
In addition to the AGI( ) application,
there are several other AGI applications suited to different
circumstances. While they won't be covered in this chapter, they
should be quite simple to figure out once you understand the basics
of AGI scripting.
The EAGI( ) (enhanced AGI) application
acts just like AGI( ), but allows your AGI script to read
the inbound audio stream on file descriptor number three.
The DeadAGI( ) application is also just
like AGI( ), but it works correctly on a channel that is
dead (i.e., a channel that has been hung up). As this implies, the
regular AGI( ) application doesn't work on dead
channels.
The FastAGI( ) application allows the
AGI script to be called across the network, so that multiple
Asterisk servers can call AGI scripts from a central location.
|
In this chapter, we'll first cover the sample
agi-test.agi script that comes
with Asterisk (which was written in Perl), then write a weather
report AGI program in PHP, and then finish up by writing an AGI
program in Python to play a math game.
|