大网数据广告活动
打印与设备

DocumentEvent function (Winspool.h)

· 52CE 我爱测

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

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

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 05/31/2018
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。