DocumentEvent 函数

DocumentEvent 函数是与打印文档关联的事件的事件处理程序。

语法

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

参数

hPrinter [in]

打印机对象的句柄。 使用 OpenPrinterAddPrinter 函数检索打印机句柄。

hdc [in]

CreateDC 调用生成的设备上下文句柄。 如果 iEsc 设置为 DOCUMENTEVENT_CREATEDCPRE,则为零。 有关从 64 位版本的 Windows 上的 32 位应用程序打印的限制,请参阅“备注”。

iEsc

标识要处理的事件的转义代码。 此参数可为下列整数常量之一。

常数 活动
DOCUMENTEVENT_ABORTDOC
GDI 即将处理对其 AbortDoc 函数的调用。
DOCUMENTEVENT_CREATEDCPOST
GDI 刚刚处理了对其 CreateDC CreateIC 函数的调用。
除非之前已调用 documentEventiEsc 设置为DOCUMENTEVENT_CREATEDCPRE,否则不应使用此转义代码。
DOCUMENTEVENT_CREATEDCPRE
GDI 即将处理对其 CreateDC CreateIC 函数的调用。
DOCUMENTEVENT_DELETEDC
GDI 即将处理对其 DeleteDC 函数的调用。
DOCUMENTEVENT_ENDDOCPOST
GDI 刚刚处理了对其 EndDoc 函数的调用。
DOCUMENTEVENT_ENDDOCPRE 或 DOCUMENTEVENT_ENDDOC
GDI 即将处理对其 EndDoc 函数的调用。
DOCUMENTEVENT_ENDPAGE
GDI 即将处理对其 EndPage 函数的调用。
DOCUMENTEVENT_ESCAPE
GDI 即将处理对其 ExtEscape 函数的调用。
DOCUMENTEVENT_QUERYFILTER
DOCUMENTEVENT_QUERYFILTER 事件表示后台处理程序有机会查询驱动程序,以获取驱动程序将响应的 DOCUMENTEVENT_ XXX 事件列表。 此事件是在调用通过 DOCUMENTEVENT_CREATEDCPRE 事件的 DocumentEvent 之前发出的。
DOCUMENTEVENT_RESETDCPOST
GDI 刚刚处理了对其 ResetDC 函数的调用。
除非之前已调用 DocumentEventiEsc 设置为DOCUMENTEVENT_RESETDCPRE,否则不应使用此转义代码。
DOCUMENTEVENT_RESETDCPRE
GDI 即将处理对其 ResetDC 函数的调用。
DOCUMENTEVENT_STARTDOCPOST
GDI 刚刚处理了对其 StartDoc 函数的调用。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC
GDI 即将处理对其 StartDoc 函数的调用。
DOCUMENTEVENT_STARTPAGE
GDI 即将处理对其 StartPage 函数的调用。

cbIn

pvIn 指向的缓冲区的大小(以字节为单位)。

pvIn [in]

指向缓冲区的指针。 缓冲区包含的内容取决于 iEsc 的值,如下表所示。

常数 pvin 内容
DOCUMENTEVENT_ABORTDOC
未使用。
DOCUMENTEVENT_CREATEDCPOST
pvIn 包含指向在上一次调用此函数中 pvOut 参数中指定的 DEVMODE 结构的指针的地址,其中 iEsc 参数设置为 DOCUMENTEVENT_CREATEDCPRE。
DOCUMENTEVENT_CREATEDCPRE
pvIn 指向 Windows 驱动程序开发工具包中记录的 DOCEVENT_CREATEDCPRE 结构。
DOCUMENTEVENT_DELETEDC
未使用。
DOCUMENTEVENT_ENDDOCPOST
未使用。
DOCUMENTEVENT_ENDDOCPRE 或 DOCUMENTEVENT_ENDDOC
未使用。
DOCUMENTEVENT_ENDPAGE
未使用。
DOCUMENTEVENT_ESCAPE
pvIn 指向 Windows 驱动程序开发工具包中记录的 DOCEVENT_ESCAPE 结构。
DOCUMENTEVENT_QUERYFILTER
与 DOCUMENTEVENT_CREATEDCPRE 相同。
DOCUMENTEVENT_RESETDCPOST
pvIn 包含指向在上一次调用此函数中 pvOut 参数中指定的 DEVMODE 结构的指针的地址,其中 iEsc 参数设置为 DOCUMENTEVENT_RESETDCPRE。
DOCUMENTEVENT_RESETDCPRE
pvIn 包含指向 ResetDC 调用方提供的 DEVMODE 结构的指针的地址。
DOCUMENTEVENT_STARTDOCPOST
pvIn 指向指定 StartDoc 返回的打印作业标识符的 LONG。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC
pvIn 包含指向 StartDoc 调用方提供的 DOCINFO 结构的指针的地址。
DOCUMENTEVENT_STARTPAGE
未使用。

cbOut

含义
IDOCUMENTEVENT_QUERYFILTER pvOut 指向的缓冲区的大小(以字节为单位)。
DOCUMENTEVENT_ESCAPE 用作 ExtEscape cbOutput 参数的值。
对于所有其他值 未使用 iEsc。

pvOut [out]

指向缓冲区的指针。 缓冲区的内容取决于为 iEsc 提供的值,如下表所示。

常数 pvOut 内容
DOCUMENTEVENT_CREATEDCPRE
指向驱动程序提供的 DEVMODE 结构的指针,GDI 使用该结构,而不是 CreateDC 调用方提供的结构。 (如果 NULL,GDI 使用调用方提供的结构。)
DOCUMENTEVENT_ESCAPE
指向用作 ExtEscape 的 lpszOutData 参数的缓冲区的指针。
DOCUMENTEVENT_QUERYFILTER
指向包含 Windows 驱动程序开发工具包中记录的 DOCEVENT_FILTER 结构的缓冲区的指针。
DOCUMENTEVENT_RESETDCPRE
指向驱动程序提供的 DEVMODE 结构的指针,GDI 使用该结构,而不是 ResetDC 调用方提供的结构。 (如果 NULL,GDI 使用调用方提供的结构。)

返回值

函数的返回值取决于为 iEsc 提供的转义。 对于某些转义代码,未使用返回值(请参阅下文)。 如果函数提供返回值,则它必须是下列值之一。

返回值 含义
DOCUMENTEVENT_FAILURE 驱动程序支持 iEsc 标识的转义代码,但发生了故障。
DOCUMENTEVENT_SUCCESS 驱动程序已成功处理 iEsc 标识的转义代码。
DOCUMENTEVENT_UNSUPPORTED 驱动程序不支持 iEsc 标识的转义代码。

以下列表指示需要返回值和不返回值的转义代码,并说明 DOCUMENTEVENT_SUCCESS、DOCUMENTEVENT_FAILURE 和 DOCUMENTEVENT_UNSUPPORTED 返回代码的含义。

返回值 含义
DOCUMENTEVENT_ABORTDOC 返回值未使用,不应读取。
DOCUMENTEVENT_CREATEDCPOST 返回值未使用,不应读取。
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE - GDI 不创建设备上下文或信息上下文,并为 CreateDC 或 CreateIC 提供返回值 0。
DOCUMENTEVENT_DELETEDC 返回值未使用,不应读取。
DOCUMENTEVENT_ENDDOCPOST 返回值未使用,不应读取。
DOCUMENTEVENT_ENDDOCPRE 或 DOCUMENTEVENT_ENDDOC 返回值未使用,不应读取。
DOCUMENTEVENT_ENDPAGE 返回值未使用,不应读取。
DOCUMENTEVENT_ESCAPE 返回值未使用,不应读取。
DOCUMENTEVENT_QUERYFILTER 请参阅“备注”。
DOCUMENTEVENT_RESETDCPOST 返回值未使用,不应读取。
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE - GDI 不会重置设备上下文,并为 ResetDC 提供返回值 0
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE - GDI 调用 AbortDoc 以停止文档,然后为 StartDoc 提供返回值 SP_ERROR。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE - GDI 不启动文档,并为 StartDoc 提供返回值 SP_ERROR
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE - GDI 不启动页面,并为 StartPage 提供返回值 SP_ERROR。

注解

对于DOCUMENTEVENT_QUERYFILTER的 iEsc 值,后台处理程序可以通过两种方式解释 DocumentEvent 返回的 DOCUMENTEVENT_SUCCESS 值,具体取决于驱动程序是否修改了 DOCEVENT_FILTER 结构的某些成员(该成员记录在 Windows 驱动程序开发工具包中)。 (pvOut 参数指向此结构。)当后台处理程序为此类型的结构分配内存时,它会将此结构的两个成员(cElementsReturnedcElementsNeeded)初始化为已知值。 DocumentEvent 返回后,后台处理程序确定这些成员的值是否已更改,并使用该信息解释 DocumentEvent 返回值。 下表总结了这种情况。

返回值 cElementsReturned 和 cElementsNeeded 的状态 含义
DOCUMENTEVENT_SUCCESS
驱动程序未对任一成员进行更改。
后台处理程序将此返回值解释为等效于 DOCUMENTEVENT_UNSUPPORTED。 后台处理程序无法从驱动程序检索事件筛选器,因此它会保留对所有事件的 DocumentEvent 调用
DOCUMENTEVENT_SUCCESS
驱动程序写给一个或两个成员。
后台处理程序接受此返回值而不解释。 如果驱动程序只写入其中一个 cElementsNeededcElementsReturned,则后台处理程序会将未更改的成员视为值为零。
后台处理程序筛选掉 DOCEVENT_FILTER 的 aDocEventCall 成员中列出的所有事件(该成员记录在 Windows 驱动程序开发工具包中)。
DOCUMENTEVENT_UNSUPPORTED
不适用
驱动程序不支持 DOCUMENTEVENT_QUERYFILTER。
后台处理程序无法从驱动程序检索事件筛选器,因此它会保留对所有事件的 DocumentEvent 调用
DOCUMENTEVENT_FAILURE
不适用
驱动程序支持 DOCUMENTEVENT_QUERYFILTER,但遇到内部错误。
后台处理程序无法从驱动程序检索事件筛选器,因此它会保留对所有事件的 DocumentEvent 调用

如果 iEsc 参数中提供的转义代码为 DOCUMENTEVENT_CREATEDCPRE,则适用以下规则:

  • 如果作业直接发送到打印机而不进行后台处理程序,pvIn->pszDevice 指向打印机名称。 (有关详细信息,请参阅 Windows 驱动程序开发工具包中的 DOCEVENT_CREATEDCPRE 结构文档。)
  • 如果作业正在后台处理,pvIn->pszDevice 指向打印机端口名称。

注意

在 64 位版本的 Windows 上运行 32 位应用程序时,以下限制适用。 DocumentEvent 应调用的唯一 GDI 函数是 ExtEscape,只应使用专用转义。 tDocumentEven 对其他 GDI 函数的调用可能会生成未定义的行为。

要求

要求
最低受支持的客户端
Windows Vista [仅限桌面应用]
最低受支持的服务器
Windows Server 2008 [仅限桌面应用]
标头
Winspool.h(包括 Windows.h)
Unicode 和 ANSI 名称
DocumentEventW (Unicode) 和 DocumentEventA (ANSI)

另请参阅