Das Asterisk Buch von Stefan Wintermeyer

Das AGI-Skript bekommt über den „standard input“ (STDIN) einige Informationen von Asterisk. Das Format sieht folgendermaßen aus:

agi_request: programmname.php
agi_channel: Zap/1-2
agi_language: de
agi_callerid: Hans Beispiel
agi_context: extern
agi_extension: 1234
agi_priority: 2

Nach dem Übergeben dieser Grundinformationen sendet Asterisk noch eine Leerzeile, um dem AGI-Skript mitzuteilen, dass die Übertragung beendet ist.

Nachdem das AGI-Skript die Grundinformationen von Asterisk erhalten hat, beginnt es mit seiner Arbeit und gibt Befehle über „standard out“ (STDOUT) zurück an Asterisk. Um sich diese Kommunikation anzuschauen, kann man im CLI mit set verbose 5 den Verbosity-Level entsprechend hochsetzen.

„Standard error“ (STDERR) ist der formale Weg, um Fehler- oder Debugmeldungen vom AGI-Skript auf die Console (das CLI) von Asterisk zu bringen.

Wir besprechen das Beispiel-Skript zeilen- oder abschnittsweise.

#!/usr/bin/perl
use strict;

Die ersten zwei Zeilen sagen dem ausführenden Betriebssystem, dass es sich um ein Perl-Programm handelt, das mit dem Interpreter /usr/bin/perl ausgeführt werden soll. use strict bewirkt eine konsequentere Behandlung von Fehlern innerhalb des Perl-Programms.

$|=1;

Diese kleine Zeile bringt Perl dazu, die Ausgabe von Text nicht zu puffern. So können wir sicher sein, dass alle Ausgaben auch unmittelbar an Asterisk übergeben und nicht erst in einem Buffer zwischengespeichert werden.

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

Hier werden verschiedene Variablen definiert. Das Hash %AGI nimmt die initialen Eingaben von Asterisk auf. Die restlichen Variablen zählen die Gesamtanzahl der Tests, die Anzahl der fehlgeschlagenen Tests und die Anzahl der funktionierenden Tests.

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

Die eben eingelesenen Werte werden zum Debuggen auf STDERR, also im Endeffekt auf dem CLI ausgegeben:

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

Danach geht es mit checkresult weiter:

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++;
  }
}

Die Subroutine checkresult liest das Ergebnis eines Befehls an Asterisk aus und bestimmt, ob der Test erfolgreich war oder nicht. Entsprechend werden die Variablen $fail und $pass hochgezählt. Nachdem die Grundlagen gelegt sind, können die einzelnen Tests beginnen: Die Datei beep.gsm wird abgespielt.

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

Der Text "hello world" wird an den Anrufer geschickt. Das funktioniert natürlich nur, wenn das Protokoll und das Endgerät diese Funktion unterstützen.

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

Das Bild "asterisk-image" wird an den Anrufer geschickt. Auch diese Funktion ist vom Protokoll und dem Endgerät abhängig.

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

Die Zahl 192837465 wird dem Anrufer vorgelesen.

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

Dieser Befehl wartet 1000 Millisekunden auf die Eingabe von DTMF-Tönen durch den Anrufer.

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

Ein 3000-Millisekunden-langes GSM-Soundfile mit dem Namen testagi.gsm wird aufgenommen. Die Aufnahme kann durch die Eingabe der Zahlen 1, 2, 3 oder 4 unterbrochen werden.

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

Das soeben aufgenommene Soundfile wird abgespielt.

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

Nun erfolgt die Ausgabe auf dem CLI, wie viele Tests funktioniert oder nicht funktioniert haben.

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

Warnung

Bei vielen AGI-Befehlen sehen Sie den folgenden Aufbau: fwrite(STDOUT,"BEFEHL $value \"\"\n"); # ^^^^^^^ Der in dieser Zeile unterschlängelte Teil (zwischen $value und );) ist zwingend erforderlich, damit der Befehl korrekt ausgeführt wird. Es handelt sich hierbei um ein Argument ohne Inhalt, das durch zwei gequotete Anführungszeichen dargestellt wird. Abgeschlossen wird der gesamte Befehl durch ein ''line feed'' (ein Zeilenendzeichen), in diesem Fall ein \n.

Wer PHP und AGI einsetzen, aber nicht das Rad neu erfinden will, kann die fertige PHP-Klasse phpAGI benutzen. Informationen und die dazugehörigen Dateien finden Sie auf der Homepage des Projekts http://phpagi.sourceforge.net/.

Das folgende bei phpAGI mitgelieferte Programm gibt schnell einen Überblick über die Funktionsaufrufe^[145]

<?php
/**
* @package phpAGI_examples
* @version 2.0
*/

function my_ip(&$agi, $peer)
   {
    $ip = 'unknown';
    $asm = $agi->new_AsteriskManager();
    if($asm->connect())
    {
      $peer = $asm->command("sip show peer $peer");
      $asm->disconnect();
    
      if(!strpos($peer['data'], ':'))
        echo $peer['data'];
      else
      {
        $data = array();
        foreach(explode("\n", $peer['data']) as $line)
        {
          $a = strpos('z'.$line, ':') - 1;
          if($a >= 0) $data[trim(substr($line, 0, $a))] = trim(substr($line, $a + 1));
        }
      }
    
      if(isset($data['Addr->IP']))
      {
        $ip = explode(' ', trim($data['Addr->IP']));
        $ip = $ip[0];
      }
    }
    $agi->text2wav("Your IP address is $ip");
  }
?>

ANSWER

Funktioniert wie Answer() in der extensions.conf. Der Anruf wird entgegengenommen.

Ergebniswerte nach Ausführung:

CHANNEL STATUS [Kanalname]

Abfrage des Status eines Kanals. Wenn der Kanalname nicht angegeben ist, wird der aktuelle Kanal benutzt.

Ergebniswerte nach Ausführung:

DATABASE DEL Familie Schlüssel

Löscht den durch Familie und Schlüssel definierten Eintrag in der Asterisk-Datenbank.

Ergebniswerte nach Ausführung:

DATABASE DELTREE Familie

Löscht eine gesamte Familie aus der Asterisk-Datenbank.

Ergebniswerte nach Ausführung:

DATABASE GET Familie Schlüssel

Gibt den entsprechenden Eintrag für Familie/Schlüssel aus der Asterisk-Datenbank aus.

Ergebniswerte nach Ausführung:

DATABASE PUT Familie Schlüssel Wert

Speichert den Wert Wert in der Asterisk-Datenbank unter Familie/Schlüssel ab. Das kann ein Hinzufügen oder ein Update sein.

Ergebniswerte nach Ausführung:

EXEC Applikation Argumente

Führt eine Dialplan-Applikation aus (siehe Abschnitt 11, „Applikationen im Dialplan“). Die Argumente werden dabei der Applikation übergeben. Mehrere Argumente werden durch ein Pipe-Zeichen (|) getrennt.

Ergebniswerte nach Ausführung:

Beispiel:

EXEC Dial Zap/g1/123456

GET DATA Dateiname [Timeout] [maxZiffern]

Vergleichbar mit der Background()-Applikation in der extensions.conf. Spielt die Audiodatei mit dem Namen Dateiname ab und wartet auf DTMF-Eingaben. Diese werden durch maxZiffern limitiert. Die maximale Zeit wird durch Timeout begrenzt.

Ergebniswerte nach Ausführung:

GET FULL VARIABLE Variablenname [Kanalname]

Gibt den Wert der Variable Variablenname aus dem Kanal Kanalname (oder dem aktuellen) aus.

Ergebniswerte nach Ausführung:

GET OPTION Dateiname Escape_Ziffern [Timeout]

Verhält sich wie STREAM FILE. Bietet aber zusätzlich die Möglichkeit, einen Timeout in Sekunden anzugeben.

Ergebniswerte nach Ausführung:

GET VARIABLE Variablenname

Ähnlich wie GET FULL VARIABLE. Allerdings versteht GET VARIABLE keine komplexen oder systemeigenen Variablen.

	Warnung
	Im Zweifelsfall sollte man GET FULL VARIABLE benutzen.

Ergebniswerte nach Ausführung:

HANGUP [Kanalname]

Legt den virtuellen Hörer auf dem angegebenen Kanal auf. Wurde kein Kanalname angegeben, wird der aktuelle Kanal aufgelegt.

Ergebniswerte nach Ausführung:

NOOP [Text]

Es wird nichts gemacht (NOOP steht für No-Operation). Text wird auf dem CLI ausgegeben.

Ergebniswerte nach Ausführung:

RECEIVE CHAR Timeout

Wenn ein Channel die Übermittlung von Text unterstützt, dann kann mit RECEIVE CHAR ein einzelnes Zeichen empfangen werden. Timeout gibt die Wartezeit für den Empfang in Millisekunden an (0 für unendlich).

Ergebniswerte nach Ausführung:

RECEIVE TEXT Timeout

Wenn ein Channel die Übermittlung von Text unterstützt, dann kann mit RECEIVE CHAR ein solcher Text empfangen werden. Timeout gibt die Wartezeit für den Empfang in Millisekunden an (0 für unendlich).

Ergebniswerte nach Ausführung:

RECORD FILE Dateiname Format Escape_Ziffern Timeout [Offset] [BEEP] [s=Stille]

Funktioniert wie ein Rekorder, der alle Audiosignale in der Datei Dateiname im angegebenen Format aufzeichnet. Beendet werden kann dies durch einen definierten DTMF-Ton Escape_Ziffern oder durch einen Timeout in Millisekunden (dabei steht -1 für keinen Timeout).

BEEP spielt vor der Aufnahme einen Signalton. Stille definiert die Anzahl der Stille-Sekunden, bis die Applikation auch ohne Eingabe von DTMF-Tönen einen Timeout ausgibt.

Mit Offset wird vor Beginn der Aufnahme so viele Sekunden wie angegeben gewartet.

Ergebniswerte nach Ausführung:

SAY ALPHA String [Escape_Ziffern]

Buchstabiert den übergebenen String. Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SAY DATE Timestamp [Escape_Ziffern]

Sagt das übergebene Datum an. Timestamp ist dabei die Anzahl der Sekunden seit 00:00:00 Uhr am 1. Januar 1970. Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SAY DATETIME Timestamp [Escape_Ziffern] [Format] [Zeitzone]

Sagt das übergebene Datum. Timestamp ist dabei die Anzahl der Sekunden seit 00:00:00 Uhr am 1. Januar 1970. Das Format bestimmt die Art der Ausgabe. Folgende Werte sind dabei möglich:

Die Zeitzone wird wie in der Konfigurationsdatei /etc/asterisk/voicemail.conf angegeben.

Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden. Wenn Escape_Ziffern oder Format ausgelassen werden soll, muss stattdessen "" angegeben werden.

Ergebniswerte nach Ausführung:

SAY DIGITS Zahl [Escape_Ziffern]

Sagt die angegebene Zahl Ziffer für Ziffer an (z.B. wird 123 „eins, zwei, drei“ gesprochen). Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SAY NUMBER Zahl [Escape_Ziffern]

Sagt die angegebene Zahl an (z.B. 123 wird „ein-hundert-drei-und-zwanzig“ gesprochen). Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SAY PHONETIC String [Escape_Ziffern]

Sagt den angegebenen String im phonetischen NATO-Alphabet an (z.B. a wird „alpha“ gesprochen). Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SAY TIME Timestamp [Escape_Ziffern]

Sagt die übergebene Zeit. Timestamp ist dabei die Anzahl der Sekunden seit 00:00:00 Uhr am 1. Januar 1970. Die Ausgabe kann durch Eingabe einer Ziffer, die in Escape_Ziffern bestimmt wird, abgebrochen werden.

Ergebniswerte nach Ausführung:

SEND IMAGE Dateiname

Sendet das in Dateiname angegebene Bild auf den aktuellen Kanal. Der Dateiname darf keine Endung (z.B. .gif oder .jpg) enthalten. Diese Funktion wird von den meisten Channels nicht unterstützt.

Ergebniswerte nach Ausführung:

SEND TEXT "zu sendender Text"

Sendet den angegebenen Text auf den aktuellen Kanal. Diese Funktion wird von den meisten Channels nicht unterstützt.

Ergebniswerte nach Ausführung:

SET AUTOHANGUP Timeout

Stellt ein automatisches Auflegen nach der angegebenen Anzahl von Sekunden ein. Mit dem Wert 0 kann diese Funktion wieder deaktiviert werden.

Ergebniswerte nach Ausführung:

SET CALLERID Nummer

Setzt die Caller-ID des aktuellen Kanals.

Ergebniswerte nach Ausführung:

SET CONTEXT Contextname

Setzt den Context, der nach dem Ausführen der AGI-Applikation angesprungen wird.

Ergebniswerte nach Ausführung:

	Wichtig
	Es wird nicht überprüft, ob der Context existiert. Wenn Sie einen ungültigen Context angeben, wird der Anruf nach Beendigung des Skripts aufgelegt.

SET EXTENSION Extension

Setzt die Extension, die nach dem Ausführen der AGI-Applikation angesprungen wird.

Ergebniswerte nach Ausführung:

	Wichtig
	Es wird nicht überprüft, ob die Extension existiert. Wenn Sie eine ungültige Extension angeben, wird Asterisk nach Beendigung des Skripts bei der i-Extension weitermachen, falls vorhanden. Ansonsten wird der Anruf aufgelegt.

SET MUSIC [on [Klasse]|off]

Aktiviert (on) oder deaktiviert (off) die Warteschleifenmusik. Wenn Klasse nicht angegeben wurde, wird die Musikklasse default benutzt (siehe Konfigurationsdatei /etc/asterisk/musiconhold.conf).

Ergebniswerte nach Ausführung:

SET PRIORITY Priorität

Setzt die Priorität, die nach dem Ausführen der AGI-Applikation angesprungen wird (als Priorität kann auch ein Label angegeben werden).

Ergebniswerte nach Ausführung:

	Wichtig
	Es wird nicht überprüft, ob die Priorität existiert. Wenn Sie eine ungültige Priorität angeben, wird der Anruf nach Beendigung des Skriptes aufgelegt.

SET VARIABLE Variablenname Wert

Setzt die Kanal-Variable Variablenname auf den Wert Wert.

Ergebniswerte nach Ausführung:

STREAM FILE Dateiname Escape_Ziffern [Offset]

Spielt die angegebene Datei Dateiname ab (dabei darf keine Dateiendung wie .wav oder .gsm angegeben werden). Das Abspielen kann dabei durch die Eingabe einer Ziffer, die in Escape_Ziffern definiert wurde, abgebrochen werden. Ist dies nicht erwünscht (es soll also kein Abbruch möglich sein), so muss an dieser Stelle "" angegeben werden. Mit Offset kann ein Offset zum Start der Datei bestimmt werden.

Ergebniswerte nach Ausführung:

	Wichtig
	STREAM FILE funktioniert manchmal nicht korrekt mit anderen Sprachen als Englisch. Stattdessen kann man EXEC Playback Dateiname verwenden.

TDD MODE [on|off]

Aktiviert (on) oder deaktiviert (off) Übertragung und Empfang des TDD-Protokolls (Baudot) für TDD-Geräte (Telecommunications Device für the Deaf, Telekommunikationsgerät für Taubstumme, auch Schreibtelefon genannt) auf dem aktiven Kanal. Bisher wird TDD nur von Zap-Kanälen unterstützt.

Ergebniswerte nach Ausführung:

VERBOSE Meldung Level

Schreibt die Meldung auf das Command Line Interface (CLI). Level gibt dabei den Mindestwert des Verbosity-Levels an, damit die Ausgabe angezeigt wird.

Ergebniswerte nach Ausführung:

WAIT FOR DIGIT Timeout

Wartet auf die Eingabe eines DTMF-Tones. Timeout gibt den Timeout der Applikation in Millisekunden an.

Ergebniswerte nach Ausführung: