[Please of course replace this placeholder document by your own user manual before shipping it to your clients.]

 

Doc2Fax API 9x

 

1. The Direct Fax Problem and its solution

 

Obviously it is quite complicated and inelegant to first print a digital document and then to have the fax device re-digitalize the printed paper again before finally sending it to the addressee.

 

Hardware components like Fritz Card, ISDN Card and such overcome this problem by virtually establishing a short circuit between computer and telephone line – and along with them a huge market for Fax Software arised, which drives these hardware components in order to send data through them.

 

Now if you as a programmer intend to offer your clients a tailor-made Fax Software, by which the end user can print his digital documents – for example think of an MS Word *.doc - without fax device, virtually directly into the telephone line, then you encounter two basic problems:

 

 

 

 

The only solution:

 

A printer driver, which writes the graphical data and the text of the digital document destined to be printed, or faxed, respectively, into files, and notifies your software about all print processes, print events and filenames, so that your software can react to it – and all that is done by Doc2Fax printer driver.



2. Scheme for mode of operation

Doc2Fax API 9x is suitable for Windows 95, 98 and Windows ME. It consists of two parts: The printer driver and the host application.

 

2.1. The printer driver

The Doc2Fax printer driver consists of files

·         d2f.drv (Driver)

·         unidrv.dll (common universal printer driver interface)

·         iconlib.dll (supplement library)

Doc2Fax API 9x´s scope of supply does not include source code for its printer driver.

When user requests a digital document (for example *.doc., *.ppt, *.xls, *.html, …) to be printed, the Doc2Fax printer driver

·         puts out one black-and-white-image in bitmap format (*.bmp) containing the graphic information for each page of the document to be printed

·         puts out one txt-file containing the text information for each page of the document to be printed (Character set: “Windows Western”). This later on allows keyword search, especially in large Fax documents.

·         on print events like 

o        StartDoc

o        EndDoc

o        StartPage

o        EndPage

o        Abort

sends Windows Messages to the window of host application d2f.exe using API function SendMessage(). Depending on the type of message, the driver provides useful information in SendMessage()´s parameters WParam and LParam, like for example a pointer to the name of the bitmap-file or txt-file it just recently put out.

 

2.2. The host application

The host application d2f.exe is delivered along with its source code in folders

·         “d2fInvisible” for invisible host application window,

·         or “d2fVisible” respectively, for visible host application window.


The host application receives the Windows Messages sent by the printer driver and provides event handler functions for these events.

Typically for example in the event handler function of event “EndPage”, which also receives the name of the bmp-file containing the graphic information of the page just recently put out by the driver, you would open this bmp-file, then eventually convert the *.bmp to a *.jpg or manipulate the image in any other way and then forward it for example to the ISDN card.

 

3. How to customize the delivered source code for your individual purpose

 

Demo version users please ask for source code at info@driverlab.de. You´re welcome!


3.1. Installation

3.1.1. Self-extracting WinRAR archive d2fSetupEngl.exe

How to customize the self-extracting WinRAR archive d2fSetupEngl.exe: Provided that WinRAR ( http://www.rarlab.com/download.htm ) is installed on your computer, right-click on d2fSetupEngl.exe and select context menu option “Open with WinRAR”. Within WinRAR please click “SFX”, then button “Advanced SFX options”:

 

 

3.1.1.1. Tab control “General”

Set extract path and the setup program, which to start after extraction.

 

3.1.1.2. Tab control “License”

Set License agreement text and corresponding window caption.

 

3.1.1.3. Tab control “Text and icon”

Set an arbitrary explanation text.

 

 

3.1.2. Project “Setup” (d2fSetup.dsw)

Setup.exe

·         installs files

o        d2f.drv (driver)

o        unidrv.dll (common universal printer driver interface)

o        iconlib.dll (supplement library)

o        unidrv.hlp (help file for common universal printer driver interface)

o        d2f.exe (Host application monitoring the printer driver)

o        Doc2Fax.ini (initialization file)

to [system directory]\system, and Doc2Fax.ini to [system directory]

·         registers host application d2f.exe in Windows registry´s run-key at

HKEY_LOCAL_MACHINE / SOFTWARE / Microsoft / Windows / CurrentVersion / run,

so that the operating system will automatically start d2f.exe every time after rebooting 

·         starts d2f.exe for the first time

·         deletes temporary files after installation 

·         displays user manual ReadMe.html


In case you would like to use a different name for host application, simply modify code line

DrvDef.h:           #define HOST_FILE_NAME "d2f.exe"

In case you would like to use a different Port for the driver, simply modify code line

DrvDef.h:           #define PORT_NAME "d2f"

and the corresponding entry in the file drvlbmon.ini, which is contained in the self-extracting archive d2fSetupEngl.exe.

Please read comments in SetupDlg.cpp: Setup.exe runs in Release version only, not in Debug version. In case debugging should ever be necessary, please use function

bool NotifyDlg( LPTSTR strWhere )

for this purpose instead.


Installing once more by Setup.exe requires a previous uninstallation by Uninstal.exe and rebooting the computer.

 

3.1.3. Project “Uninstall”

Provides inverse functions to Setup.exe.

 

3.2. Projects “d2fVisible” and “d2fInvisible”

The scope of supply of “Doc2Fax API” kit includes two different versions of host applications d2f.exe monitoring the printer driver. Please choose the one which fits your purpose: 

·         d2fVisible with visible host application window  

·         d2fInvisible with invisible host application window (showing MessageBoxes in order to trace the temporal sequence of print events in Debug version).

 

3.2.1. Print events and corresponding messages 

The messages processed by d2f.exe are defined in DrvDef.h: 

#define PRINT_EVENT_STARTDOC       WM_USER+0x100 
#define PRINT_EVENT_ENDDOC          WM_USER+0x101 
#define PRINT_EVENT_STARTPAGE     WM_USER+0x102 
#define PRINT_EVENT_ENDPAGE        WM_USER+0x103
#define PRINT_EVENT_ABORT             WM_USER+0x104 
#define MSG_CLOSE_APP                   WM_USER+0x199 

Please write your own code handling print events

·         if d2fInvisible: in MainWnd.cpp, function OnMsg()

·         if d2fVisible: in

o        D2fSpyDlg.cpp, functions CD2fSpyDlg::OnPRINT_EVENT_XYZ(),

and / or

o        D2fSpyWnd.CPP, CD2fSpyWnd::OnPRINT_EVENT_XYZ()

 

3.3. Names and strings

Most of the names and strings are defined as string constants in DrvDef.h. For example you can change the name of the device / driver:

#define DRIVER_NAME

After changing a string constant like DRIVER_NAME, please make sure to re-build all executables effected by this modification, in this example Setup.exe and Uninstal.exe.

 

3.3.1. Strings, which depend on used language

In file

...\Global\Language.h

there are code lines

//#define LANGUAGE_GERMAN 
#define LANGUAGE_ENGLISH 

Just comment out the definition(s) for the undesired language(s), and keep the definition for the language of your choice.

 

3.4. Initialization file Doc2Fax.ini

Initialization file Doc2Fax.ini must be located in system folder C:\Windows. Setup.exe puts it in this path automatically, and it must not be moved from there ever after.

Do not change structure or name of the initialization file, because the printer driver, for which you don´t have the source code, also reads from Doc2Fax.ini. Do not change value

…\Global\DrvDef.h: #define INI_FILE_NAME    _T("Doc2Fax.ini") 

Do not change section captions and variable specifiers. Never modify the values in Doc2Fax.ini directly, but by configuration tool D2fConfig.exe only.

 

3.5. Configuration tool D2fConfig.exe

This tool allows you to customize the settings of driver d2f.drv and initialization file Doc2Fax.ini for your individual requirements. It expects to find these two files in its own directory. D2fConfig.exe serves the programmer only, and is not supposed to be delivered to the end-user.

 

Generally D2fConfig prohibits

·         strings longer than 31 characters, except for „Output Path“

·         numerical values greater than 65535 (0xFFFF)

·         dots („.“) in form names

·         more than 4 output forms


D2fConfig does not write modifications to files d2f.drv und Doc2Fax.ini unless you click button „Write to file“. If you want to cancel the modifications you made, and read the values from the files once more, then please click „Read file again“.

Generally, if you want to modify settings, you have to do as follows:

1.       Copy C:\Windows\Doc2Fax.ini and C:\Windows\System\d2f.drv to D2fConfig.exe´s directory.

2.       Apply the desired customizations by D2fConfig. Do not forget to click „Write to file“ in the end.

3.       Uninstall the driver by Uninstal.exe.

4.       Reboot your computer.

5.       Integrate the new, modified files d2f.drv and Doc2Fax.ini in your installation program.

6.       Re-install once more with this new, modified installation program.


3.5.1. Driver name

Type the desired name into entry field „Driver name”, and change

DrvDef.h:           #define DRIVER_NAME             "Doc2Fax API"

according to this.

 

3.5.2. Resolution

Type the desired resolution into entry field „Resolution (dpi)”, then click button „Recalc pixel dimensions“ in order to adapt the dimensions of the output images – measured in pixels – to the new resolution.

Example: An A4 page of 210 mm x 297 mm on 200 dpi has a width of

             210 mm / 25,4 mm/Inch * 200 dots/Inch = 1654 dots

or pixels; on 300 dpi on the other hand it has

             210 mm / 25,4 mm/Inch * 300 dots/Inch = 2480 dots.

 

3.6. “Hands off” – what NOT to customize

Some of the definitions in DrvDef.h are shared by those executables, for which you have the source code (d2f.exe, Setup.exe, Uninstal.exe), and those, for which you do not have the source code (d2f.drv, unidrv.dll). That´s why these definitions must never be modified, in particular not:

#define PRINT_EVENT_STARTDOC       WM_USER+0x100
#define PRINT_EVENT_ENDDOC          WM_USER+0x101
#define PRINT_EVENT_STARTPAGE     WM_USER+0x102
#define PRINT_EVENT_ENDPAGE        WM_USER+0x103
#define PRINT_EVENT_ABORT             WM_USER+0x104
#define MSG_CLOSE_APP                   WM_USER+0x199
#define PS_FORM_FAX                        _T("A4")
#define DEFAULT_OUTPUT_PATH        _T("c:\\")
#define DEFAULT_HOST_WND_NAME _T("d2f")  
#define INI_FILE_NAME                        _T("Doc2Fax.ini")
#define INI_SECTION                            _T("Setup")
#define INI_RESOLUTION_KEY             "FaxResolution"
#define INI_OUTPUTPATH                     _T("OutputPath")
#define INI_HOSTWNDNAME                _T("HostWndName")
#define PORT_INI_FILENAME                "drvlbmon.ini"