DrvDocumentEvent function

A printer interface DLL's DrvDocumentEvent function can handle certain events associated with printing a document.

Syntax


int DrvDocumentEvent(
  HANDLE hPrinter,
  HDC hdc,
  int iEsc,
  ULONG cbIn,
  _In_   PVOID pvIn,
  ULONG cbOut,
  _Out_  PVOID pvOut
);

Parameters

hPrinter

Caller-supplied printer handle.

hdc

Caller-supplied device context handle, generated by a CreateDC (described in the Windows SDK documentation) call. This is zero if iEsc is set to DOCUMENTEVENT_CREATEDCPRE. For restrictions on printing from a 32-bit application on a 64-bit version of Windows, see the following Remarks section.

iEsc

Caller-supplied escape code identifying the event to be handled. This parameter can be one of the following integer constants. See the Windows SDK documentation for descriptions of the functions listed in the Event column.

For restrictions on printing from a 32-bit application on a 64-bit version of Windows, see the following Remarks section.

iEsc ConstantEvent

DOCUMENTEVENT_ABORTDOC

GDI is about to process a call to its AbortDoc function.

DOCUMENTEVENT_CREATEDCPOST

GDI has just processed a call to its CreateDC or CreateIC function.

This escape code should not be used unless there has been a previous call to DrvDocumentEvent with iEsc set to DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_CREATEDCPRE

GDI is about to process a call to its CreateDC or CreateIC function.

DOCUMENTEVENT_DELETEDC

GDI is about to process a call to its DeleteDC function.

DOCUMENTEVENT_ENDDOCPOST

GDI has just processed a call to its EndDoc function.

DOCUMENTEVENT_ENDDOCPRE

or

DOCUMENTEVENT_ENDDOC

GDI is about to process a call to its EndDoc function.

DOCUMENTEVENT_ENDPAGE

GDI is about to process a call to its EndPage function.

DOCUMENTEVENT_ESCAPE

GDI is about to process a call to its ExtEscape function.

DOCUMENTEVENT_QUERYFILTER

The DOCUMENTEVENT_QUERYFILTER event represents an opportunity for the spooler to query the driver for a list of the DOCUMENTEVENT_XXX events to which the driver will respond. This event is issued just prior to a call to DrvDocumentEvent that passes the DOCUMENTEVENT_CREATEDCPRE event.

DOCUMENTEVENT_RESETDCPOST

GDI has just processed a call to its ResetDC function.

This escape code should not be used unless there has been a previous call to DrvDocumentEvent with iEsc set to DOCUMENTEVENT_RESETDCPRE.

DOCUMENTEVENT_RESETDCPRE

GDI is about to process a call to its ResetDC function.

DOCUMENTEVENT_STARTDOCPOST

GDI has just processed a call to its StartDoc function.

DOCUMENTEVENT_STARTDOCPRE

or

DOCUMENTEVENT_STARTDOC

GDI is about to process a call to its StartDoc function.

DOCUMENTEVENT_STARTPAGE

GDI is about to process a call to its StartPage function.

 

cbIn

Caller-supplied size, in bytes, of the buffer pointed to by pvIn.

pvIn [in]

Caller-supplied pointer, the use of which is dependent on the value supplied for iEsc, as follows:

iEsc ConstantpvIn Contents

DOCUMENTEVENT_ABORTDOC

Not used.

DOCUMENTEVENT_CREATEDCPOST

pvIn contains the address of a pointer to the DEVMODEW structure specified in the pvOut parameter in a previous call to this function, for which the iEsc parameter was set to DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_CREATEDCPRE

pvIn points to a DOCEVENT_CREATEDCPRE structure.

DOCUMENTEVENT_DELETEDC

Not used.

DOCUMENTEVENT_ENDDOCPOST

Not used.

DOCUMENTEVENT_ENDDOCPRE

or

DOCUMENTEVENT_ENDDOC

Not used.

DOCUMENTEVENT_ENDPAGE

Not used.

DOCUMENTEVENT_ESCAPE

pvIn points to a DOCEVENT_ESCAPE structure.

DOCUMENTEVENT_QUERYFILTER

Same as for DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_RESETDCPOST

pvIn contains the address of a pointer to the DEVMODEW structure specified in the pvOut parameter in a previous call to this function, for which the iEsc parameter was set to DOCUMENTEVENT_RESETDCPRE.

DOCUMENTEVENT_RESETDCPRE

pvIn contains the address of a pointer to the DEVMODEW structure supplied by the caller of ResetDC (described in the Windows SDK documentation).

DOCUMENTEVENT_STARTDOCPOST

pvIn points to a LONG that specifies the print job identifier returned by StartDoc (described in the Windows SDK documentation).

DOCUMENTEVENT_STARTDOCPRE

or

DOCUMENTEVENT_STARTDOC

pvIn contains the address of a pointer to a DOCINFO structure supplied by the caller of StartDoc (both described in the Windows SDK documentation).

DOCUMENTEVENT_STARTPAGE

Not used.

 

cbOut

If iEsc is DOCUMENTEVENT_ESCAPE:

Function-supplied value that is used as the cbOutput parameter for ExtEscape.

If iEsc is DOCUMENTEVENT_QUERYFILTER:

Caller-supplied size, in bytes, of the buffer pointer to by pvOut.

For all other iEsc values:

Not used.

pvOut [out]

Function-supplied pointer to an output buffer, the use of which is dependent on the value supplied for iEsc, as follows. CreateDC, ExtEscape, and ResetDC are described in the Windows SDK documentation.

iEsc ConstantpvOut Contents

DOCUMENTEVENT_CREATEDCPRE

Pointer to a driver-supplied DEVMODEW structure, which GDI uses instead of the one supplied by the CreateDC caller. (If NULL, GDI uses the caller-supplied structure.)

DOCUMENTEVENT_ESCAPE

Buffer pointer that is used as the lpszOutData parameter for ExtEscape.

DOCUMENTEVENT_QUERYFILTER

Caller-supplied pointer to buffer containing a DOCEVENT_FILTER structure.

DOCUMENTEVENT_RESETDCPRE

Pointer to a driver-supplied DEVMODEW structure, which GDI uses instead of the one supplied by the ResetDC caller. (If NULL, GDI uses the caller-supplied structure.)

All other iEsc values

Not used.

 

Return value

The function's return value is dependent on the escape supplied for iEsc. For some escape codes, the return value is not used (see the second list of values). If the function supplies a return value, it must be one of the following:

Return codeDescription
DOCUMENTEVENT_FAILURE

The driver supports the escape code identified by iEsc, but a failure occurred.

DOCUMENTEVENT_SUCCESS

The driver successfully handled the escape code identified by iEsc.

DOCUMENTEVENT_UNSUPPORTED

The driver does not support the escape code identified by iEsc.

 

Remarks

A printer interface DLL can optionally provide a DrvDocumentEvent function to perform preprocessing or postprocessing of GDI calls associated with rendering a document. Calls to the DrvDocumentEvent function are made from the user-mode GDI client, when an application makes calls into the GDI client.

For an iEsc value of DOCUMENTEVENT_QUERYFILTER, the spooler can interpret a DOCUMENTEVENT_SUCCESS value returned by DrvDocumentEvent in two ways, depending on whether the driver modified certain members of the DOCEVENT_FILTER structure. (The pvOut parameter points to this structure.) When the spooler allocates memory for a structure of this type, it initializes two members of this structure, cElementsReturned and cElementsNeeded, to known values. After DrvDocumentEvent returns, the spooler determines whether the values of these members have changed, and uses that information to interpret the DrvDocumentEvent return value. The following table summarizes this situation.

Return ValueStatus of cElementsReturned,Meaning
cElementsNeeded

DOCUMENTEVENT_SUCCESS

Driver made no change to either member.

The spooler interprets this return value as equivalent to DOCUMENTEVENT_UNSUPPORTED.

The spooler is unable to retrieve the event filter from the driver, so it persists in calling DrvDocumentEvent for all events.

DOCUMENTEVENT_SUCCESS

Driver wrote to one or both members.

The spooler accepts this return value without interpretation. If the driver wrote to only one of cElementsNeeded and cElementsReturned, the spooler considers the unchanged member to have a value of zero.

The spooler filters out all events listed in the aDocEventCall member of DOCEVENT_FILTER.

DOCUMENTEVENT_UNSUPPORTED

Not applicable

The driver does not support DOCUMENTEVENT_QUERYFILTER.

The spooler is unable to retrieve the event filter from the driver, so it persists in calling DrvDocumentEvent for all events.

DOCUMENTEVENT_FAILURE

Not applicable

The driver supports DOCUMENTEVENT_QUERYFILTER, but encountered an internal error.

The spooler is unable to retrieve the event filter from the driver, so it persists in calling DrvDocumentEvent for all events.

 

If the escape code name has no suffix or is suffixed with PRE, the GDI client calls DrvDocumentEvent just prior to calling the kernel-mode GDI rendering engine. If the escape code name is suffixed with POST, the GDI client calls DrvDocumentEvent just after the kernel-mode GDI rendering engine returns.

If the escape code supplied in the iEsc parameter is DOCUMENTEVENT_CREATEDCPRE, the following rules apply:

  • If the job is being sent directly to the printer without spooling, pvIn --> pszDevice points to the printer name. (See the DOCEVENT_CREATEDCPRE structure for more information.)

  • If the job is being spooled, pvIn --> pszDevice points to the printer port name.

The DrvDocumentEvent function executes in the context of the user-mode caller of the GDI client function. When EMF spooling is disabled, the function can display a user interface. For example, the DrvDocumentEvent function for a FAX driver might display a dialog box to the user before GDI's StartDoc function (described in the Microsoft Windows SDK documentation) is processed.

Note   The following restrictions apply when running a 32-bit application on a 64-bit version of Windows. The only GDI function that DrvDocumentEvent should call is ExtEscape, and only private escapes should be used. DrvDocumentEvent calls to other GDI functions may produce undefined behavior.

Requirements

Header

Winddiui.h (include Winddiui.h)

See also

DOCEVENT_FILTER
DOCEVENT_CREATEDCPRE
DOCEVENT_ESCAPE

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft