INT DrvDocumentEvent(
| HANDLE hPrinter, | |
| HDC hdc, | |
| int iEsc, | |
| ULONG cbIn, | |
| PULONG pbIn, | |
| ULONG cbOut, | |
| PULONG pbOut | |
| ); |
DrvDocumentEvent allows the printer driver UI to hook certain printer management calls.
Parameters
hPrinter
Handle that identifies the printer.
hdc
Handle to the device context
iEsc
Specifies the escape code that identifies the event to be handled. The escape code is packed in the LOWORD of iEsc, and the HIWORD contains zero. This parameter can be one of the following values:
| Escape | Definition |
| DOCUMENTEVENT_CREATEDCPRE | User-mode GDI is calling DrvDocumentEvent before sending an application’s CreateDC call to kernel-mode GDI for processing. pbIn points to an array of four ULONGs that are 0, pointer to the printer name, pointer to the input DEVMODE, and a Boolean value that specifies whether the call was CreateIC (TRUE) or CreateDC (FALSE). The driver should return a pointer to the output DEVMODE in pbOut. |
| DOCUMENTEVENT_CREATEDCPOST | User-mode GDI is calling DrvDocumentEvent after kernel-mode GDI has processed an application’s CreateDC call. pbIn points to the DEVMODE structure returned by a previous call to DrvDocumentEvent with an iEsc of DOCUMENTEVENT_CREATEDCPRE. pbOut is not used. |
| DOCUMENTEVENT_RESETDCPRE | User-mode GDI is calling DrvDocumentEvent before sending an application’s ResetDC call to kernel-mode GDI for processing. pbIn points to an input DEVMODE. The driver should return a pointer to the output DEVMODE in pbOut. |
| DOCUMENTEVENT_RESETDCPOST | User-mode GDI is calling DrvDocumentEvent after kernel-mode GDI has processed an application’s ResetDC call. pbIn points to the DEVMODE structure returned by a previous call to DrvDocumentEvent with an iEsc of DOCUMENTEVENT_RESETDCPRE. pbOut is not used. |
| DOCUMENTEVENT_STARTDOCPRE DOCUMENTEVENT_STARTDOC |
User-mode GDI is calling DrvDocumentEvent before sending an application’s StartDoc call to kernel-mode GDI for processing. pbIn points to an input DOCINFO structure. pbOut is not used. |
| DOCUMENTEVENT_STARTDOCPOST | User-mode GDI is calling DrvDocumentEvent after kernel-mode GDI has processed an application’s StartDoc call. pbIn points to a ULONG that specifies the ID of the current print job. pbOut is not used. |
| DOCUMENTEVENT_STARTPAGE | User-mode GDI is calling DrvDocumentEvent before sending an application’s StartPage call to kernel-mode GDI for processing. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_ENDPAGE | User-mode GDI is calling DrvDocumentEvent before sending an application’s EndPage call to kernel-mode GDI for processing. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_ENDDOCPRE DOCUMENTEVENT_ENDDOC |
User-mode GDI is calling DrvDocumentEvent before sending an application’s EndDoc call to kernel-mode GDI for processing. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_ENDDOCPOST | User-mode GDI is calling DrvDocumentEvent after kernel-mode GDI has processed an application’s EndDoc call. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_ABORTDOC | User-mode GDI is calling DrvDocumentEvent before sending an application’s AbortDoc call to kernel-mode GDI for processing. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_DELETEDC | User-mode GDI is calling DrvDocumentEvent before sending an application’s DeleteDC call to kernel-mode GDI for processing. Neither pbIn or pbOut are used. |
| DOCUMENTEVENT_ESCAPE | User-mode GDI is calling DrvDocumentEvent before sending an application’s ExtEscape call to kernel-mode GDI for processing. pbIn points to an array of three ULONGs that specify the nEscape, cbInput, and lpszInData parameters of the Win32 ExtEscape. The driver should return cbOut and pbOut so that they correspond with the cbOutput and lpszOutData parameters to ExtEscape. |
cbIn
Size in bytes of the buffer to which pbIn points.
pbIn
Pointer to the input data associated with iEsc, if any. See the description of iEsc for details.
cbOut
Size in bytes of the buffer to which pbOut points.
pbOut
Pointer to the output data associated with iEsc, if any. See the description of iEsc for details.
Return Value
DrvDocumentEvent returns one of the following values:
| Return Value | Meaning |
| DOCUMENTEVENT_SUCCESS | The driver successfully handled the hooked call identified by iEsc. |
| DOCUMENTEVENT_UNSUPPORTED | The driver does not support the hooked call identified by iEsc. |
| DOCUMENTEVENT_FAILURE | The driver supports the hooked call identified by iEsc, but failed to handle the request. |
Comments
A printer driver UI can optionally implement DrvDocumentEvent to hook certain printer management calls made by an application to GDI. This enables the printer driver’s UI module to process data in user mode before GDI passes the call to kernel-mode, and to post-process the data returned from kernel-mode before GDI returns it to the application. DrvDocumentEvent is executed in the context of the application’s process.
GDI calls DrvDocumentEvent before sending the application call on to kernel-mode GDI when the escape code definition has no suffix or is suffixed with PRE. For those escape code definitions suffixed with POST, GDI calls DrvDocumentEvent after the call is processed by kernel-mode GDI but before the results are returned to the application.
A FAX driver can implement DrvDocumentEvent so that it displays a user interface dialog box upon a call to the Win32 StartDoc routine.