This section describes the messages sent by the Black Ice printer drivers. The printer driver will send messages when the following events happen during the printing process:
· Change Devmode
· Start of Document
· Start of Page
· Text Output passed in Memory
· OCR Data passed in Memory
· Image passed in Memory
· End of Page
· End of Document
· Print Job Aborted
· Message Capture Error
For a single print job, the order of the messages is the following:
1. Change Devmode
2. Start of Document
3. OCR Data passed in Memory (if “Generate OCR data in memory” is enabled and hOCR format is selected)|
4. Change Devmode
5. Start of Page
6. Text output passed in Memory (If the “Generate Text Output in memory” option is enabled)
7. OCR Data passed in Memory (If the “Generate OCR data in memory” option is enabled)
8. Image passed in Memory (If the “Generate Image in memory” and “Save each page as separate file” options are enabled)
9. End of Page
The Change Devmode, Start of Page,OCR Data, Image, End of Page events are repeated for each page in the document.
10.OCR Data passed in Memory (if “Generate OCR data in memory” is enabled and hOCR format is selected)|
11.Image passed in Memory (If the “Generate Image in memory” option is enabled and “Save each page as separate file” option is disabled)
12.End of Document
The following events can happen any time during printing:
o Print Job Aborted
o Message Capture Error
Handling the Messages
The messages sent by the Printer Driver can be handled by using the Message Capture Library (BLICECTR.DLL), or the Message Capture ActiveX control (BiPrnDrv.ocx). Using the BLICECTR.DLL is recommended for C++ applications and using BiPrnDrv.ocx is recommended for .NET applications.
http://www.blackice.com/private/rtk/The_Message_Capture_Library_Reference.htm
http://www.blackice.com/private/rtk/The_Message_Capture_ActiveX_Reference.htm
Description of the Messages
Change Devmode
Message Capture ActiveX event name: ChangeDevmode/ChangeDevmodeEx
Message Capture Library message ID: BLACKICE_MESSAGE_DEVMODE
The Black Ice printer driver sends the Change Devmode message to the application before the Start of Document message and before each Start of Page message.
The application can modify the printer driver Extended devmode structure to configure the printer driver. The Application can NOT modify certain members of the printer driver DEVMODE structure such as Resolution (DPI), Orientation and Paper Size. If the application wants to change a member of the DEVMODE structure, the application should change that member at every Change Devmode message, because the application receives a different instance of the DEVMODE structure every time and different members of the DEVMODE structure are read by the driver at different stages of the printing process.
Start of Document
Message Capture ActiveX event name: StartDoc/StartDocEx
Message Capture Library message ID: BLACKICE_MESSAGE_STARTDOC
The driver sends this message when it starts to print a new document.
Start of Page
Message Capture ActiveX event name: StartPage/StartPageEx
Message Capture Library message ID: BLACKICE_MESSAGE_STARTPAGE
The driver sends this message at the beginning of each new page.
Text Output passed in Memory
Message Capture ActiveX event name: TextData
Message Capture Library message ID: BLACKICE_MESSAGE_TEXT
The Text Output message is available since Printer Driver version 14.99.
The printer driver transfers the Text Output data through this message if the “Generate Text output in memory” option is enabled. The Text Output is generated for each printed page separately.
OCR Data passed in Memory
Message Capture ActiveX event name: OCRData
Message Capture Library message ID: BLACKICE_MESSAGE_OCR
The OCR data message is available since Printer Driver version 14.98.
The printer driver transfers the OCR data through this message if the “Generate OCR output in memory” option is enabled. The OCR data is generated for each printed page separately.
Image passed in Memory
Message Capture ActiveX event name: MemoryImage/MemoryImageEx
Message Capture Library message ID: BLACKICE_MESSAGE_MEMIMAGE
The printer driver transfers the image data through this message, if the “Generate Output in Memory” option is turned on in the printer driver.
End of Page
Message Capture ActiveX event name: EndPage/EndPageEx
Message Capture Library message ID: BLACKICE_MESSAGE_ENDPAGE
The driver sends this message when it is finished printing a page.
End of Document
Message Capture ActiveX event name: EndDoc/EndDocEx
Message Capture Library message ID: BLACKICE_MESSAGE_ENDDOC
The driver sends this message when it finishes printing a document. This event is not sent if the print job is aborted.
Print Job Aborted
Message Capture ActiveX event name: Abort/AbortEx
Message Capture Library message ID: BLACKICE_MESSAGE_ABORT
The driver sends this message when an error occurs or the user cancels the document printing.
Message Capture Error
Message Capture ActiveX event name: Error
Message Capture Library message ID: BLACKICE_MESSAGE_ERROR
The Message Capture Dll sends this message when error happens during the communication with the printer.
Notes for Using the Message Capture Interface
For more information about how to use the Messaging Interface and how to change values of the DEVMODE Structure, please see the Message Capture C++, C#, VB.NET or Delphi sample and the Sample for Changing the Output Directory C++, C#, VB.NET samples.
If the application is started by the Printer Driver’s “Start Application Before Printing” feature, it is started at the Start of Document (StarDoc / StartDocEx / BLACKICE_MESSAGE_STARTDOC) event and the printer driver will not wait for the application. This means the application will not receive the first Change Devmode (ChangeDevmode / ChangeDevmodeEx / BLACKICE_MESSAGE_DEVMODE) message, and depending on how fast it starts and how fast the printing progresses, it might not receive any messages at all.
Therefore if one wants to use the Messaging Interface from an application started by the printer driver, the application must be started using the “Start for Messaging” option or must run in the background and wait for the events continuously instead of being started by the Printer Driver. Another option is to use the plugin interface (BiPlugin.dll) instead of the Messaging Interface. (Especially when changing settings like file type and output directory or filename, which must be set at the first time the Change Devmode event fires)
To make the Printer Driver wait for the application at every event or to abort the printing process, the plugin interface must be used.
The Save As dialog pops up before the message capture application gets the Change Devmode message, therefore the Save As dialog can’t be enabled or disabled in the handler of the Change Devmode messages.
To disable the Save As dialog when the message capture application is running, the DisableSaveAsOption function of the BlackIceDEVMODE DLL or OCX control should be called when the application starts and the EnableSaveAsOption function should be called when the application closes. In this case when the application is running the Save As dialog won’t pop up at printings.