Edytuj

Udostępnij za pośrednictwem

DocumentEvent function

  • Artykuł

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.

Constant Event
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_QUERYFILTER The size, in bytes, of the buffer pointer to by pvOut.
DOCUMENTEVENT_ESCAPE A value that is used as the cbOutput parameter for ExtEscape.
For all other values iEsc 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 Value Meaning
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.

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 Value Meaning
DOCUMENTEVENT_ABORTDOC The return value is not used and should not be read.
DOCUMENTEVENT_CREATEDCPOST The return value is not used and should not be read.
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE - GDI does not create the device context or information context, and provides a return value of 0 for CreateDC or CreateIC.
DOCUMENTEVENT_DELETEDC The return value is not used and should not be read.
DOCUMENTEVENT_ENDDOCPOST The return value is not used and should not be read.
DOCUMENTEVENT_ENDDOCPRE or DOCUMENTEVENT_ENDDOC The return value is not used and should not be read.
DOCUMENTEVENT_ENDPAGE The return value is not used and should not be read.
DOCUMENTEVENT_ESCAPE The return value is not used and should not be read.
DOCUMENTEVENT_QUERYFILTER See Remarks.
DOCUMENTEVENT_RESETDCPOST The return value is not used and should not be read.
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE - GDI does not reset the device context, and provides a return value of 0 for ResetDC.
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE - GDI calls AbortDoc to stop the document, and then provides a return value of SP_ERROR for StartDoc.
DOCUMENTEVENT_STARTDOCPRE or DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE - GDI does not start the document, and provides a return value of SP_ERROR for StartDoc.
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_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 Value Status of cElementsReturned and cElementsNeeded Meaning
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

Requirement Value
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