Asterisk

Asterisk Gateway Interface

AGI
La AGI (o Asterisk Gateway Interface) provee una interfaz estndar para que programas externos puedan controlar el plan de marcacin. Generalmente, los scripts AGI se utilizan para realizar lgica avanzada, comunicarse con base de datos relacionales, etc. Los lenguajes ms comunes de programacin de scripts AGI son: PHP, Python y Perl, aunque se puede utilizar cualquier otro lenguaje.
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo 2

AGI
El intercambio de informacin del script con Asterisk se realiza va los canales de comunicacin: STDIN, STDOUT y STDERR.
Lee desde STDIN para obtener informacin. Escribe en STDOUT para enviar informacin. Escribe en STDERR para enviar informacin de debugging.

El script AGI enva comandos a Asterisk escribiendo en el STDOUT. Seguidamente Asterisk enva una respuesta por cada uno de ellos que es leda por el script. Julin Dunayevich, Lzaro Baca,
Andrs Brassara, Santiago Alberch, Antonio Lobo 3

AGI
La respuesta del servidor Asterisk ante un pedido es de la sig forma:
<code> result=<result> [data]

donde
code es un cdigo de respuesta similar a HTTP (200 en caso de xito, 5XX en caso de error). result es el resultado del comando (los valores ms convencionales son -1 para errores, 0 si fue exitosa la ejecucin) data es un conjunto de datos adicionales que pueden ser enviados por comando especficos (por ej, timeout para un comando temporizado)
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo 4

AGI
Cuando Asterisk comienza la llamada al script, enva un conjunto de variables relacionadas con el canal en el STDIN. Por ejemplo:
agi_request: nombre del script agi_channel: nombre del canal agi_language: lenguaje del canal (en, es) agi_type: tipo de canal (sip, iax, etc.) etc.
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

AGI
Algunos ejemplos de comandos son:
ANSWER: atiende. HANGUP: cuelga. SAY [NUMBER | DIGITS | ALPHA | PHONETICS]: dice un nmero, dgito, caracter o una cadena fonticamente. SET [CONTEXT | EXTENSION | PRIORITY]: establece un nuevo contexto, extensin o prioridad luego de finalizada la ejecucin de script. VERBOSE: imprime un mensaje en el log. WAIT FOR DIGIT: espera que se presione un dgito. [SET | GET] VARIABLE: asigna u obtiene el valor de una variable del plan de marcacin.
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo 6

AGI
El programa debe:
Tener derechos de ejecucin y presentar un intrprete vlido
Ej yum y install php; chmod 755 mi_script.php

Estar localizado por defecto en /var/lib/asterisk/agibin

Cmo llamar al script desde el dialplan: exten => 123,1,Answer() exten => 123,2,AGI(mi_script.php,arg1,..,argn)
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo 7

AGI: ejemplo en PHP

El siguiente script est escrito en PHP y dicta los nmeros que se encuentran en el archivo que se le pasa como parmetro:
#!/usr/bin/php -q <?php // Esta lnea es para que que haga no mantenga en un buffer el output ob_implicit_flush(true); set_time_limit(60); error_reporting(0); // Se abren los diferentes archivos (STDIN, STDOUT y un archivo de log del AGI) $in = fopen("php://stdin","r"); $out = fopen("php://stdout","w"); $stdlog = fopen("/var/log/asterisk/my_agi.log", a"); // Si debug es true, escribe en el archivo de log definido anteriormente $debug = true;
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

AGI: ejemplo en PHP

// Toma el nombre del archivo con los nmeros a dictar del primer parmetro $archivo = $argv[1]; // Define la funcion read, que lee el input del STDIN function read() { global $in, $debug, $stdlog; $input = str_replace("\n", "", fgets($in, 4096)); if ($debug) fputs($stdlog, "read: $input\n"); return $input; } // Define la funcion write, que escribe el output en el STDOUT function write($line) { global $debug, $stdlog, $out; if ($debug) fputs($stdlog, "write: $line\n"); fputs($out,$line."\n"); fflush($out); }
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

AGI: ejemplo en PHP

// Parsea los headers del AGI (variables de entorno, etc) while ($env=read()) { $s = split(": ",$env); $agi[str_replace("agi_","",$s[0])] = trim($s[1]); if (($env == "") || ($env == "\n")) { break; } } // Lee el archivo que se paso como parametro $lines = file($archivo);

Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

10

AGI: ejemplo en PHP

// Reproduce los digitos contenidos en cada linea del mismo // informando en el log del Asterisk la accion realizada foreach ($lines as $line) { $line=trim($line); for ($i=0;$i<strlen($line);$i++) { write("VERBOSE \"REPRODUCIENDO DIGITO $line[$i]\""); read(); write("SAY DIGITS $line[$i] \"\""); read(); sleep(1); } } // Se cierran todos los handlers de archivos fclose($in); fclose($out); fclose($stdlog); exit;
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

11

AGI: ejemplo en PHP

Por ejemplo, si se quiere asociar el script a la extensin 200, se debe agregar al dialplan:
exten => 200,1,Answer(); exten => 200,2,AGI(dicta.php|/tmp/numeros.txt) exten => 200,3,Hangup()

Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

12

AGI: CLI
Los siguientes comandos pueden ser ejecutados en la CLI para obtener informacin sobre la AGI:
agi show command topic <command>: muestra informacin sobre el comando <command> del AGI agi show commands: lista todos los comandos del agi agi set debug on/off: activa/desactiva el debugging de la ejecucin de scripts va la AGI

Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

13

Ejercicio 10: AGI

Implementar una funcionalidad en Asterisk utilizando AGI

Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

14

Curso elaborado por Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch y Antonio Lobo
julian@dunayevich.com lazaro.baca@gmail.com abrassara@gmail.com salberch@gmail.com antoniwolf@gmail.com
Detalles de la licencia: http://creativecommons.org/licenses/by-nc-sa/2.5/deed.es_AR Autores: Autores: Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Brassara, Alberch, Alberch, Antonio Lobo (cc) Creative Commons - Attribute Non-Commercial Share-Alike 2.5 NonShareBasndose en: Irontec: contacto@irontec.com (CC)
Asterisk, The Future of Telephony, Jim Meggelen, Jared Smith, and Leif Madsen, OREILLY, 2005
Julin Dunayevich, Lzaro Baca, Andrs Brassara, Santiago Alberch, Antonio Lobo

15