DOCEVENT_FILTER Struktur (winddiui.h)
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;
Angehörige
cbSize
Spooler-bereitgestellte Größe in Bytes dieser Struktur. Der Pooler initialisiert dieses Element in Größe von(DOCEVENT_FILTER).
cElementsAllocated
Spooler-bereitgestellte Anzahl von Elementen im aDocEventCall Arraymemm. Der Spooler initialisiert dieses Element in DOCUMENTEVENT_LAST - 1. (Die DOCUMENTEVENT_LAST Konstante wird in der Headerdatei Winddiui.h.)
cElementsNeeded
Die vom Treiber bereitgestellte Gesamtanzahl der elemente, die im aDocEventCall Arraymemm erforderlich sind. Der Spooler initialisiert dieses Element in 0XFFFFFFFF. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
cElementsReturned
Die vom Treiber bereitgestellte Anzahl von DOCUMENTEVENT_**XXX **-Ereignissen, die im aDocEventCall Arraymemm platziert wurden. Der Spooler initialisiert dieses Element in 0XFFFFFFFF. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
aDocEventCall[ANYSIZE_ARRAY]
Das vom Treiber gefüllte Array von DWORDs listet alle DOCUMENTEVENT_XXX- Ereignisse auf, auf die der Druckertreiber reagiert. Der Spooler initialisiert dieses Element auf 0.
Bemerkungen
Der Druckertreiber listet die Ereignisse auf, auf die er in der DOCEVENT_FILTER Struktur reagiert. Da dadurch die Anzahl der Aufrufe an den Treiber begrenzt wird, die der Spooler vornehmen muss, wird die Druckerleistung verbessert. Wenn der Spooler einen Aufruf des DrvDocumentEvent- DDI mit dem auf DOCUMENTEVENT_QUERYFILTER festgelegten iEsc Parameter vorgibt, weist der Spooler einen Puffer zu, der eine DOCEVENT_FILTER Struktur enthält, einschließlich des aDocEventCall Arrays. Die für den Puffer zugewiesene Arbeitsspeichermenge lautet:
sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)
Nach dem Zuordnen 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. |
| cElementsNeeded- | 0XFFFFFFFF |
| cElementsReturned | 0XFFFFFFFF |
| aDocEventCall- | 0 |
Nachdem der Spooler die Strukturmmber in den Werten initialisiert hat, die in der vorherigen Tabelle angezeigt werden, wird dann DrvDocumentEventaufgerufen. Wenn diese Funktion zurückgegeben wird, prüft der Spooler die cElementsNeededed und cElementsReturned Member, um festzustellen, ob eine der Elemente geändert wurde. Wenn der Treiber in eines dieser Member geschrieben wurde, aber nicht in den anderen, interpretiert der Spooler das nicht geschriebene Element als den Wert 0.
Wenn der Treiber DOCUMENTEVENT_QUERYFILTER unterstützt:
Wenn das aDocEventCall Array 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 aus.
Legt den cElementsReturned Member auf diese Anzahl von Ereignissen fest (die kleiner oder gleich cElementsAllocatedsein sollte)
Lässt cElementsNeeded unverändert
Gibt DOCUMENTEVENT_SUCCESS zurück.
In diesem Fall verwendet der Spooler die ersten cElementsReturned Werte im aDocEventCall Array.
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 an DrvDocumentEvent- mit DOCUMENTEVENT_CREATEDCPRE, unabhängig davon, ob dieses Ereignis herausgefiltert wird.
Wenn das aDocEventCall- Array 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 cElementsNeededed- auf die Anzahl der Ereignisse fest, auf die sie reagieren möchten (die größer als cElementsAllocated)
Lassen Sie cElementsReturned unverändert
DOCUMENTEVENT_SUCCESS zurückgeben
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 es DOCUMENTEVENT_UNSUPPORTED zurückgeben. Wenn der Treiber DOCUMENTEVENT_QUERYFILTER unterstützt, aber beim Behandeln dieses Ereignisses interne Fehler auftritt, sollte er DOCUMENTEVENT_FAILURE zurückgeben. In beiden Fällen kann der Spooler den Ereignisfilter nicht vom Treiber abrufen, sodass er im Verhalten des Aufrufs DrvDocumentEvent- für alle Ereignisse fortgesetzt wird.
Anforderungen
| Anforderung | Wert |
|---|---|
| Header- | winddiui.h (include Winddiui.h) |