# 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>