FAQ

Wie integriere ich die Auerswald-Fax-Schnittstelle in eigene Treiber oder Software?

Auerswald Fax-Versand via Netzwerk

  1. Allgemeines

    Mit der Auerswald-Fax-Schnittstelle wurde ein Übertragungsweg fĂŒr den Fax-Versand ĂŒber eine Auerswald-Telefonanlage realisiert. Um eine möglichst weitgehende Verwendung bereits bestehender Quelltexte zu ermöglichen, wird hierbei auf Standardprotokolle zurĂŒckgegriffen.
    Als Basisprotokoll fĂŒr die Übertragung wird HTTP/HTTPS verwendet. HierfĂŒr existiert in den Telefonanlagen eine funktionierende Infrastruktur. Auf Seiten des versendenden Computers gibt es hierfĂŒr i.d.R. bereits fertige Programmbibliotheken.
    Der Inhalt des Fax (d. h. das Dokument) wird als Bild in TIFF-G3-Kodierung ĂŒbermittelt. Auch hierfĂŒr gibt es fĂŒr den Sender meist fertige OSS-Druckertreiber zur Erzeugung dieses Formates. Die Telefonanlage kann dieses Format ohne weitere Umkodierung direkt fĂŒr den Versand verwenden.

  2. UnterstĂŒtzte Telefonanlagen

    Folgende Systeme werden unterstĂŒtzt (je nach System sind zusĂ€tzliche Erweiterungen nötig):

    • COMpact 3000 analog/ISDN/VoIP
    • COMpact 4000
    • COMpact 5000/5000R
    • COMpact 5010/5020 VoIP
    • COMmander Basic.2 / Basic.2 19
    • COMmander Business / Business 19
    • COMmander 6000/6000R/6000RX
  3. Übertragungsprotokoll

    Zur Übertragung wird die HTTP/HTTPS-Methode POST verwendet.

    Beispiel:

    POST /faxupload HTTP/1.1
    User-Agent: auFaxAgent
    Host: 192.168.20.154
    Connection: Keep-Alive
    Cache-Control: no-cache
    Content-Type: multipart/form-data; boundary=456C6C536F742D48616D52757267
    Authorization: Digest username="801", realm="Auerswald", nonce="bdf981eab52a4f0993748bf6021c81a1", cnonce="666",nc="00000001", qop=auth, uri="/faxupload", algorithm=MD5,
    response="76d6900e6af5802ae0e86c959e26988e"
    Content-Length: 14910

    --456C6C536F742D48616D52757267
    Content-Disposition: form-data; name=""; faxdest="345345"; filename="fax.tiff"
    Content-Type: image/tiff
    [ab hier folgen die BinÀrdaten]
    II*.x7.........@.6j.).P.M..
    l..Sf...5.......@.6j.).P.M..
    &
    [bis hier folgen die BinÀrdaten]
    ----456C6C536F742D48616D52757267

    Die URL faxupload enthÀlt dabei als POST-Parameter die Rufnummer des Fax-EmpfÀngers (faxdest=[Rufnummer]).

    Zur Authentisierung mittels Benutzername und Passwort wird DAA (Digest Authentication Access) verwendet. Der Benutzername ist hierbei die interne Rufnummer des Teilnehmers (MSN), das Passwort ist die fĂŒr diese Rufnummer eingetragene 6-stellige PIN (fĂŒr COMpact 3000-Serie) bzw. ein mindestens 8-stelliges alphanumerisches Passwort (COMpact 5000/5000R, COMpact 5010/5020 VoIP, COMmander Business, COMander Basic.2, COMmander 6000/6000R/6000RX).

    Das Dokument wird mit dem mimetype image/tiff nach der Authentisierung als multipart/form-data ĂŒbermittelt. Die Übertragung erfolgt immer im BinĂ€rformat, d. h. keine base64-Kodierung.

    Die Telefonanlage als HTTP/HTTPS-Server kann beim Verbindungsaufbau oder bei der Übertragung einen Fehler feststellen. Der Fehler wird erst nach Ende der Übertragung an die Senderseite ĂŒbermittelt. Ein vorzeitiger Abbruch des Uploads ist nach dem HTTP/HTTPS-RFC nicht vorgesehen. Der Sender soll die Fehlermeldung aus dem socket auslesen und eine entsprechende Reaktion auslösen.

    Folgende Fehlermeldungen muss der Sender behandeln:

    • 301 moved permanently
      302 found moved temporarily
      In diesem Fall muss der Versand nochmals mit der in der Meldung angegebenen URL durchgefĂŒhrt werden.
      Diese RĂŒckmeldung erfolgt z. B., wenn der HTTP/HTTPS-Server der Anlage eine HTTP-Anfrage erhĂ€lt, aber in der Anlagenkonfiguration die Option 'HTTPS-Verbindung erzwingen' aktiviert ist.
    • 401 unauthorized
      Der Teilnehmer ist unbekannt, oder das Passwort passt nicht.
    • 403 forbidden
      Der Teilnehmer ist zwar bekannt, Fax-Versand ist aber nicht aktiviert.
    • 404 not found
      Fax-Versand ist mit dieser Telefonanlage nicht möglich.
    • 413 Request Entity Too Large
      Das Fax konnte nicht versendet werden. Pro Fax-Dokument sind nur max. 50 Seiten erlaubt.
    • 415 unsupported media type
      Der mimetype ist falsch, oder das Fax hat nicht das richtige Format.
    • 503 service unavailable
      Der Fax-Server steht derzeit nicht zur VerfĂŒgung.
    • 507 insufficient storage
      Der Fax-Puffer der Telefonanlage ist ĂŒberfĂŒllt.

    Eine abgebrochene Verbindung ohne Übermittlung eines HTTP/HTTPS-Statuscodes soll wie 503 behandelt werden.

    Eine erfolgreiche Anfrage wird mit 200 OK beantwortet. Diese Antwort beinhaltet aber lediglich, dass das Fax erfolgreich in die Versandwarteschlange der Telefonanlage ĂŒbernommen wurde. Das sollte dem Benutzer auch so mitgeteilt werden.

    Beispielantwort fĂŒr eine erfolgreiche HTTP/HTTPS-Übertragung:

    HTTP/1.1 200 OK
    Server: GoAhead-Webs
    Expires: 0
    Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
    Pragma: no-cache
    Content-Type: text/html; charset=iso-8859-1;

    Beispielantwort fĂŒr eine nicht erfolgreiche HTTP/HTTPS-Übertragung:

    HTTP/1.1 503 Site Temporarily Unavailable. Try again.
    Server: GoAhead-Webs
    Date: Mon, 12 Sep 2011 08:27:53 GMT
    Pragma: no-cache
    Cache-Control: no-cache
    Content-Type: text/html; charset=iso-8859-1;

    <html><head><title>Document Error: Site Temporarily Unavailable. Try again.</title></head>
    ...<body><h2>Access Error: Site Temporarily Unavailable. Try again.</h2>
    ...<p></p></body></html>

    Eine unmittelbare RĂŒckmeldung ĂŒber die AusfĂŒhrung des Faxauftrags wird nicht ĂŒbermittelt.

  4. Übertragungsformat

    Fax-Inhalte werden an die Anlage grundsĂ€tzlich als TIFF in G3-Kodierung ĂŒbermittelt. FĂŒr die TIFF-Kodierung gelten folgende Voraussetzungen bzw. EinschrĂ€nkungen:

    • Byte Order: Little Endian
    • Hinter dem TIFF-Header erst die Image-Daten, dann der IFD-Table, dann ggf. vom IFD referenzierte Zusatzdaten
    • Seitenformat wie nach T.4 fĂŒr das Papierformat A4 vorgegeben mit folgenden festen Parametern: schwarz/weiß, MR-Verfahren, 1.728 Pixel horizontal (203 dpi), die vertikale LĂ€nge ist nicht vorgegeben (196 dpi), eine Zerlegung eines langen Original-Dokumentes auf A4-Seiten wird aber wegen der Darstellung im Webserver der Anlage empfohlen!
    • Die einzelnen Fax-Seiten werden innerhalb eines Anhangs als mehrseitiges TIFF-Dokument ĂŒbertragen.

    Folgende IFD-Tags mĂŒssen mit den vorgegebenen Werten belegt sein:

    Tag ID Wert
    Image Width
    Bits per Sample
    Compression
    Photometric
    Group3Options
    0x100
    0x102
    0x103
    0x106
    0x124
    1728
    1
    3
    0
    0
    A4
    B/W
    CCITT Group 3
    White is Zero
    1-dim., RLE, no fillbits

    Folgende IFD-Tags mĂŒssen mit der Seite entsprechenden Werten belegt sein:

    Tag ID Wert
    Image Height
    Strip Offset
    Strip Byte Count
    0x101
    0x111
    0x117
    LĂ€nge der Seite in Pixelzeilen
    Offset auf Image Daten
    LĂ€nge der Image Daten

    Folgende IFD-Tags werden erkannt aber nicht ausgewertet:

    Tag ID Verwendeter Wert
    Rows per Strip
    xResolution
    yResolution
    0x116
    0x128
    0x129
    -1 Ein Strip pro Seite
    203 DPI
    196 DPI

    Alle weiteren IFD-Tags und zusÀtzliche beschreibende Daten werden (vorerst) ignoriert.

    Umwandlung der zu faxenden Bilddaten:

    1. Tools
      gs: steht Exemplarisch fĂŒr Ghostscript
      tiffcp: Tool erzeugt aus mehreren Tiffs ein einziges Tiff
    2. Beispielhafte Befehlsfolge
      gs -q -sDEVICE=tiffg3 -dNOPAUSE -dBATCH -g1728x2254 -r203x196 -sOutputFile=result.tiff + filename;
      tiffcp -c g3:1d -r -1 result.tiff result.0.tiff

    Das entstandene Tiff (result.0.tiff) wird dann zwischen die Boundarys eingebedded und zur Anlage gesendet.

  5. Verhalten der Telefonanlage

    Nachdem das Fax-Dokument per HTTP/HTTPS-Upload auf die Telefonanlage ĂŒbertragen wurde, stellt der Fax-Server es in die Fax-Warteschlange ein. Der Fax-Server arbeitet nun, wie fĂŒr diesen spezifiziert, die Fax-Warteschlange ab.

    Ist fĂŒr den Fax-Versand eine Benachrichtigung durch E-Mail vorgesehen, wird nach erfolgtem Versand ein Versandbericht erstellt und versendet. HierĂŒber kann der Sender erfahren, dass der Fax-Versand beendet ist und ob der Versand erfolgreich war.

  6. Parameter des Senders

    Auf Senderseite mĂŒssen mindestens folgende feste Parameter mit einem Konfigurations-GUI eingestellt werden:

    • IP-Adresse der Telefonanlage
    • MSN des Teilnehmers (2 – 4 Ziffern)
    • zugehörige PIN (6 Ziffern) bzw. Passwort (a – z, A – Z, 0 – 9; min. 8, max. 32 Zeichen)

    FĂŒr jedes Fax werden noch zusĂ€tzlich diese Parameter beim Benutzer abgefragt:

    • Rufnummer des Fax-EmpfĂ€ngers (40 Ziffern) mit fĂŒhrender Amtszugangsziffer (Sollte in der Telefonanlage die automatische Amtholung aktiviert sein, darf die Rufnummer keine fĂŒhrende Amtszugangsziffer enhalten.)