DrvDocumentEvent 函数 (winddiui.h)

  • 项目

打印机接口 DLL 的 DrvDocumentEvent 函数可以处理与打印文档相关的某些事件。

语法

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

参数

hPrinter

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

hdc

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

iEsc

调用方提供的转义代码标识要处理的事件。

有关在 64 位版本的 Windows 上从 32 位应用程序打印的限制，请参阅下面的 “备注 ”部分。

此参数可以是以下整数常量之一：

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 指向的缓冲区的调用方提供的大小（以字节为单位）。

[in] 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 结构的指针的地址。
DOCUMENTEVENT_STARTDOCPOST pvIn 指向指定 StartDoc 函数返回的打印作业标识符的 LONG。
DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC pvIn 包含指向由 StartDoc 函数的调用方提供的 DOCINFO 结构的指针的地址。
DOCUMENTEVENT_STARTPAGE 未使用。

cbOut

如果 iEsc 为 DOCUMENTEVENT_ESCAPE

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

如果 iEsc 为 DOCUMENTEVENT_QUERYFILTER

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

对于所有其他 iEsc 值

未使用。

[out] pvOut

函数提供的指向输出缓冲区的指针，其用法取决于为 iEsc 提供的值，如下所示：

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 值 未使用。

返回值

函数的返回值取决于为 iEsc 提供的转义。 对于某些转义代码，不使用返回值 (查看) 的第二个值列表。 如果函数提供返回值，则它必须是下列值之一：

返回代码 说明
DOCUMENTEVENT_FAILURE 驱动程序支持 由 iEsc 标识的转义代码，但发生故障。
DOCUMENTEVENT_SUCCESS 驱动程序已成功处理 由 iEsc 标识的转义代码。
DOCUMENTEVENT_UNSUPPORTED 驱动程序不支持 iEsc 标识的转义代码。

注解

打印机接口 DLL 可以选择提供 DrvDocumentEvent 函数，以执行与呈现文档相关的 GDI 调用的预处理或后处理。 当应用程序调用 GDI 客户端时，从用户模式 GDI 客户端调用 DrvDocumentEvent 函数。

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

返回值 cElementsReturned、cElementsNeeded 的状态 含义
DOCUMENTEVENT_SUCCESS 驱动程序未对任一成员进行更改。 后台处理程序将此返回值解释为等效于DOCUMENTEVENT_UNSUPPORTED。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。
DOCUMENTEVENT_SUCCESS 驱动程序写入一个或两个成员。 后台处理程序接受此返回值，无需解释。 如果驱动程序只写入 cElementsNeeded 和 cElementsReturned 中的一个，则后台处理程序会将未更改的成员视为值为零。 后台处理程序筛选出DOCEVENT_FILTER的 aDocEventCall 成员中列出的所有事件。
DOCUMENTEVENT_UNSUPPORTED 不适用 驱动程序不支持DOCUMENTEVENT_QUERYFILTER。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。
DOCUMENTEVENT_FAILURE 不适用 驱动程序支持DOCUMENTEVENT_QUERYFILTER，但遇到内部错误。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。

如果转义代码名称没有后缀或带有 PRE 后缀，则 GDI 客户端会在调用内核模式 GDI 呈现引擎之前调用 DrvDocumentEvent 。 如果转义代码名称后缀为 POST，则 GDI 客户端会在内核模式 GDI 呈现引擎返回后调用 DrvDocumentEvent 。

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

  • 如果作业直接发送到打印机而不后台打印， 则 pvIn --> pszDevice 指向打印机名称。 (有关详细信息，请参阅 DOCEVENT_CREATEDCPRE 结构。)

  • 如果作业正在假脱机， 则 pvIn --> pszDevice 指向打印机端口名称。

DrvDocumentEvent 函数在 GDI 客户端函数的用户模式调用方上下文中执行。 禁用 EMF 假脱机时，函数可以显示用户界面。 例如，FAX 驱动程序的 DrvDocumentEvent 函数可能会在处理 GDI 的 StartDoc 函数之前向用户显示一个对话框。

在 64 位版本的 Windows 上运行 32 位应用程序时，以下限制适用：

  • DrvDocumentEvent 应调用的唯一 GDI 函数是 ExtEscape，并且只应使用专用转义。

  • 对其他 GDI 函数的 DrvDocumentEvent 调用可能会产生未定义的行为。

要求

要求 值
目标平台 桌面
标头 winddiui.h (包括 Winddiui.h)

另请参阅

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER