DOCEVENT_FILTER 結構 (winddiui.h)

  • 發行項

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

spooler 提供的 aDocEventCall 陣列成員中的元素數目。 多任務緩衝處理程式會將這個成員初始化為 DOCUMENTEVENT_LAST - 1。 (頭檔 Winddiui.h.) 中定義DOCUMENTEVENT_LAST常數

cElementsNeeded

驅動程式提供的 aDocEventCall 陣列成員中所需的元素總數。 多任務緩衝處理程式會將這個成員初始化為0XFFFFFFFF。 如需詳細資訊，請參閱接下來的＜備註＞一節。

cElementsReturned

驅動程式提供的DOCUMENTEVENT_**XXX **事件數目，會放在 aDocEventCall 陣列成員中。 多任務緩衝處理程式會將這個成員初始化為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事件會以特殊方式處理。 當多任務緩衝處理程式呼叫 DrvDocumentEvent 時， 會將iEsc 參數設定為 DOCUMENTEVENT_CREATEDCPRE，多任務緩衝處理程式會使用傳回值來判斷是否需要未來呼叫此函式。 不同於其他DOCUMENTEVENT_XXX 事件，印表機驅動程式一律會透過 DOCUMENTEVENT_CREATEDCPRE 收到 DrvDocumentEvent 的呼叫，不論此事件是否已篩選掉。

  • 如果 aDocEventCall 陣列不夠大，足以包含印表機驅動程式想要放置的所有DOCUMENTEVENT_XXX 事件，印表機驅動程序應該：

    • 將 cElementsNeeded 設定為其想要回應的事件數目， (應該大於 cElementsAllocated)

    • 讓 cElementsReturn 保持不變

    • 傳回DOCUMENTEVENT_SUCCESS

在此情況下，多任務緩衝處理接著會配置夠大的新緩衝區，然後使用 DOCUMENTEVENT_QUERYFILTER呼叫 DrvDocumentEvent 。

如果驅動程式不支援DOCUMENTEVENT_QUERYFILTER事件，它應該會傳回DOCUMENTEVENT_UNSUPPORTED。 如果驅動程式支援DOCUMENTEVENT_QUERYFILTER，但在處理此事件時遇到內部錯誤，它應該會傳回DOCUMENTEVENT_FAILURE。 不論是哪一種情況，多任務緩衝處理程式都無法從驅動程式擷取事件篩選條件，因此它會繼續在所有事件呼叫 DrvDocumentEvent 的行為中。

規格需求

需求 值
標頭 winddiui.h (包含Winddiui.h)

另請參閱

DrvDocumentEvent