IPrintOemUI2：:D ocumentEvent 方法 (prcomoem.h)

项目
03/14/2023

方法 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 调用生成。如果DOCUMENTEVENT_CREATEDCPRE iEsc ，则为零。

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 调用方提供的 DEVMODEW 结构。 (如果为 NULL，GDI 将使用调用方提供的 structure.)
DOCUMENTEVENT_ESCAPE	用作 ExtEscape 的 lpszOutData 参数的缓冲区指针。
DOCUMENTEVENT_QUERYFILTER	调用方提供的指向包含DOCEVENT_FILTER结构的缓冲区的指针。
DOCUMENTEVENT_RESETDCPRE	指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是 ResetDC 调用方提供的 DEVMODEW 结构。 (如果为 NULL，GDI 将使用调用方提供的 structure.)
所有其他 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 的返回值。