[Bitte ersetzen Sie dieses Platzhalter-Dokument selbstverständlich durch ihr eigenes Benutzerhandbuch, bevor Sie es an Ihre Kunden ausliefern.]

 

Doc2Fax API

 

1. Das Direkt-Fax-Problem und seine Lösung

 

Bekanntermaßen ist es sehr umständlich, ein digitales Dokument erst auszudrucken, um das bedruckte Papier dann im Fax-Gerät wieder zu re-digitalisieren, bevor man es schließlich an den Adressaten senden kann.

 

Hardware-Bauteile wie Fritz-Card, ISDN-Karte & Co. schaffen hier Abhilfe, indem sie Rechner und Telefonleitung quasi kurzschließen - und mit ihnen ist ein riesiger Markt für Fax-Software entstanden, die diese Hardware-Teile ansteuert, um darüber Daten zu versenden.

 

Wenn Sie als Programmierer oder Software-Entwickler nun Ihren Kunden selbst eine maßgeschneiderte Fax-Software anbieten möchten, mit der der Endbenutzer seine digitalen Dokumente - denken Sie dabei etwa an ein MS Word *.doc - ohne Fax-Gerät praktisch direkt in die Telefonleitung ausdrucken kann, dann stellen sich Ihnen zwei grundlegende Probleme:

 

 

 

 

Die einzige Lösung:

 

Ein Druckertreiber, der die grafischen Daten und den Text des zu druckenden bzw. zu faxenden digitalen Dokuments in Dateien niederlegt und Ihre Software über alle Druckvorgänge, -Ereignisse und Dateinamen benachrichtigt, so dass Ihre Software darauf reagieren kann - und all das leistet der Doc2Fax-Druckertreiber.



2. Zielgruppe: An wen richtet sich Doc2Fax API ?

 

Gelegentlich rufen uns Interessenten an und fragen, warum sie denn eigentlich Doc2Fax API kaufen sollen, wenn doch etwa der Treiber der Firma Peernet, der doch im Prinzip auf eine ähnliche Weise funktioniert wie der Doc2Fax-Druckertreiber, schon für unter 100 Euro zu haben ist ? - Ganz einfach:

 

Der genannte Preis bezieht sich auf eine einzige Endkunden-Lizenz. Der Peernet-Treiber richtet sich an Endkunden, die es nicht stört, dass z.B. auf jeder Eigenschaftsseite des Treibers, also dort wo der Benutzer etwa Seitengröße und Auflösung einstellt, das Peernet-Logo erscheint, und dem es auch egal ist, welcher Druckername und Hersteller z.B. im Druckdialog oder bei der Installation angezeigt werden.

 

Doc2Fax API dagegen richtet sich an Software-Entwickler, die ihren Kunden eine Fax-Software inklusive Treiber anbieten möchten, dessen Treiber einen Druckernamen und Hersteller ausweist, den der Software-Entwickler selbst frei wählen kann. Der Preis von Doc2Fax API bezieht sich also auf eine Entwickler-Lizenz mit unbeschränkter Anzahl von Endkunden-Lizenzen.

 

Doc2Fax API ermöglicht es Ihnen, einen Druckertreiber nach Ihren eigenen Wünschen und Erfordernissen zu konfigurieren, ohne auch nur die geringsten Kenntnisse über Druckertreiber-Programmierung oder überhaupt über Programmierung mitbringen zu müssen. 

 

 

 

3. Funktionsweise

Doc2Fax API ist für

·         Windows 2000

·         Windows XP

·         Windows Server 2003

·         und Windows Vista

geeignet. (Darüber hinaus gibt es gewissermaßen aus Gründen der Abwärtskompatibilität noch eine Version für

·         Windows 95

·         Windows 98

·         und Windows ME,

die Sie unter info@driverlab.de anfordern können.)

Wenn der Benutzer den Druck eines digitalen Dokumentes (z.B. *.doc., *.ppt, *.xls, *.html, …) anfordert, dann tut der Doc2Fax-Druckertreiber Folgendes:

·         er gibt für jede Seite des zu druckenden Dokuments ein Schwarz-Weiß-Bild im Bitmap-Format (*.bmp) aus, das die grafischen Informationen der Seite enthält (wahlweise auf Wunsch stattdessen auch ein mehrseitiges TIFF-F alias Fax Group 3 oder eine SFF-Datei).

·         er gibt für jede Seite des zu druckenden Dokuments eine txt-Datei aus, die die Text-Informationen der Seite enthält. Dies erlaubt später die Suche nach Schlüsselworten, besonders in umfangreichen Fax-Dokumenten.

·         bei Druck-Ereignissen wie 

o        StartDoc

o        EndPage

o        EndDoc

startet er dasjenige Programm, das Sie als Software-Entwickler in der Konfigurationsdatei Doc2Fax.ini dafür vorgesehen hatten. Je nach Druck-Ereignis stellt der Treiber in den Befehlszeilenargumenten nützliche Informationen zur Verfügung, etwa den Namen der Bitmap- oder txt-Datei, die er gerade ausgegeben hat.

Dieses Programm müssen Sie als Programmierer nach dem Vorbild des mitgelieferten NotifyApp.exe lediglich so schreiben, dass es 2 Befehlszeilenargumente erwartet, nämlich erstens eine Kennziffer für das Druck-Ereignis:

o        bei StartDoc:    dezimal 1280 oder hexadezimal 0x500

o        bei EndPage:    dezimal 1282 oder hexadezimal 0x502

o        bei EndDoc:     dezimal 1284 oder hexadezimal 0x504

und zweitens eine Zeichenkette:

o        bei StartDoc:    den Namen des in Druck befindlichen Dokuments

o        bei EndPage:    den Namen der gerade ausgegebenen Bitmap-Datei, die die grafischen Informationen der entsprechenden Seite des Dokuments enthält

o        bei EndDoc:     den Namen des in Druck befindlichen Dokuments

Typischerweise würden Sie etwa in dem Programm für das Ereignis “EndPage”, das ja den Namen der gerade vom Treiber ausgegebenen bmp-Datei mit den grafischen Informationen der Seite empfängt, diese bmp-Datei öffnen, dann vielleicht das *.bmp in ein *.jpg umwandeln oder anderweitig manipulieren und schließlich z.B. an die ISDN-Karte weiterleiten.

 

 

4. Wie man Doc2Fax API den eigenen Anforderungen anpasst

 

4.1. Installation

4.1.1. Selbstentpackendes WinRAR-Archiv d2fSetupDeu.exe

Wie man das selbstentpackende WinRAR-Archiv d2fSetupDeu.exe anpasst: Vorausgesetzt, WinRAR ( http://www.rarlab.com/download.htm ) ist auf Ihrem Rechner installiert, klicken Sie bitte mit der rechten Maustaste auf d2fSetupDeu.exe und wählen die Kontext-Menü-Option “Öffnen mit WinRAR”.

 

4.1.1.1. Lieferumfang

Doc2Fax API besteht aus folgenden Dateien:


Der Doc2Fax-Druckertreiber besteht aus den Dateien

·         d2fddi.dll (Device Driver Interface = Gerätetreiber-Schnittstelle)

·         d2fui.dll (User Interface = Benutzer-Schnittstelle)

·         Doc2Fax.ini (Konfigurationsdatei für Druckertreiber, aber auch für Installations- und Deinstallationsprogramm)

·         RASDDUI.HLP (allgemeine Hilfe-Datei für Raster-Druckertreiber)

Im Lieferumfang von Doc2Fax API sind keine Quelltexte für seinen Druckertreiber enthalten.

Das Doc2Fax-Installationsprogramm besteht aus den Dateien

·         Setup.exe (Installationsprogramm)

·         Logo.bmp (Firmenlogo für das Hauptfenster des Installationsprogramms)

·         Doc2Fax API\Readme.html (LiesMich-Datei)

Das Doc2Fax-Deinstallationsprogramm besteht aus der Datei

·         Doc2Fax API \Uninstall.exe (Deinstallationsprogramm)

Der Name des Unterverzeichnisses (hier z.B. „Doc2Fax API“) im Archiv d2fSetupDeu.exe muss mit dem Druckernamen in der Konfigurationsdatei Doc2Fax.ini (vergl. Kapitel „4.3.1. Druckername“) übereinstimmen.

 

4.1.1.2. Selbstentpackendes Archiv

Innerhalb WinRARs klicken Sie bitte auf “SFX”, dann den Knopf “Erweiterte SFX-Optionen”:

 

 

4.1.1.3. Registerkarte „Allgemein”

Setzen Sie unter „Vorgegebenes Zielverzeichnis“ das Entpack-Unterverzeichnis im Programmverzeichnis (meist „C:\Programme“; s. Radiobutton „Unter „Programme“ erzeugen“ in obiger Abbildung). Der Name dieses Entpack-Unterverzeichnisses muss mit dem Herstellernamen in der Konfigurationsdatei Doc2Fax.ini (vergl. Kapitel „4.3.3. Herstellername“) übereinstimmen.   

Setzen Sie unter „Aufruf nach dem Entpacken“ das Installationsprogramm, das nach dem Entpacken automatisch gestartet werden soll, in diesem Fall üblicherweise das mitgelieferte Installationsprogramm Setup.exe.

 

4.1.1.4. Registerkarte „Lizenz”

Setzen Sie den Text der Lizenzbestimmungen und den zugehörigen Fenstertitel.

 

4.1.1.5. Registerkarte “Text und Symbol”

Setzen Sie einen beliebigen Erläuterungstext und den zugehörigen Fenstertitel.

 

 

4.2. Sprachabhängige Zeichenketten in Treiber und Installationsprogramm

Derzeit liegt Doc2Fax API in deutscher und englischer Sprache vor. Wenn Sie den Doc2Fax-Druckertreiber, sein Installationsprogramm Setup.exe und sein Deinstallationsprogramm Uninstall.exe in einer anderen Sprache benötigen sollten - und selbst dieser Sprache mächtig sind - dann wenden Sie sich bitte einfach an info@driverlab.de.

 

4.3. Konfigurationsdatei Doc2Fax.ini

Die Initialisierungsdatei Doc2Fax.ini muss im Pfad

[Systemverzeichnis]\system32\spool\drivers\w32x86\3

stehen. Setup.exe kopiert sie bei der Installation automatisch in diesen Pfad, und danach darf sie auch nicht wieder von dort verlegt werden.

Ändern Sie keinesfalls die Struktur oder den Namen der Initialisierungsdatei, weil der Druckertreiber, dessen Quelltext Ihnen nicht zugänglich ist, aus Doc2Fax.ini liest.

Ändern Sie nicht die Sektionsüberschriften und Variablenbezeichner. Sie dürfen alle Werte in der Initialisierungsdatei ändern, außer die der Sektion [Paper1], weil diese das Vorgabe-Papierformat des Druckertreibers darstellt:

[Paper1] 
PaperName ="A4" 
ShortEdgeLength =2100 
LongEdgeLength =2970 
ImageableAreaShortEdgeLength =2100 
ImageableAreaLongEdgeLength =2970 

 

4.3.1. Druckername

Ändern Sie den Wert

DeviceName=Doc2Fax API,

um den Druckernamen Ihrer Wahl festzulegen.

Diesen Wert müssen Sie vor der Installation durch Setup.exe setzen, also in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe, und nicht etwa erst nach der Installation in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini, denn dann hätte Setup.exe den Drucker bereits unter dem vorherigen, anderen Namen ins Betriebssystem eingetragen.

Dieser Druckername muss mit dem Namen des Unterverzeichnisses im Archiv d2fSetupDeu.exe aus Kapitel „4.1.1.1. Lieferumfang“ übereinstimmen.

 

4.3.2. Treibername

Ändern Sie den Wert

DriverName=Doc2Fax API Driver,

um den Treibernamen Ihrer Wahl festzulegen.

Diesen Wert müssen Sie vor der Installation durch Setup.exe setzen, also in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe, und nicht etwa erst nach der Installation in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini, denn dann hätte Setup.exe den Treiber bereits unter dem vorherigen, anderen Namen ins Betriebssystem eingetragen.

 

4.3.3. Herstellername

Ändern Sie den Wert

Manufacturer=DriverLab,

um den Hersteller Ihrer Wahl festzulegen.

Diesen Wert müssen Sie vor der Installation durch Setup.exe setzen, also in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe, und nicht etwa erst nach der Installation in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini, denn dann hätte Setup.exe bereits den vorherigen, anderen Hersteller ins Betriebssystem eingetragen.

Dieser Herstellername muss mit dem Namen des Entpack-Unterverzeichnisses aus Kapitel „4.1.1.3. Registerkarte „Allgemein”“ übereinstimmen.

 

4.3.4. Auflösung

Ändern Sie den Wert

FaxResolution=209,

um die Auflösung Ihrer Wahl festzulegen.

Diesen Wert sollten Sie vor der Installation durch Setup.exe setzen, also in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe, und nicht etwa erst nach der Installation in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini, denn dann hätte Setup.exe bereits die vorherige, andere Auflösung ins Betriebssystem eingetragen. Nachträgliche Änderungen der Auflösung in [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini sind aber dennoch jederzeit möglich, da sie nicht zu Inkonsistenzen führen.

 

4.3.5. Ausgabepfad

Ändern Sie den Wert

OutputPath=C:\Documents and Settings\All Users\Documents\,

um den Ausgabepfad Ihrer Wahl festzulegen.

Achtung: Dieser Wert wird selbstverständlich erst während der Installation durch Setup.exe in die Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini eingetragen, da er ja von Betriebssystem, Landessprache und Verzeichnis-System des jeweiligen Rechners abhängt. Es hätte also keinen Sinn, diesen Wert vor der Installation in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe zu setzen, weil er in diesem Fall sowieso wieder (in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini) überschrieben würde. Stattdessen müssen Sie ihn, falls dies tatsächlich einmal nötig sein sollte, nach der Installation entweder programmatisch oder per Hand verändern.

 

4.3.6. Programme, die bei bestimmten Druck-Ereignissen gestartet werden sollen

Ändern Sie die Werte

StartDoc=C:\WINDOWS\System32\spool\DRIVERS\W32X86\3\NotifyApp.exe

SendPage=C:\WINDOWS\System32\spool\DRIVERS\W32X86\3\NotifyApp.exe

EndDoc  =C:\WINDOWS\System32\spool\DRIVERS\W32X86\3\NotifyApp.exe

um festzulegen, welche Programme bei welchen Druck-Ereignissen gestartet werden sollen.

Achtung: Diese Werte werden selbstverständlich erst während der Installation durch Setup.exe in die Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini eingetragen, da sie ja von Betriebssystem, Landessprache und Verzeichnis-System des jeweiligen Rechners abhängen. Es hätte also keinen Sinn, diese Werte vor der Installation in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe zu setzen, weil sie in diesem Fall sowieso wieder (in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini) überschrieben würden. Stattdessen müssen Sie sie, falls dies tatsächlich einmal nötig sein sollte, nach der Installation entweder programmatisch oder per Hand verändern.

 

4.3.7. Papierformate

Sie können neue Papierformate ([paperX] sections) hinzufügen oder Bestehende ändern, außer [Paper1]. Beim Hinzufügen neuer Papierformate dürfen Sie keine Sektionsnummern überspringen  - die Sektionsnummern müssen in ununterbrochener Reihenfolge fortlaufen.

Diese Werte für die Papierformate sollten Sie vor der Installation durch Setup.exe setzen, also in der Datei Doc2Fax.ini im Archiv d2fSetupDeu.exe, und nicht etwa erst nach der Installation in der Datei [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini, denn dann hätte Setup.exe bereits die vorherige, andere Liste der Papierformate ins Betriebssystem eingetragen. Nachträgliche Änderungen an der Liste der Papierformate in [Systemverzeichnis]\system32\spool\drivers\w32x86\3\Doc2Fax.ini sind aber dennoch jederzeit möglich, da sie nicht zu Inkonsistenzen führen.