DocumentEvent function

The DocumentEvent function is an event handler for events associated with printing a document.

Syntax


HRESULT DocumentEvent(
  _In_  HANDLE hPrinter,
  _In_  HDC    hdc,
        INT    iEsc,
        ULONG  cbIn,
  _In_  PVOID  pvIn,
        ULONG  cbOut,
  _Out_ PVOID  pvOut
);

Parameters

hPrinter [in]

A handle to a printer object. Use the OpenPrinter or AddPrinter function to retrieve a printer handle.

hdc [in]

A device context handle that is generated by a call of CreateDC. 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 Remarks.

iEsc

An escape code that identifies the event to be handled. This parameter can be one of the following integer constants.

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 DocumentEvent 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 DocumentEvent 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 DocumentEvent 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

The size, in bytes, of the buffer pointed to by pvIn.

pvIn [in]

A pointer to a buffer. What the buffer contains depends on the value of iEsc, as shown in the following table.

Constant pvin Contents
DOCUMENTEVENT_ABORTDOC

Not used.

DOCUMENTEVENT_CREATEDCPOST

pvIn contains the address of a pointer to the DEVMODE 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 which is documented in the Windows Driver Development Kit.

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 which is documented in the Windows Driver Development Kit.

DOCUMENTEVENT_QUERYFILTER

Same as for DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_RESETDCPOST

pvIn contains the address of a pointer to the DEVMODE 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 DEVMODE structure supplied by the caller of ResetDC.

DOCUMENTEVENT_STARTDOCPOST

pvIn points to a LONG that specifies the print job identifier returned by StartDoc.

DOCUMENTEVENT_STARTDOCPRE or DOCUMENTEVENT_STARTDOC

pvIn contains the address of a pointer to a DOCINFO structure supplied by the caller of StartDoc.

DOCUMENTEVENT_STARTPAGE

Not used.

 

cbOut
Value Meaning
IDOCUMENTEVENT_QUERYFILTERThe size, in bytes, of the buffer pointer to by pvOut.
DOCUMENTEVENT_ESCAPEA value that is used as the cbOutput parameter for ExtEscape.
For all other valuesiEsc is not used.

 

pvOut [out]

A pointer to a buffer. The contents of the buffer depend on the value supplied for iEsc, as shown in the following table.

Constant pvOut Contents
DOCUMENTEVENT_CREATEDCPRE

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

DOCUMENTEVENT_ESCAPE

A pointer to a buffer that is used as the lpszOutData parameter for ExtEscape.

DOCUMENTEVENT_QUERYFILTER

A pointer to buffer containing a DOCEVENT_FILTER structure which is documented in the Windows Driver Development Kit.

DOCUMENTEVENT_RESETDCPRE

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

 

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 below). If the function supplies a return value, it must be one of the following.

Return ValueMeaning
DOCUMENTEVENT_FAILUREThe driver supports the escape code identified by iEsc, but a failure occurred.
DOCUMENTEVENT_SUCCESSThe driver successfully handled the escape code identified by iEsc.
DOCUMENTEVENT_UNSUPPORTEDThe driver does not support the escape code identified by iEsc.

 

The following list indicates which escape codes that require a return value and which do not, and explains the meaning of the DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE, and DOCUMENTEVENT_UNSUPPORTED return codes.

Return ValueMeaning
DOCUMENTEVENT_ABORTDOCThe return value is not used and should not be read.
DOCUMENTEVENT_CREATEDCPOSTThe return value is not used and should not be read.
DOCUMENTEVENT_CREATEDCPREDOCUMENTEVENT_FAILURE - GDI does not create the device context or information context, and provides a return value of 0 for CreateDC or CreateIC.
DOCUMENTEVENT_DELETEDCThe return value is not used and should not be read.
DOCUMENTEVENT_ENDDOCPOSTThe return value is not used and should not be read.
DOCUMENTEVENT_ENDDOCPRE or DOCUMENTEVENT_ENDDOCThe return value is not used and should not be read.
DOCUMENTEVENT_ENDPAGEThe return value is not used and should not be read.
DOCUMENTEVENT_ESCAPEThe return value is not used and should not be read.
DOCUMENTEVENT_QUERYFILTERSee Remarks.
DOCUMENTEVENT_RESETDCPOSTThe return value is not used and should not be read.
DOCUMENTEVENT_RESETDCPREDOCUMENTEVENT_FAILURE - GDI does not reset the device context, and provides a return value of 0 for ResetDC.
DOCUMENTEVENT_STARTDOCPOSTDOCUMENTEVENT_FAILURE - GDI calls AbortDoc to stop the document, and then provides a return value of SP_ERROR for StartDoc.
DOCUMENTEVENT_STARTDOCPRE or DOCUMENTEVENT_STARTDOCDOCUMENTEVENT_FAILURE - GDI does not start the document, and provides a return value of SP_ERROR for StartDoc.
DOCUMENTEVENT_STARTPAGEDOCUMENTEVENT_FAILURE - GDI does not start the page, and provides a return value of SP_ERROR for StartPage.

 

Remarks

For an iEsc value of DOCUMENTEVENT_QUERYFILTER, the spooler can interpret a DOCUMENTEVENT_SUCCESS value returned by DocumentEvent in two ways, depending on whether the driver modified certain members of the DOCEVENT_FILTER structure (which is documented in the Windows Driver Development Kit ). (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 DocumentEvent returns, the spooler determines whether the values of these members have changed, and uses that information to interpret the DocumentEvent return value. The following table summarizes this situation.

Return ValueStatus of cElementsReturned and cElementsNeededMeaning

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 DocumentEvent 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 (which is documented in the Windows Driver Development Kit ).

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 DocumentEvent 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 DocumentEvent for all events.

 

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. (For more information, see the documentation for the DOCEVENT_CREATEDCPRE structure in the Windows Driver Development Kit.)
  • If the job is being spooled, pvIn->pszDevice points to the printer port name.
Note   The following restrictions apply when running a 32-bit application on a 64-bit version of Windows. The only GDI function that DocumentEvent should call is ExtEscape, and only private escapes should be used. DocumentEvent calls to other GDI functions may produce undefined behavior.
 

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Winspool.h (include Windows.h)

Unicode and ANSI names

DocumentEventW (Unicode) and DocumentEventA (ANSI)

See also

Printing
Print Spooler API Functions
Windows Driver Development Kit

 

 

Show: