DrvDocumentEvent

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.