IPrintOemUI2：:D ocumentEvent 方法（prcomoem.h）

项目
02/07/2025

IPrintOemUI2::DocumentEvent 方法允许 UI 插件替换核心驱动程序 UI 模块对 DrvDocumentEvent DDI 的默认实现。

语法

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

参数

hPrinter

调用方提供的打印机句柄。

hdc

调用方提供的设备上下文句柄，由 CreateDC 调用生成。如果 iEsc DOCUMENTEVENT_CREATEDCPRE，则为零。

iEsc

调用方提供的转义代码标识要处理的事件。此参数可以是下列整数常量之一：

转义代码	意义
DOCUMENTEVENT_ABORTDOC	GDI 即将处理对其 AbortDoc 函数的调用。
DOCUMENTEVENT_CREATEDCPOST	GDI 刚刚处理了对其 CreateDC 或 CreateIC 函数的调用。除非先前已调用 DrvDocumentEvent且 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事件的 drvDocumentEvent 之前发出此事件。
DOCUMENTEVENT_RESETDCPOST	GDI 刚刚处理了对其 ResetDC 函数的调用。除非先前已调用 DrvDocumentEvent 且 iEsc 设置为DOCUMENTEVENT_RESETDCPRE，否则不应使用此转义代码。
DOCUMENTEVENT_RESETDCPRE	GDI 即将处理对其 ResetDC 函数的调用。
DOCUMENTEVENT_STARTDOCPOST	GDI 刚刚处理了对其 StartDoc 函数的调用。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC	GDI 即将处理对其 StartDoc 函数的调用。
DOCUMENTEVENT_STARTPAGE	GDI 即将处理对其 StartPage 函数的调用。

cbIn

pvIn指向的缓冲区的调用方提供的大小（以字节为单位）。

pvIn

调用方提供的指针，其用法取决于为 iEsc提供的值，如下所示：

iEsc 常量	pvIn 内容
DOCUMENTEVENT_ABORTDOC	未使用。
DOCUMENTEVENT_CREATEDCPOST	pvIn 包含指向上一个调用此函数的 pvOut 参数中指定的 DEVMODEW 结构的指针的地址，其中 iEsc 参数设置为DOCUMENTEVENT_CREATEDCPRE。
DOCUMENTEVENT_CREATEDCPRE	pvIn 指向 DOCEVENT_CREATEDCPRE 结构。
DOCUMENTEVENT_DELETEDC	未使用。
DOCUMENTEVENT_ENDDOCPOST	未使用。
DOCUMENTEVENT_ENDDOCPRE 或 DOCUMENTEVENT_ENDDOC	未使用。
DOCUMENTEVENT_ENDPAGE	未使用。
DOCUMENTEVENT_ESCAPE	pvIn 指向 DOCEVENT_ESCAPE 结构。
DOCUMENTEVENT_QUERYFILTER	与DOCUMENTEVENT_CREATEDCPRE相同。
DOCUMENTEVENT_RESETDCPOST	pvIn 包含指向上一个调用此函数的 pvOut 参数中指定的 DEVMODEW 结构的指针的地址，其中 iEsc 参数设置为DOCUMENTEVENT_RESETDCPRE。
DOCUMENTEVENT_RESETDCPRE	pvIn 包含指向 ResetDC 调用方提供的 DEVMODEW 结构的指针的地址（Microsoft Windows SDK 文档中所述）。
DOCUMENTEVENT_STARTDOCPOST	pvIn 指向一个 LONG，它指定 StartDoc 返回的打印作业标识符（如 Windows SDK 文档中所述）。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC	pvIn 包含指向 StartDoc 调用方提供的 DOCINFO 结构的指针的地址（这两者均在 Windows SDK 文档中所述）。
DOCUMENTEVENT_STARTPAGE	未使用。

cbOut

如果 iEsc DOCUMENTEVENT_ESCAPE：

用作 ExtEscape的 cbOutput 参数的函数提供的值。

如果 iEsc DOCUMENTEVENT_QUERYFILTER：

调用方提供的缓冲区指针的大小（以字节为单位）通过 pvOut。

对于所有其他 iEsc 值：

未使用。

pvOut

函数提供的指向输出缓冲区的指针，其用法取决于为 iEsc提供的值，如下所示。 Windows SDK 文档中介绍了 createDC、ExtEscape和 ResetDC。

iEsc 常量	pvOut 内容
DOCUMENTEVENT_CREATEDCPRE	指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是由 CreateDC 调用方提供的结构。（如果 NULL，GDI 将使用调用方提供的结构。
DOCUMENTEVENT_ESCAPE	用作 ExtEscape的 lpszOutData 参数的缓冲区指针。
DOCUMENTEVENT_QUERYFILTER	调用方提供的指向包含 DOCEVENT_FILTER 结构的缓冲区的指针。
DOCUMENTEVENT_RESETDCPRE	指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是由 ResetDC 调用方提供的结构。（如果 NULL，GDI 将使用调用方提供的结构。
所有其他 iEsc 值	未使用。

piResult

指向接收以下值之一的内存位置的指针：

返回值	定义
DOCUMENTEVENT_FAILURE	驱动程序支持由 iEsc标识的转义代码，但发生了故障。
DOCUMENTEVENT_SUCCESS	驱动程序已成功处理由 iEsc标识的转义代码。另请参阅“备注”部分了解详细信息。
DOCUMENTEVENT_UNSUPPORTED	驱动程序不支持由 iEsc标识的转义代码。

返回值

此方法应返回以下值之一。有关详细信息，请参阅“备注”部分。

返回代码	描述
S_OK	UI 插件实现此方法。
E_NOTIMPL	UI 插件不实现此方法。

言论

用户界面插件的 IPrintOemUI2::DocumentEvent 方法执行与用户模式打印机接口 DLL 导出的 DrvDocumentEvent DDI 相同的作类型。有关文档事件及其处理方式的信息，请参阅 DrvDocumentEvent DDI 的说明。

如果提供用户界面插件，打印机驱动程序的 DrvDocumentEvent DDI 调用 IPrintOemUI2::DocumentEvent 方法。 DrvDocumentEvent DDI 为指定事件执行自己的处理，然后调用 IPrintOemUI2::DocumentEvent 方法来处理事件的其他处理。

当使用 DOCUMENTEVENT_QUERYFILTER iEsc 参数的值调用此方法，并使用 *piResult == DOCUMENTEVENT_SUCCESS返回时，后台处理程序可以通过两种方式之一解释此值，具体取决于 DOCEVENT_FILTER 结构的某些成员是否更改了值。有关详细信息，请参阅 DrvDocumentEvent的“备注”部分。

触发DOCUMENTEVENT_QUERYFILTER事件时，核心驱动程序会按安装的顺序调用插件，直到其中一个插件返回S_OK，或者直到调用所有插件，并且没有返回任何插件S_OK。这样，最多允许一个插件处理DOCUMENTEVENT_QUERYFILTER事件，并且它指定的筛选器将应用于插件链中的所有插件。

对于实现 IPrintOemUI2 接口但不需要支持 IPrintOemUI2::DocumentEvent 方法的插件编写器，此方法应返回 iEsc的所有值的E_NOTIMPL。如果确实需要实现此方法，它应返回 iEsc的所有值的S_OK。这向核心驱动程序发出信号，即此方法已处理相关事件。核心驱动程序使用此方法放置在 piResult 中的值作为 DrvDocumentEvent DDI 的返回值。