Asterisk comes with a sample AGI script called agi-test.agi. Let's step through the file while we cover the core concepts of AGI programming. While this particular script is written in Perl, please remember that your own AGI programs may be written in almost any programming language. Just to prove it, we're going to cover AGI programming in a couple of other languages later in the chapter.

Let's get started! We'll look at each section of the code in turn, and describe what it does.

    #!/usr/bin/perl

This line tells the system that this particular script is written in Perl, so it should use the Perl interpreter to execute the script. If you've done much Linux or Unix scripting, this line should be familiar to you. This line assumes, of course, that your Perl binary is located in the /usr/bin/ directory. Change this to match the location of your Perl interpreter.

    use strict;

use strict tells Perl to act, well, strict about possible programming errors, such as undeclared variables. While not absolutely necessary, enabling this will help you avoid common programming pitfalls.

    $|=1;

This line tells Perl not to buffer its output—in other words, that it should write any data immediately, instead of waiting for a block of data before outputting it. You'll see this as a recurrent theme throughout the chapter.

    # Set up some variables
    my %AGI; my $tests = 0; my $fail = 0; my $pass = 0;

Here, we set up four variables. The first is a hash called AGI, which is used to store the variables that Asterisk passes to our script at the beginning of the AGI session. The next three are scalar values, used to count the total number of tests, the number of failed tests, and the number of passed tests, respectively.

    while(<STDIN>) {
            chomp;
            last unless length($_);
            if (/^agi_(\w+)\:\s+(.*)$/) {
                    $AGI{$1} = $2;
            }
    }

As we explained earlier, Asterisk sends a group of variables to the AGI program at startup. This loop simply takes all of these variables and stores them in the hash named AGI. They can be used later in the program or simply ignored, but they should always be read from STDIN before continuing on with the logic of the program.

    print STDERR "AGI Environment Dump:\n";
    foreach my $i (sort keys %AGI) {
            print STDERR " -- $i = $AGI{$i}\n";
    }

This loop simply writes each of the values that we stored in the AGI hash to STDERR. This is useful for debugging the AGI script, as STDERR is printed to the Asterisk console.^[127]

    sub checkresult {
            my ($res) = @_;
            my $retval;
            $tests++;
            chomp $res;
            if ($res =~ /^200/) {
                    $res =~ /result=(-?\d+)/;
                    if (!length($1)) {
                            print STDERR "FAIL ($res)\n";
                            $fail++;
                    } else {
                            print STDERR "PASS ($1)\n";
                            $pass++;
                    }
            } else {
                    print STDERR "FAIL (unexpected result '$res')\n";
                    $fail++;
            }

This subroutine reads in the result of an AGI command from Asterisk and decodes the result to determine whether the command passes or fails.

Now that the preliminaries are out of the way, we can get to the core logic of the AGI script.

    print STDERR "1.  Testing 'sendfile'...";
    print "STREAM FILE beep \"\"\n";
    my $result = <STDIN>;
    &checkresult($result);

This first test shows how to use the STREAM FILE command. The STREAM FILE command tells Asterisk to play a sound file to the caller, just as the Background() application does. In this case, we're telling Asterisk to play a file called beep.gsm.^[128]

You will notice that the second argument is passed by putting in a set of double quotes, escaped by backslashes. Without the double quotes to indicate the second argument, this command does not work correctly.

After sending the STREAM FILE command, this test reads the result from STDIN and calls the checkresult subroutine to determine if Asterisk was able to play the file. The STREAM FILE command takes three arguments, two of which are required:

In short, this test told Asterisk to play back the file named beep.gsm, and then checked the result to make sure the command was successfully executed by Asterisk.

    print STDERR "2.  Testing 'sendtext'...";
    print "SEND TEXT \"hello world\"\n";
    my $result = <STDIN>;
    &checkresult($result);

This test shows us how to call the SEND TEXT command, which is similar to the SendText() application. This command will send the specified text to the caller, if the caller's channel type supports the sending of text.

The SEND TEXT command takes one argument: the text to send to the channel. If the text contains spaces (as in the example above), the argument should be encapsulated with quotes, so that Asterisk will know that the entire text string is a single argument to the command. Again, notice that the quotation marks are escaped, as they must be sent to Asterisk, not used to terminate the string in Perl.

    print STDERR "3.  Testing 'sendimage'...";
    print "SEND IMAGE asterisk-image\n";
    my $result = <STDIN>;
    &checkresult($result);

This test calls the SEND IMAGE command, which is similar to the SendImage() application. Its single argument is the name of an image file to send to the caller. As with the SEND TEXT command, this command works only if the calling channel supports the reception of images.

    print STDERR "4.  Testing 'saynumber'...";
    print "SAY NUMBER 192837465 \"\"\n";
    my $result = <STDIN>;
    &checkresult($result);

This test sends Asterisk the SAY NUMBER command. This command behaves identically to the SayNumber() dialplan application. It takes two arguments:

Again, since we're not passing in any digits as the second argument, we need to pass in an empty set of quotes.

    print STDERR "5.  Testing 'waitdtmf'...";
    print "WAIT FOR DIGIT 1000\n";
    my $result = <STDIN>;
    &checkresult($result);

This test shows the WAIT FOR DIGIT command. This command waits the specified number of milliseconds for the caller to enter a DTMF digit. If you want the command to wait indefinitely for a digit, use -1 as the timeout. This application returns the decimal ASCII value of the digit that was pressed.

    print STDERR "6.  Testing 'record'...";
    print "RECORD FILE testagi gsm 1234 3000\n";
    my $result = <STDIN>;
    &checkresult($result);

This section of code shows us the RECORD FILE command. This command is used to record the call audio, similar to the Record() dialplan application. RECORD FILE takes seven arguments, the last three of which are optional:

In this particular case, we're recording a file called testagi (in the GSM format), with any of the DTMF digits 1 through 4 terminating the recording, and a maximum recording time of 3,000 milliseconds.

    print STDERR "6a.  Testing 'record' playback...";
    print "STREAM FILE testagi \"\"\n";
    my $result = <STDIN>;
    &checkresult($result);

The second part of this test plays back the audio that was recorded earlier, using the STREAM FILE command. We've already covered STREAM FILE, so this section of code needs no further explanation.

    print STDERR "================== Complete ======================\n";
    print STDERR "$tests tests completed, $pass passed, $fail failed\n";
    print STDERR "==================================================\n";

At the end of the AGI script, a summary of the tests is printed to STDERR, which should end up on the Asterisk console.

In summary, you should remember the following when writing AGI programs in Perl: