Stefan Hacker
114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# BlacklistBlock - STARFACE Custom Block
|
||
|
||
Ein Custom Block für den STARFACE Module Designer, der eingehende Anrufe gegen eine
|
||
konfigurierbare Blacklist prüft und anonyme Anrufe (unterdrückte Rufnummer) separat
|
||
behandelt. Pro Eintrag kann festgelegt werden, **was** mit dem Anruf passieren soll.
|
||
|
||
## Funktionsweise
|
||
|
||
Der Block wird **bei jedem eingehenden Anruf** ausgeführt (Modultyp *Call-Processing*).
|
||
Ablauf:
|
||
|
||
1. `GetCaller2` ermittelt Anrufernummer, Name und das Flag `isAnonymous`.
|
||
2. **Anonymer Anruf** (unterdrückte Rufnummer): es greift die *Aktion bei anonymen Anrufen*.
|
||
3. Andernfalls wird die Nummer gegen die **Blacklist-Einträge** geprüft (erster Treffer gewinnt).
|
||
4. Bei einem Treffer wird die zugehörige Aktion ausgeführt.
|
||
5. Kein Treffer / Aktion `NONE` / `ALLOW` → der Block tut nichts, der Anruf läuft normal weiter.
|
||
|
||
Die Aktionen nutzen die eingebauten STARFACE-Blöcke (`Hangup`, `Busy`, `CallPhonenumber2`,
|
||
`Answer` + `PlaybackResourceFile2`), die per Reflection im selben Anruf-Kontext aufgerufen
|
||
werden – dadurch bleibt der Block über STARFACE-Versionen hinweg robust.
|
||
|
||
## Aktionen
|
||
|
||
| Aktion | Wirkung |
|
||
|------------|---------------------------------------------------------------------|
|
||
| `HANGUP` | Anruf sofort auflegen (Anrufer wird getrennt) |
|
||
| `BUSY` | Besetztzeichen senden |
|
||
| `REDIRECT` | Anruf auf eine andere Nummer/Nebenstelle umleiten (Ziel erforderlich)|
|
||
| `ANNOUNCE` | Anruf annehmen, Ansage abspielen, dann auflegen |
|
||
| `ALLOW` | Ausnahme – Anruf trotz Treffer durchstellen (für Whitelist-Fälle) |
|
||
| `NONE` | (nur anonym) nichts tun, Anruf normal durchstellen |
|
||
|
||
## Kompatibilität
|
||
|
||
- STARFACE 8.x, 9.x, 10.x (Java 21)
|
||
|
||
## Konfigurationsfelder (Eingabe)
|
||
|
||
| Feld | Typ | Beschreibung | Default |
|
||
|------|-----|--------------|---------|
|
||
| `blacklistEntries` | STRING (mehrzeilig) | Nummern + optionale Aktion/Ziel, eine pro Zeile | |
|
||
| `defaultAction` | STRING (Auswahl) | Aktion für Einträge ohne eigene Aktion | `HANGUP` |
|
||
| `defaultRedirectTarget` | STRING | Ziel für REDIRECT-Einträge ohne eigenes Ziel | |
|
||
| `announcementFile` | STRING | Name der Sound-Ressource für `ANNOUNCE` | |
|
||
| `anonymousAction` | STRING (Auswahl) | Behandlung anonymer Anrufe | `NONE` |
|
||
| `anonymousRedirectTarget` | STRING | Ziel bei `REDIRECT` für anonyme Anrufe | |
|
||
| `countryCode` | STRING | Eigene Ländervorwahl (Deutschland = 49) | `49` |
|
||
| `prefixMatch` | BOOLEAN | Bereichssperre: Eintrag sperrt auch beginnende Nummern | `true` |
|
||
|
||
## Ausgabe-Variablen
|
||
|
||
| Feld | Typ | Beschreibung |
|
||
|------|-----|--------------|
|
||
| `caller` | STRING | Erkannte Anrufernummer (international normalisiert) |
|
||
| `isAnonymous` | BOOLEAN | Rufnummer unterdrückt? |
|
||
| `blocked` | BOOLEAN | Wurde der Anruf behandelt (geblockt/umgeleitet)? |
|
||
| `actionTaken` | STRING | Tatsächlich ausgeführte Aktion |
|
||
| `statusMessage` | STRING | Status-Meldung |
|
||
|
||
## Format der Blacklist-Einträge
|
||
|
||
Eine Nummer pro Zeile (Komma geht auch). Pro Zeile optional eine eigene Aktion und ein Ziel:
|
||
|
||
```
|
||
nummer;AKTION;ziel
|
||
```
|
||
|
||
Beispiele:
|
||
|
||
```
|
||
# Kommentarzeile, wird ignoriert
|
||
+49301234567 # nutzt die Standard-Aktion
|
||
0190;BUSY # dieser (Bereich) immer besetzt
|
||
004989;REDIRECT;100 # auf Nebenstelle 100 umleiten
|
||
+4972112345;ALLOW # Ausnahme: trotz Bereichssperre durchstellen
|
||
0900;ANNOUNCE # Ansage abspielen und auflegen
|
||
```
|
||
|
||
**Reihenfolge:** Der erste passende Eintrag gewinnt. `ALLOW`-Ausnahmen daher **vor**
|
||
breite Bereichssperren setzen.
|
||
|
||
## Nummern-Vergleich
|
||
|
||
Alle Nummern werden vor dem Vergleich in eine einheitliche internationale Ziffernform
|
||
gebracht (`countryCode` = 49):
|
||
|
||
| Eingabe | normalisiert |
|
||
|---------|--------------|
|
||
| `+49 721 12345` | `4972112345` |
|
||
| `0049 721 12345` | `4972112345` |
|
||
| `0721 12345` | `4972112345` |
|
||
| `100` (intern) | `100` |
|
||
|
||
Bei `prefixMatch = true` sperrt ein Eintrag auch alle Nummern, die mit ihm beginnen
|
||
(z.B. `0190` → gesamter `0190`-Bereich). Zum Schutz vor versehentlichem Über-Sperren
|
||
greift die Bereichssperre erst ab 3 Ziffern; kürzere Einträge werden nur exakt verglichen.
|
||
|
||
## Build
|
||
|
||
```bash
|
||
./build-block.sh
|
||
```
|
||
|
||
Die STARFACE-API-JARs werden in `libs/starface/` erwartet. Sind sie dort nicht vorhanden,
|
||
nutzt das Script automatisch die JARs des `mail2fax`-Moduls
|
||
(`../../mail2fax/v8-9-10/libs/starface/`). Ergebnis: `BlacklistBlock.class`.
|
||
|
||
Es werden **keine** zusätzlichen Bibliotheken benötigt (kein JavaMail o.ä.).
|
||
|
||
## Installation im Module Designer
|
||
|
||
Siehe **[INSTALLATION.md](INSTALLATION.md)** für die Schritt-für-Schritt-Anleitung.
|
||
</content>
|