Instead of releasing an API for programming, AGI scripts communicate
with Asterisk over communications channels (file handles, 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.
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
console—that is, the first Asterisk console started with the -c 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 of 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.)
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. These actions (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 question—we’ll cover the basic commands shortly.[119]
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 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 finish up by writing an AGI program in Python to play a math game.
[119] To get a list of available AGI commands, type
show agi