
         --------------------------------
        |                                |
        |            F D D K             |
        |                                |
        |   FAXDRIVER DEVELOPMENT KIT    |
        |                                |
         --------------------------------

Der Inhalt dieses Folders darf kopiert und weitergegeben
werden, solange er nicht verndert wird.

Folgende Dateien gehren dazu:


README
FDDK.TXT     (diese Datei)
QFAXDRV.O    (das eigentliche Faxmodul / TC-Format)
QFAXDRV.H    (der dazugehrige ANSI-C-Header)
MINIDEMO.C   (wie der Name schon sagt..)
MINIDEMO.PRJ (das dazugehrige Turbo-C Project-File)
QFAX.INF     (die Konfig-Datei bitte in die Root des
             (Bootlaufwerkes kopieren)
CALLQFAX.C   (ruft QFAX.ACC per Message-Pipe)



Erzeugen von Faxseiten mit jeder beliebigen Applikation
-------------------------------------------------------

"Ganz einfach nur Druckfunktion starten, Faxnummer eingeben 
und ferig?" Ein kleines Object-Modul ermglicht es einem 
C-Programmierer mit jeder beliebigen Applikation Faxseiten 
zu erzeugen. Auf das eher unbequeme Arbeiten mit Programmen, 
die das Erzeugen von Faxseiten selbst bernehmen knnte man 
dann verzichten. Das Besondere: dieses Modul ist 
Public-Domain und die damit erzeugten Faxtreiber knnen 
problemlos weitergegeben werden! 

Ich mchte hier die ntigen Funktionsaufrufe 
beschreiben, und die Benutzung anhand eines kleinen 
C-Programmes demonstrieren. An dieser Stelle sollte nicht 
verschwiegen werden, da das Erzeugen von Faxseiten auf 
anderen Betriebssystemen zentral bernommen wird (siehe z.B.
Next). Das ist natrlich besonders bequem. Durch den hier 
vorgeschlagene Weg ergibt sich aber ein anderer, 
entscheidenden Vorteil: jeder einzelne, der rund 4.000.000 
Pixel auf einer Faxseite, wird von der Applikation gesetzt. 
Dadurch knnen mgliche Qualtitsverluste durch eine 
Wandlung der vorgesehenen Auflsung nach 200 dpi sicher 
vermieden werden. Faxtreiber fr Calamus, TeX, CyPress und
andere Programme liegen schon vor. 



WIE FUNKTIONIERT ES ?

Zunchst mchte ich die Funktionsweise eines solchen 'Fax- 
Treibers' erlutern. Diese werden vom Benutzer wie normale 
Druckertreiber nachgeladen und nehmen dann die Daten von der 
Applikation entgegen. Allerdings wird zu diesem Zeitpunkt 
noch nicht gefaxt. Statt dessen werden die Daten komprimiert 
und in einer Art Warteschlange auf die Festplatte 
zwischengespeichert. Der verwendete Huffman-Algorithmus 
komprimiert die Daten auf bis zu 10% der ursprnglichen 
Gre. Die Seiten in der Fax-Queue werden spter auf Wunsch 
und in einem Rutsch versendet. Ein positiver Effekt dieses 
Verfahrens ergibt sich aus der Mglichkeit ein mehrseitiges Fax
mit Hilfe mehrerer Applikationen zu erstellen. So knnte man
z.B die erste Seite mit der Textverarbeitung erstellen und eine 
zweite Seite mit Calamus. 



5 plus 1 Funktionen

Das Object-Modul 'QFAXDRV.O', setzt sich aus den hier 
aufgefhrten 6 Funktionen zusammen. In der Datei 'QFAXDRV.H' 
befinden sich neben den Funktionsprototypen auch die 
Definitionen fr Fehlermeldungen. 

    int qfax_init (void)

Diese Funktion dient zur Initialisierung des Treibers und 
sollte einmal, zu allererst aufgerufen werden. Parameter 
werden hier keine bergeben. Wird (in Register D0) ein Wert 
ungleich Null zurckgegeben, liegt ein Fehler vor. Der Wert 
ERR_INIT deutet auf eine nicht vorhandene, bzw. fehlerhafte 
Konfigurationsdatei. Die Rckgabe des Wertes ERR_PATH 
bedeutet, da der Pfad in der Konfiguration nicht gefunden 
werden konnte. 


    int qfax_open (char *applic)

Zu Beginn einer neuen Seite wird diese Funktion aufgerufen. 
Sie erstellt die Ausgabedatei inklusive Fax-Header. Als 
Argument mu (in A0) ein Dateiname bergeben werden 
(Null-Terminiert, nicht vergessen). Dieser sollte mindestens 
6 aber maximal 8 Zeichen lang sein und auf die erzeugende 
Applikation deuten (z.B.: 'CALFAX', 'CYPFAX' etc.). Ein 
Return-Wert ungleich 0 deutet auch hier auf einen Fehler. 
Der Wert ERR_CREATE weist darauf hin, da nicht geschrieben 
werden konnte.


    int qfax_pix (unsigned char *pixptr, int lines)

Diese Funktion wird benutzt um Bitmap zu erzeugen. 
Dabei wird in 'lines' angegeben, wie oft die Pixelzeile 
in 'pixptr' wiederholt werden soll. In der Regel 
wird also in 'lines' eine '1' bergegeben. Der Parameter 
'pixptr' zeigt auf einen genau 216 Bytes groen 
Speicherbereich, indem sich eine Zeile Pixel befinden. Die 
Applikation stellt diesen Bereich zur Verfgung. 216 * 8 = 
1728 Pixel pro Zeile sind das Standard-Format fr die Breite 
von 200 dpi (bzw. 196 dpi) Faxseiten und mssen unbedingt
eingehalten werden.
Evtl. mu die Vorlage gestaucht werden. Eine Vorlage in einer 
Auflsung von 300 dpi mu also zuvor auf 2/3 gestaucht werden.
Nicht vergessen, da dann auch die Vertikale im selben 
Verhltniss gestaucht werden mu!
Die Pixelzeile wird nun komprimiert und gespeichert. 
Hierbei benutzt der Treiber einen internen, 8 KByte groen 
Cachespeicher. Diese Funktion gibt den Wert ERR_WRITE 
zurck, wenn ein Fehler beim schreiben aufgetreten ist. Bei 
fehlerfreier Funktion wird ein Wert grer '0' zurckgegeben 
der aussagt, auf wieviele Bytes komprimiert wurde. Es spielt 
absolut keine Rolle wie oft diese Funktion aufgerufen wird, 
weil eine Faxseite beliebig lang bzw. kurz sein kann. 2240 
Pixelzeilen ergeben eine Faxseite von 29.68 cm hhe (= DIN-A4).
75 Aufrufe ergeben etwa 1 cm Fax! 


    int qfax_text (char *string)

Diese Funktion wird benutzt um Text auf eine Faxseite zu 
schreiben. Es wird ein im Modul integrierter Font verwendet, 
der sich besonders fr die bertragung im Faxformat eignet. 
Der Font erzeugt nmlich besonders 'wenig' Hufman-Code und 
beschleunigt damit die bertragung. Pro Textzeile werden 32 
Pixelzeilen erzeugt. Auf eine A4-Seite maximal 70 Zeilen 
Text. Pro Zeile knnen bis zu 98 Zeichen untergebracht 
werden. Es drfen keine Steuerzeichen, auch kein Linefeed 
bergeben werden. Diese Funktion gibt ebenfalls den Wert 
ERR_WRITE zurck, wenn ein Fehler beim Schreiben aufgetreten 
ist. Bei fehlerfreier Funktion wird ein Wert grer '0' 
zurckgegeben der aussagt, wieviel Bytes erzeugt wurden. 


    int qfax_close (void)

Diese Funktion wird am Seitenende aufgerufen. Sie fllt den 
Fax-Header mit den richtigen Werten und schliet die Datei. 
Ein Return-Wert ungleich '0' deutet auf einen Fehler beim 
Schreiben. Wenn alles fehlerfrei funktioniert hat, kann die 
nchste Seite geffnet werden. 


    int qfax_clr (void)

Mit dieser Funktion kann die Queue, z.B. vor dem erzeugen 
neuer Seiten, gelscht werden. Wird danach eine neue 
Faxseite angelegt, erhlt diese die Erweiterung '.F01' im 
Dateinamen. Die nchste Seite '.F02' usw.
Das geschieht ganz automatisch.

Der Treiber kann brigens problemlos wieder entfernt werden. 
Die Erzeugten Seiten werden in der Fax-Queue gespeichert, 
was nichts anderes ist als ein Directory, das speziell dafr 
angelegt wurde. Hier zum Beispiel der Inhalt dieses 
Verzeichnisses nachdem drei Seite mit verschiedenen 
Applikationen erzeugt wurden: 

    "CYPRESS .F01"
    "ASCII   .F02"
    "CALAMUS .F03"

Fr jede Seite wurde eine Datei angelegt. Die nchste Seite 
wrde die Erweiterung ".F04" erhalten. Der Dateiname vor der 
Erweiterung spielt fr das Versenden keine Rolle. Er gibt 
dem Benutzer nur Auskunft darber, welches Programm die 
Seiten erzeugt hat.



FORMAT DER FAX-DATEI
--------------------

 01-24  : reserved
 25     : 01 = 1-Dim, 02 = 2-Dim
 26-27  : Seiten in Pixelzeilen             (sorry: INTEL-Format)
 28-29  : Breite in Pixeln, z.Z. immer 1728 (sorry: INTEL-Format)
 30     : Auflsung 0 = 100 dpi, 1 = 200 dpi
 31-255 : reserved!
256-eof : huffman-code


DEMO-PROGRAMME IN ANSI-C
------------------------

Die beiliegende C-Source 'MINIDEMO.C' zeigt, wie einfach die
Benutzung der hier vorgestellten Funktionen ist. 

Das Accessory "QFAX.ACC" gestattet das Versenden der 
erzeugten Seiten an einen oder mehrere Empfnger. Die mit 
dem Modul erzeugten Faxseiten und das Modul selbst drfen 
frei weitergegeben werden. Eine V e r m a r k t u n g solcher 
Treiber bedarf meiner schriftlichen Genehmigung. 
(In der Regel kein Problem.)

Das Programm CALLQFAX.C demonstriert die Mglichkeit QFax aus einer
anderen GEM-Applikation aufzurufen. Zusammen mit dem FDDK kann
eine Applikation Faxseiten erzeugen und direkt an ein Faxgert
versenden.


Wenn Sie bis hier hin gelesen haben, bedanke ich mich
fr Ihre Geduld. Weitere Informationen erhalten
Sie ber die Firma Computer & Design in Hagen.
