Джим Меггелен - Asterisk™: будущее телефонии Второе издание
Приложение DeadAGI() также очень похоже на AGI(), но выполняется корректно для «мертвого» канала (то есть канала, который был отключен). Отсюда следует, что обычное приложение AGI() не работает для отключенных каналов.
Приложение FastAGI() позволяет вызывать сценарий AGI по сети, таким образом, множество серверов Asterisk могут использовать сценарии AGI, хранящиеся централизованно.
Написание сценариев AGI на Perl
Asterisk поставляется с образцом сценария AGI под названием agi-test. agi. На примере этого файла рассмотрим основные концепции программирования AGI. Этот конкретный сценарий написан на Perl, но AGI- программы могут быть реализованы практически на любом языке программирования. Чтобы доказать это, в данной главе будут представлены AGI-программы на нескольких других языках программирования. Итак, приступим! Будем рассматривать каждый раздел кода по очереди и описывать, что он делает: #!/usr/bin/perl
Эта строка сообщает системе, что данный сценарий написан на Perl, таким образом, для его выполнения должен использоваться интерпретатор Perl. Опытным создателям сценариев для Linux или UNIX эта строка должна быть хорошо знакома. Конечно, здесь предполагается, что исполняемый файл Perl располагается в папке /usr/bin/. Если необходимо, измените строку соответственно местоположению своего интерпретатора Perl. use strict;
Строка use strict указывает Perl строго придерживаться правил программирования и не допускать возможных ошибок при написании программы, таких как, например, необъявленные переменные. Хотя она не является обязательной, но активация этой функциональности поможет избежать обычных ошибок при программировании. $|=1;
Данная строка указывает интерпретатору Perl не буферизировать вывод. Иначе говоря, любые данные должны записываться немедленно, а не накапливаться и выводиться блоками. К этому вопросу мы будем многократно возвращаться по ходу главы.
# Задаем некоторые переменные
my %AGI; my $tests = 0; my $fail = 0; my $pass = 0;
При написании сценариев AGI должен использоваться только небуферизированный вывод. В противном случае AGI может работать не так, как от него требуется. Например, Asterisk может ожидать вывода программы, тогда как программа полагает, что уже отправила вывод в Asterisk, и ожидает ответа.
Здесь задаются четыре переменные. Первая - это хеш AGI, который используется для хранения переменных, передаваемых Asterisk в наш сценарий в начале сеанса AGI. Следующие три - это скалярные значения, используемые для подсчета общего количества тестов, количества непройденных тестов и количества пройденных тестов соответственно:
while(<STDIN>) { chomp;
last unless length($_);
if (/~agi_(w+):s+(.*)$/) {
$AGI{$1} = $2;
}
i
Как говорилось ранее, Asterisk передает группу переменных в программу AGI при запуске. Этот цикл просто принимает все эти переменные и сохраняет их в хеше AGI. Позже они могут использоваться в программе или просто игнорироваться, но они обязательно должны быть прочитаны из STDIN, прежде чем будет продолжено выполнение логики программы.
print STDERR "AGI Environment Dump:n";
foreach my $i (sort keys %AGI) {
print STDERR " -- $i = $AGI{$i}n";
}
Данный цикл просто записывает каждое из значений, сохраненных в хеше AGI, в STDERR. Это полезно для отладки сценария AGI, поскольку STDERR выводится в консоли Asterisk[100].
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++;
}
Эта подпрограмма считывает результат выполнения команды AGI из Asterisk и декодирует его, чтобы выяснить, была ли команда выполнена успешно или дала сбой.
Теперь, когда подготовительные этапы пройдены, можно перейти к основной логике сценария AGI:
print STDERR "1. Testing 'sendfile'..."; print "STREAM FILE beep ""n"; my $result = <STDIN>; &checkresult($result);
Первый тест показывает, как использовать команду STREAM FILE. Команда STREAM FILE указывает Asterisk воспроизвести звуковой файл вызывающему абоненту, точно так же как это делает приложение Backg round(). В данном случае Asterisk должна воспроизвести файл beep.gsm[101]. Обратите внимание, второй аргумент заменяется парой двойных кавычек, экранированных обратным слэшем. Без обозначения второго аргумента двойными кавычками эта команда не будет работать правильно.
В команды AGI должны передаваться все необходимые аргументы. Если требуется пропустить необходимый аргумент, должны быть указаны пустые кавычки (правильно экранированные, соответственно синтаксису конкретного языка программирования), как показано выше. Если необходимое количество аргументов не будет передано, сценарий AGI не станет работать.
Также необходимо убедиться, что вы не забыли передать символы перевода строки (символы n в конце выражения print) в конце команды.
После передачи команды STREAM FILE этот тест читает результат из STDIN и вызывает подпрограмму checkresult, чтобы выяснить, смогла ли Asterisk воспроизвести файл. Команда STREAM FILE принимает три аргумента, два из которых являются обязательными:
• Имя звукового файла для воспроизведения.
• Коды, которые могут прерывать воспроизведение.
• Место начала воспроизведения звукового файла, заданное номером музыкального фрагмента (необязательный).
Одним словом, этот тест указал Asterisk воспроизвести файл beep.gsm и затем проверил результат, чтобы убедиться, что Asterisk успешно выполнила команду.
print STDERR "2. Testing 'sendtext'..."; print "SEND TEXT "hello world"n"; my $result = <STDIN>; &checkresult($result);
Этот тест демонстрирует, как вызывать команду SEND TEXT, которая является аналогом приложения SendText(). Эта команда будет посылать заданный текст вызывающему абоненту, если используемый им тип канала поддерживает передачу текста.
Команда SEND TEXT принимает один аргумент: текст, который должен быть отправлен в канал. Если текст содержит пробелы (как в предыдущем фрагменте кода), аргумент должен быть заключен в кавычки, чтобы Asterisk понимала, что вся строка является одним аргументом команды. Опять же, обратите внимание, что кавычки экранированы, поскольку они должны быть переданы в Asterisk, а не использоваться для ограничения строки в Perl.
print STDERR "3. Testing 'sendimage'..."; print "SEND IMAGE asterisk-imagen"; my $result = <STDIN>; &checkresult($result);
Этот тест вызывает команду SEND IMAGE, которая является аналогом приложения SendImage(). Ее единственный аргумент - имя файла изображения, который будет отправляться вызывающему абоненту. Как и команда SEND TEXT, данная команда работает, только если вызывающий канал поддерживает прием изображений. print STDERR "4. Testing 'saynumber'..."; print "SAY NUMBER 192837465 ""n"; my $result = <STDIN>; &checkresult($result);
Этот тест посылает Asterisk команду SAY NUMBER. Она ведет себя аналогично приложению диалплана SayNumber() и принимает два аргумента:
• Число, которое должно быть воспроизведено.
• Коды, которые могут прервать выполнение команды.
Опять же, поскольку второй аргумент опущен, необходимо передать пустую пару кавычек.
print STDERR "5. Testing 'waitdtmf'..."; print "WAIT FOR DIGIT 1000n"; my $result = <STDIN>; &checkresult($result);
Этот тест демонстрирует применение команды WAIT FOR DIGIT. Эта команда обеспечивает ожидание ввода DTMF-кода вызывающим абонентом заданное количество миллисекунд. Если требуется реализовать бесконечное ожидание ввода цифры, в качестве времени ожидания задается -1. Это приложение возвращает десятичное значение ASCII нажатой цифры.
print STDERR "6. Testing 'record'..."; print "RECORD FILE testagi gsm 1234 3000n"; my $result = <STDIN>; &checkresult($result);
Этот фрагмент кода демонстрирует команду RECORD FILE. Она используется для записи разговора, аналогично приложению диалплана Record(). RECORD FILE принимает семь аргументов, из которых три последних являются необязательными:
• Имя записываемого файла.
• Формат, в котором выполняется запись.
• Коды, которые могут прервать запись.
• Время ожидания (максимальное время записи) в миллисекундах или -1, если время ожидания бесконечно.
• Число музыкальных фрагментов, которые необходимо пропустить перед началом записи (необязательный).
• Слово BEEP, если требуется, чтобы Asterisk подавала звуковой сигнал перед началом записи (необязательный).
• Количество секунд, которое должно пройти, прежде чем Asterisk решит, что пользователь закончил запись, и продолжит выполнение даже несмотря на то, что время ожидания еще не истекло и DTMF-коды не были введены (необязательный). Этот аргумент должен следовать за s=.
В данном конкретном случае записывается файл testagi (в формате GSM), любой DTMF-код от 1 до 4 может прервать запись и максимальное время записи - 3000 мс.
print STDERR "6a. Testing 'record' playback..."; print "STREAM FILE testagi ""n"; my $result = <STDIN>; &checkresult($result);
Вторая часть этого теста воспроизводит записанный ранее аудиофайл, используя команду STREAM FILE. Команда STREAM FILE уже рассматривалась, поэтому данный фрагмент кода не требует дополнительных пояснений.
print STDERR "================== Complete ======================n";
print STDERR "$tests tests completed, $pass passed, $fail failedn"; print STDERR "==================================================n";
В конце сценария AGI результаты тестирования записываются в STDERR, который должен быть выведен в консоли Asterisk.
