Listeners
Die Listeners-Datei enthält eine Liste von Regeln, die festlegen, welche Aktionen unter welchen Bedingungen ausgeführt werden sollen.
Leerzeilen werden ignoriert, ebenso Zeilen, die mit # beginnen (das sind Kommentare).
Jede Regel steht in einer Zeile und besteht aus vier Angaben, die durch Leerraum getrennt in dieser Reihenfolge aufeinander folgen:
- Ereignis
- Quellrufnummer: Muster für SOURCE
- Zielrufnummer: Muster für DEST
- Aktion: Beliebiger Shell-Code
Die beiden Muster für SOURCE und DEST sind "extended regular expressions" (ERE), wie sie von egrep verstanden werden. Das Ereignis (ein-/ausgehender Anruf; Klingeln, Annahme, etc.) wird mit der unten angeführten Syntax angegeben.
Man kann negative Muster bei den Listeners verwenden, indem man ein Ausrufezeichen voranstellt: “!123“ passt auf alle Nummern, die nicht irgendwo 123 enthalten.
Beispiele:
| Muster | passt auf |
|---|---|
| ^ | alle Nummern |
| ^034 | Nummern, die mit 034 beginnen |
| 4563$ | Nummern, die auf 4563 enden |
| !^(045|0164) | Nummern, die nicht mit 045 oder 0164 beginnen |
| ^0123456$ | nur genau die Nummer 0123456 |
| ^04553...$ | die Nummern, bei denen nach 04553 genau drei weitere Zeichen folgen |
Alle Regeln werden parallel abgearbeitet; eine bestimmte Reihenfolge ist nicht garantiert.
Damit die Listeners über das Webinterface des ds-mod bearbeitet werden können, muss dessen Sicherheitsstufe auf 0 gesetzt werden. Das ist nötig, da über die Listeners beliebiger Code ausgeführt werden kann.
Format
Seit Version 1.0 des Callmonitors gilt folgendes Format für die Listeners, mit dem auf bis zu acht verschiedene Ereignisse unterschiedlich reagiert werden kann:
- *:request: Anruf kommt an (es klingelt)
- *:cancel: Anruf wurde abgebrochen, bevor eine Verbindung zustande kam (so kann man direkt auf „verpasste Anrufe“ reagieren)
- *:connect: Verbindung beginnt
- *:disconnect: Verbindung wurde beendet
Dazu kommt die Unterscheidung zwischen
- in:*: eingehenden und
- out:*: ausgehenden Anrufen.
Das ergibt folgende Menge von Ereignissen:
| *:request | *:cancel | *:connect | *:disconnect | |
|---|---|---|---|---|
| in:* | in:request | in:cancel | in:connect | in:disconnect |
| out:* | out:request | out:cancel | out:connect | out:disconnect |
Dazu passend haben die Listeners eine zusätzliche erste Spalte bekommen, in der (mit Hilfe von Abkürzungen und Wildcards) das gewünschte Ereignis angegeben werden kann, auf das die betreffende Regel reagieren soll:
in:request ^ ^1234$ xboxmessage xbox
in:cancel ^ ^ mailmessage -t test@example.com
out:cancel ^1234$ ^0123 dboxpopup dbox-a "${DEST} geht nicht ran"
*:dis ^ ^ echo "Anruf beendet: ${DURATION} Sekunden" >> log
Es kann mehrere Regeln geben, die auf dasselbe Ereignis passen.
Die Präfixe „NT:“, „E:“ und „*:“ in der SOURCE-Spalte gibt es nicht mehr. Eure bisherige Listeners-Datei (vor Version 1.0) könnt ihr nicht einfach weiterverwenden. Der Callmonitor versucht aber, beim ersten Start eine grobe Konvertierung vorzunehmen, um euch den Umstieg zu erleichtern. Auf jeden Fall solltet ihr aber die Listeners nach der Umstellung einmal kontrollieren.
Die Spalten 2 und 3 in den Listeners sind weiterhin Muster (reguläre Ausdrücke) für Quell- und Zielrufnummer (SOURCE und DEST).
Dabei ist jedoch zu beachten, dass in Spalte 2 bzw. 3 die MSNs, also die Internet-Rufnummern, anzugeben sind und nicht wie früher bspw. SIP0 oder SIP1.
Ereignis-Informationen für Aktionen
Den Aktionen stehen Informationen über den auslösenden Anruf in Umgebungsvariablen bereit. Sie werden in Shell-Scripten mit einem $ referenziert, also z.B. „echo $SOURCE_NAME“.
| Variable | Inhalt | seit Version |
|---|---|---|
| EVENT | das auslösende Ereignis | 1.0 |
| ID | die ID des Anrufs (direkt von der Callmonitor-Schnittstelle) | 1.0 |
| TIMESTAMP | der Zeitpunkt des Ereignisses (im Format „DD.MM.YY HH:MM“) | 1.0 |
| SOURCE | Quellrufnummer | — |
| SOURCE_DISP | „anzeigefreundlichere“ Variante von SOURCE (Landesvorwahl weg, Call-by-Call-Vorwahlen weg, etc.) | 1.8 |
| SOURCE_NAME | Name der Quelle, falls dieser bestimmt werden konnte | — |
| DEST | Zielrufnummer | — |
| DEST_NAME | Name des Ziels, falls dieses bestimmt werden konnte | — |
| DEST_DISP | „anzeigefreundlichere“ Variante von DEST (Landesvorwahl weg, Call-by-Call-Vorwahlen weg, etc.) | 1.8 |
| EXT | die Nebenstelle, sofern bekannt (direkt von der Callmonitor-Schnittstelle) | 1.0 |
| DURATION | bei *:disconnect die Dauer des Gesprächs in Sekunden | 1.0 |
| PROVIDER | Dienstleister, über den der Anruf abgewickelt wird („POTS“ für Festnetz oder „SIP0“, „SIP1“, … für die verschiedenen SIP-Provider) | 1.5 |
Formatierung der Ausgaben
Zur Formatierung der Ausgaben stehen folgende Funktionen bereit:
seit Version 1.8:
- f_duration: zur Darstellung von Zeitdauern als „hh:mm:ss“
f_duration <ZEIT_IN_SEKUNDEN> ZEIT_IN_SEKUNDEN: Zeit in Sekunden, z.B. $DURATION
Beispiel:
echo "Der Anruf dauerte $(f_duration $DURATION)"
führt zu einer Ausgabe
Der Anruf dauerte 1:05:03
falls DURATION den Wert 3903 hat.
Als nützlich kann sich auch die Konstante $LF erweisen, die einen Zeilenumbruch enthält (line feed):
dboxmessage foo.bar "Zeile 1${LF}Zeile 2"
Muster für Ereignisse
Es gibt mehrere Möglichkeiten, in den Listeners die Ereignisse anzugeben, bei der eine Regel auslösen soll:
- Vollständige Ereignisnamen:
in:request out:disconnect
- Abkürzungen des vorderen und/oder hinteren Teils:
in:req out:disc i:r o:d
- Wildcards für den vorderen Teil (Richtung), den hinteren oder beide:
*:req ou:* *
- Listen dieser Bestandteile (mit Komma getrennt (Vorsicht, kein Whitespace); die Regel passt, wenn einer der Teile passt):
in:req,out:*
