API for writing a Plug-in for the printer driver
The Black Ice printer drivers include “Plug-In” support which is accessed through a dynamic linked library (DLL). The printer driver calls pre-defined functions from the Plug-in at each phase of printing. Developers have full access to the DLL and can insert their own custom code to each DLL function to perform a variety of tasks as required by their application.
Some common usages are:
· Suspend printing for user to set password on PDF documents.
· Suspend printing for user to interface with the Web.
· Suspend printing for user to manually index document.
· Runtime interface with database application without user interaction.
· Set output directory or file format at Runtime without user interaction.
How It Works
The Black Ice printer driver will load the Plug-In model “BiPlugin.dll” with each print job and will pass to each DLL function a pointer to the DEVMODE of the current print job. When the print job starts, at the “Start Document” phase, the Plug-In DLL function BiStartDoc get called. In the BiStartDoc function one can modify the printer driver settings though the printer driver Extended DEVMODE. During the call to the BiStartDoc function, the printer driver suspends printing and wait for the BiStartDoc function to return. While the printing is suspended a user module can be called from the BiPlugin.dll for user interaction. For example, to enter password for a PDF document, Index printed document, or pass custom data through the printer driver.
Functions Called by the Printer Driver:
The Plug-in DLL functions must return TRUE on success or FALSE on any failure. If any of the custom functions return FALSE, the Black Ice Printer driver will abort the current print job.
The driver passes the extended DEVMODE structure to every function call. Use the functions of the BlackIceDEVMODE.dll to change the settings. Please note the limitations mentioned below.
BiStartDoc: Called at the beginning of the printing process, return false to abort the process. You can return custom data to the printer driver using pCustomData and pdwCustomDataSize. The driver will pass the data to the other functions.
BOOL __stdcall BiStartDoc (BlackIceDEVMODE* pDevmode, void** pCustomData,
unsigned long *pdwCustomDataSize);
BiStartPage: Called at the beginning of each page.
BOOL __stdcall BiStartPage (BlackIceDEVMODE* pDevmode, void* pCustomData);
BiEndPage: Called at the end of each page.
BOOL __stdcall BiEndPage (BlackIceDEVMODE* pDevmode, void* pCustomData,
unsigned long dwPageNumber);
BiEndDoc: Called at the end of the printing job.
BOOL __stdcall BiEndDoc (BlackIceDEVMODE* pDevmode, void* pCustomData,
char* pszGroupFile);
BiAbort: Called if you abort the printing process.
BOOL __stdcall BiAbort (BlackIceDEVMODE* pDevmode, void* pCustomData);
Limitations:
The Standard DEVMODE data structure cannot be changed in the Plug-in DLL such as page resolution, orientation, and page size. Any change to the Standard DEVMODE data structure may cause spooler or printer driver exception.
The BiStartDoc function receives a different instance of the extended DEVMODE structure than BiStartPage. Any changes made to the extended DEVMODE structure in the BiStartDoc function, the same changes need to reapply, in the BiStartPage function, for the extended DEVMODE structure.
Sample Applications: