The BLICECTR.DLL exports a set of functions which can help developers capture printer driver pipe messages. The DLL captures pipe messages sent by the printer driver and converts them into window messages. This way the developer does not have to write his own pipe handling code (which can be very tricky and time consuming).
The name of the pipe should be specified in the InterfaceName member of the BlackIceDEVMODE structure. The pipe name in the InterfaceName member should not contain the \\.\pipe\ prefix, the printer driver will insert this prefix when it tries to write the named pipe.
The application should create a window and register a window message. Afterwards, the application should start waiting for printer driver messages by calling the WaitForPrnPipeWithPriority function from the BLICECTR.DLL.
NOTE: On Terminal Server Systems the printer driver will add the Messaging Interface ID.
When a document is being printed on the printer, the BLICECTR.DLL will capture the pipe messages sent by the printer, convert the pipe messages into window messages and forward them to the application. The parameter of each message will be a TSPrnMessage structure:
typedef struct tagTSPrnMessage
{
DWORD dwMessage;
WCHAR szDocName[MAX_PATH];
WCHAR szFileName[MAX_PATH]; // Obsolete, use
// szOutputFileName or szGroupFileName instead.
WCHAR szPrinterName[MAX_PATH];
INT nPageNumber;
BOOL fAppendPage;
BOOL fPortrait;
// The following fields are available
// since Printer Driver version 14.98:
DWORD dwJobID; // The Windows Job ID of the Print Job
WCHAR szOutputFileName[MAX_PATH];
WCHAR szGroupFileName[MAX_PATH];
DWORD dwOCRDataFormat;
To stop waiting for messages, the application should call the EndWaitPrnPipe function from the BLICECTR.DLL.
Description of the Members of the TSPrnMessage Structure
DWORD dwMessage;
The type of the received message.
The possible dwMessage values are the following: (defined in devmode.h)
#define BLACKICE_MESSAGE_STARTDOC 0x00000001
#define BLACKICE_MESSAGE_STARTPAGE 0x00000002
#define BLACKICE_MESSAGE_ENDPAGE 0x00000003
#define BLACKICE_MESSAGE_ENDDOC 0x00000004
#define BLACKICE_MESSAGE_ABORT 0x00000005
#define BLACKICE_MESSAGE_ERROR 0x00000006
#define BLACKICE_MESSAGE_DEVMODE 0x00000007
#define BLACKICE_MESSAGE_MEMIMAGE 0x00000008
#define BLACKICE_MESSAGE_OCR 0x00000009
#define BLACKICE_MESSAGE_TEXT 0x0000000A
The BLACKICE_MESSAGE_OCR message is available in Printer Driver version 14.98 and newer.
The BLACKICE_MESSAGE_TEXT message is available in Printer Driver version 14.99 and newer.
For the description of each message, please see the following page in the manual:
Description of the Black Ice Printer Messages
Notes: The events are not declared in the sequence it should be processed.
WCHAR szDocName[MAX_PATH];
Contains the document name. The document name is the name of the print job, specified by the printing application and it is not the same as the input or the output filenames.
For printer drivers 14.97 and earlier, the szDocName value is not available for the BLACKICE_MESSAGE_MEMIMAGE and BLACKICE_MESSAGE_ERROR messages. For printer drivers 14.98 and newer the szDocName value is available for all messages, except the BLACKICE_MESSAGE_ERROR message.
WCHAR szFileName[MAX_PATH];
This member of the of the structure is for compatibility with older version of the printer driver. Since Printer Driver version 14.98, use the szOutputFileName or szGroupFileName members instead.
For the BLACKICE_MESSAGE_STARTDOC and BLACKICE_MESSAGE_ENDDOC messages, it contains the name of the Group File.
For the BLACKICE_MESSAGE_STARTPAGE and BLACKICE_MESSAGE_ENDPAGE messages, it contains the name of the output file.
WCHAR szPrinterName[MAX_PATH];
Contains the name of the printer that sent the message.
For printer drivers 14.97 and earlier, the szPrinterName value is available for the BLACKICE_MESSAGE_STARTDOC, BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE, BLACKICE_MESSAGE_ENDDOC and BLACKICE_MESSAGE_ABORT messages.
For printer drivers 14.98 and newer, the szPrinterName value is available for all messages, except the BLACKICE_MESSAGE_ERROR message.
INT nPageNumber;
Contains the current page number.
The nPageNumber value is available for the BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE, BLACKICE_MESSAGE_ENDDOC, BLACKICE_MESSAGE_ABORT and BLACKICE_MESSAGE_OCR messages.
BOOL fAppendPage;
TRUE, if the printer driver is set to write a multi-page TIFF or PDF output file, FALSE otherwise.
The fAppendPage value is available for the BLACKICE_MESSAGE_STARTDOC, BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE, BLACKICE_MESSAGE_ENDDOC and BLACKICE_MESSAGE_ABORT messages.
BOOL fPortrait;
TRUE, if the printer driver is printing a portrait document, FALSE otherwise.
The fPortrait value is available for the BLACKICE_MESSAGE_STARTDOC, BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE, BLACKICE_MESSAGE_ENDDOC and BLACKICE_MESSAGE_ABORT messages.
DWORD dwJobID;
Contains the Windows Job ID of the Print Job.
Available for printer drivers 14.98 and newer, for all messages except the BLACKICE_MESSAGE_ERROR message.
WCHAR szOutputFileName[MAX_PATH];
Contains the output path and filename of the printed document.
Available for printer drivers 14.98 and newer, for the BLACKICE_MESSAGE_STARTDOC, BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE and BLACKICE_MESSAGE_ENDDOC messages.
WCHAR szGroupFileName[MAX_PATH];
Contains the path and filename of the Group File (*.grp), if the Group File generation is enabled in the printer.
Available for printer drivers 14.98 and newer, for the BLACKICE_MESSAGE_STARTDOC, BLACKICE_MESSAGE_STARTPAGE, BLACKICE_MESSAGE_ENDPAGE and BLACKICE_MESSAGE_ENDDOC messages.
DWORD dwOCRDataFormat;
Contains the type of the OCR data. It can be one of the following values:
BI_OCR_MEM_FORMAT_TEXT (1): Plain Text format
BI_OCR_MEM_FORMAT_HOCR_HEADER (2): Header of the hOCR data
BI_OCR_MEM_FORMAT_HOCR_PAGE (3): hOCR data for the page
BI_OCR_MEM_FORMAT_HOCR_FOOTER (4): Ending part of the hOCR data
The Black Ice Printer Drivers support Plain Text and hOCR output formats for the OCR.
If the Plain Text output format is selected, the printer driver will send a BLACKICE_MESSAGE_OCR message after each BLACKICE_MESSAGE_STARTPAGE message, containing the OCR text (BI_OCR_MEM_FORMAT_TEXT) for the page.
If the hOCR output format is selected, the printer driver will send a BLACKICE_MESSAGE_OCR message before the first BLACKICE_MESSAGE_STARTPAGE message, containing the header part of the hOCR data (BI_OCR_MEM_FORMAT_HOCR_HEADER).
Then the driver will send a BLACKICE_MESSAGE_OCR message after each BLACKICE_MESSAGE_STARTPAGE message, containing the hOCR data for the page (BI_OCR_MEM_FORMAT_HOCR_PAGE).
Finally, the driver will send a BLACKICE_MESSAGE_OCR message after the last BLACKICE_MESSAGE_ENDPAGE message, containing the footer part of the hOCR data (BI_OCR_MEM_FORMAT_HOCR_FOOTER).
Available for printer drivers 14.98 and newer, for the BLACKICE_MESSAGE_OCR message.
The BLICECTR.DLL exports the following four functions: