winddiui.h) (DOCEVENT_FILTER 结构

  • 项目

DOCEVENT_FILTER 结构包含打印机驱动程序将响应的文档事件列表。 有关文档事件的完整列表，请参阅 DrvDocumentEvent 。

语法

typedef struct _DOCEVENT_FILTER {
  UINT  cbSize;
  UINT  cElementsAllocated;
  UINT  cElementsNeeded;
  UINT  cElementsReturned;
  DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;

成员

cbSize

此结构的后台处理程序提供的大小（以字节为单位）。 后台处理程序将此成员初始化为 sizeof (DOCEVENT_FILTER) 。

cElementsAllocated

aDocEventCall 数组成员中由后台处理程序提供的元素数。 后台处理程序将此成员初始化为 DOCUMENTEVENT_LAST - 1。 (头文件 Winddiui.h.) 中定义了DOCUMENTEVENT_LAST常量

cElementsNeeded

驱动程序提供的 aDocEventCall 数组成员中所需的元素总数。 后台处理程序将此成员初始化为0XFFFFFFFF。 有关更多信息，请参见下面的“备注”部分。

cElementsReturned

驱动程序提供的放置在 aDocEventCall 数组成员中的DOCUMENTEVENT_**XXX**事件数。 后台处理程序将此成员初始化为0XFFFFFFFF。 有关更多信息，请参见下面的“备注”部分。

aDocEventCall[ANYSIZE_ARRAY]

驱动程序填充的 DWORD 数组，其中列出了打印机驱动程序将响应的所有 DOCUMENTEVENT_XXX 事件。 后台处理程序将此成员初始化为 0。

注解

打印机驱动程序列出将在DOCEVENT_FILTER结构中响应的事件。 由于这限制了后台处理程序需要对驱动程序的调用次数，因此打印机性能得到了增强。 当后台处理程序调用 DrvDocumentEvent DDI 且其 iEsc 参数设置为 DOCUMENTEVENT_QUERYFILTER 时，后台处理程序将分配包含DOCEVENT_FILTER结构的缓冲区，包括其 aDocEventCall 数组。 为缓冲区分配的内存量为：

sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)

分配包含 DOCEVENT_FILTER 结构的缓冲区后，后台处理程序会将结构成员初始化为以下值：

成员 初始化为
cbSize 0
cElementsAllocated DOCUMENTEVENT_LAST - 1

DOCUMENTEVENT_LAST常量在 winddiui.h 中定义。
cElementsNeeded 0XFFFFFFFF
cElementsReturned 0XFFFFFFFF
aDocEventCall 0

后台处理程序将结构成员初始化为上表所示的值后，它会调用 DrvDocumentEvent。 当此函数返回时，后台处理程序将检查 cElementsNeeded 和 cElementsReturned 成员，以查看其中一个是否已更改。 如果驱动程序已写入其中一个成员，但未写入另一个成员，则后台处理程序会将未写入的成员解释为值为 0。

如果驱动程序支持DOCUMENTEVENT_QUERYFILTER：

  • 如果 aDocEventCall 数组足够大，足以包含打印机驱动程序打算放入其中的所有 DOCUMENTEVENT_XXX 事件，则打印机驱动程序：

    • 用这些事件填充数组

    • 将 cElementsReturned 成员设置为 (应小于或等于 cElementsAllocated)

    • 使 cElementsNeeded 保持不变

    • 返回DOCUMENTEVENT_SUCCESS

在这种情况下，后台处理程序使用 aDocEventCall 数组中的第一个 cElementsReturned 值。

以特殊方式处理 DOCUMENTEVENT_CREATEDCPRE 事件。 当后台处理程序在 iEsc 参数设置为 DOCUMENTEVENT_CREATEDCPRE 的情况下调用 DrvDocumentEvent 时，后台处理程序将使用返回值来确定将来是否需要对此函数的调用。 与其他 DOCUMENTEVENT_XXX 事件不同，无论是否筛选出此事件，打印机驱动程序始终使用 DOCUMENTEVENT_CREATEDCPRE 接收对 DrvDocumentEvent 的调用。

  • 如果 aDocEventCall 数组不够大，无法包含打印机驱动程序打算放入其中的所有 DOCUMENTEVENT_XXX 事件，打印机驱动程序应：

    • 将 cElementsNeeded 设置为它要响应的事件数 (应大于 cElementsAllocated)

    • 使 cElementsReturned 保持不变

    • 返回DOCUMENTEVENT_SUCCESS

在这种情况下，后台处理程序会分配一个足够大的新缓冲区，然后使用DOCUMENTEVENT_QUERYFILTER再次调用 DrvDocumentEvent 。

如果驱动程序不支持 DOCUMENTEVENT_QUERYFILTER 事件，则应返回DOCUMENTEVENT_UNSUPPORTED。 如果驱动程序支持DOCUMENTEVENT_QUERYFILTER，但在处理此事件时遇到内部错误，则应返回DOCUMENTEVENT_FAILURE。 在任一情况下，后台处理程序都无法从驱动程序中检索事件筛选器，因此它会继续执行针对所有事件调用 DrvDocumentEvent 的行为。

要求

要求 值
Header winddiui.h (包括 Winddiui.h)

另请参阅

DrvDocumentEvent