DOCEVENT_FILTER Struktur (winddiui.h)

  • Artikel

Die DOCEVENT_FILTER-Struktur enthält eine Liste von Dokumentereignissen, auf die der Druckertreiber reagiert. Eine vollständige Liste der Dokumentereignisse finden Sie unter DrvDocumentEvent .

Syntax

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

Member

cbSize

Die von Spooler bereitgestellte Größe dieser Struktur in Bytes. Der Spooler initialisiert diesen Member in sizeof(DOCEVENT_FILTER).

cElementsAllocated

Von Spooler bereitgestellte Anzahl von Elementen im Arraymember aDocEventCall . Der Spooler initialisiert dieses Element auf DOCUMENTEVENT_LAST - 1. (Die DOCUMENTEVENT_LAST Konstante wird in der Headerdatei Winddiui.h definiert.)

cElementsNeeded

Vom Treiber bereitgestellte Gesamtanzahl von Elementen, die im Arraymember aDocEventCall benötigt werden. Der Spooler initialisiert dieses Element, um 0XFFFFFFFF. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

cElementsReturned

Vom Treiber bereitgestellte Anzahl von DOCUMENTEVENT_**XXX **-Ereignissen, die er im Arraymember aDocEventCall platziert hat. Der Spooler initialisiert dieses Element, um 0XFFFFFFFF. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

aDocEventCall[ANYSIZE_ARRAY]

Treibergefülltes Array von DWORDs, das alle DOCUMENTEVENT_XXX-Ereignisse auflistet, auf die der Druckertreiber reagiert. Der Spooler initialisiert diesen Member auf 0.

Hinweise

Der Druckertreiber listet die Ereignisse auf, auf die er in der DOCEVENT_FILTER-Struktur reagiert. Da dadurch die Anzahl der Aufrufe des Treibers begrenzt wird, die der Spooler tätigen muss, wird die Druckerleistung verbessert. Wenn der Spooler den DrvDocumentEvent DDI aufruft, dessen iEsc-Parameter auf DOCUMENTEVENT_QUERYFILTER festgelegt ist, weist der Spooler einen Puffer zu, der eine DOCEVENT_FILTER-Struktur enthält, einschließlich des zugehörigen aDocEventCall-Arrays . Die Für den Puffer zugewiesene Arbeitsspeichermenge ist:

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

Nach der Zuweisung eines Puffers, der eine DOCEVENT_FILTER-Struktur enthält, initialisiert der Spooler die Strukturmember mit den folgenden Werten:

Mitglied Initialisiert für
cbSize 0
cElementsAllocated DOCUMENTEVENT_LAST - 1

Die DOCUMENTEVENT_LAST Konstante wird in winddiui.h definiert.
cElementsNeed 0XFFFFFFFF
cElementsReturned 0XFFFFFFFF
aDocEventCall 0

Nachdem der Spooler die Strukturmember mit den werten initialisiert hat, die in der vorherigen Tabelle angezeigt werden, ruft er drvDocumentEvent auf. Wenn diese Funktion zurückgibt, überprüft der Spooler die Elemente cElementsNeeded und cElementsReturned , um festzustellen, ob beides geändert wurde. Wenn der Treiber in eines dieser Member geschrieben hat, aber nicht in das andere, interpretiert der Spooler den ungeschriebenen Member so, dass er den Wert 0 aufweist.

Wenn der Treiber DOCUMENTEVENT_QUERYFILTER unterstützt:

  • Wenn das Array aDocEventCall groß genug ist, um alle DOCUMENTEVENT_XXX-Ereignisse zu enthalten, die der Druckertreiber darin platzieren möchte, wird der Druckertreiber:

    • Füllt das Array mit diesen Ereignissen

    • Legt den cElementsReturned-Member auf diese Anzahl von Ereignissen fest (die kleiner oder gleich cElementsAllocated sein sollte).

    • Lässt cElementsNeeded unverändert

    • Gibt DOCUMENTEVENT_SUCCESS zurück.

In diesem Fall verwendet der Spooler die ersten cElementsReturned-Werte im Array aDocEventCall .

Das DOCUMENTEVENT_CREATEDCPRE-Ereignis wird auf besondere Weise behandelt. Wenn der Spooler DrvDocumentEvent aufruft, wobei der iEsc-Parameter auf DOCUMENTEVENT_CREATEDCPRE festgelegt ist, verwendet der Spooler den Rückgabewert, um zu bestimmen, ob zukünftige Aufrufe dieser Funktion erforderlich sind. Im Gegensatz zu anderen DOCUMENTEVENT_XXX-Ereignissen empfängt der Druckertreiber immer Aufrufe von DrvDocumentEvent mit DOCUMENTEVENT_CREATEDCPRE, unabhängig davon, ob dieses Ereignis herausgefiltert ist oder nicht.

  • Wenn das Array aDocEventCall nicht groß genug ist, um alle DOCUMENTEVENT_XXX-Ereignisse zu enthalten, die der Druckertreiber darin platzieren möchte, sollte der Druckertreiber Folgendes ausführen:

    • Legen Sie cElementsNeeded auf die Anzahl der Ereignisse fest, auf die sie reagieren möchten (die größer als cElementsAllocated sein sollte).

    • Lassen Sie cElementsReturned unverändert.

    • Zurückgeben von DOCUMENTEVENT_SUCCESS

In diesem Fall weist der Spooler dann einen neuen Puffer zu, der ausreichend groß ist, und führt dann einen weiteren Aufruf von DrvDocumentEvent mit DOCUMENTEVENT_QUERYFILTER aus.

Wenn der Treiber das DOCUMENTEVENT_QUERYFILTER-Ereignis nicht unterstützt, sollte er DOCUMENTEVENT_UNSUPPORTED zurückgeben. Wenn der Treiber DOCUMENTEVENT_QUERYFILTER unterstützt, aber bei der Behandlung dieses Ereignisses interne Fehler auftritt, sollte er DOCUMENTEVENT_FAILURE zurückgeben. In beiden Fällen ist der Spooler nicht in der Lage, den Ereignisfilter aus dem Treiber abzurufen, sodass er in seinem Verhalten des Aufrufens von DrvDocumentEvent für alle Ereignisse fortfährt.

Anforderungen

Anforderung Wert
Header winddiui.h (include Winddiui.h)

Weitere Informationen

DrvDocumentEvent