DocumentEvent 函数

  • 项目

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

语法

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

参数

hPrinter [in]

打印机对象的句柄。 使用 OpenPrinter 或 AddPrinter 函数检索打印机句柄。

hdc [in]

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

iEsc

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

常数 活动
DOCUMENTEVENT_ABORTDOC
 GDI 即将处理对其 AbortDoc 函数的调用。
DOCUMENTEVENT_CREATEDCPOST
 GDI 刚刚处理了对其 CreateDC 或 CreateIC 函数的调用。
除非之前已调用 documentEvent 且 iEsc 设置为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 函数的调用。
除非之前已调用 DocumentEvent 且 iEsc 设置为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 参数指向此结构。）当后台处理程序为此类型的结构分配内存时，它会将此结构的两个成员（cElementsReturned 和 cElementsNeeded）初始化为已知值。 DocumentEvent 返回后，后台处理程序确定这些成员的值是否已更改，并使用该信息解释 DocumentEvent 返回值。 下表总结了这种情况。

返回值 cElementsReturned 和 cElementsNeeded 的状态 含义
DOCUMENTEVENT_SUCCESS
 驱动程序未对任一成员进行更改。
 后台处理程序将此返回值解释为等效于 DOCUMENTEVENT_UNSUPPORTED。 后台处理程序无法从驱动程序检索事件筛选器，因此它会保留对所有事件的 DocumentEvent 调用。
DOCUMENTEVENT_SUCCESS
 驱动程序写给一个或两个成员。
 后台处理程序接受此返回值而不解释。 如果驱动程序只写入其中一个 cElementsNeeded 和 cElementsReturned，则后台处理程序会将未更改的成员视为值为零。
后台处理程序筛选掉 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）

另请参阅