struttura DOCEVENT_FILTER (winddiui.h)
La struttura DOCEVENT_FILTER contiene un elenco di eventi del documento a cui risponderà il driver della stampante. Per un elenco completo degli eventi del documento, vedere DrvDocumentEvent .
Sintassi
typedef struct _DOCEVENT_FILTER {
UINT cbSize;
UINT cElementsAllocated;
UINT cElementsNeeded;
UINT cElementsReturned;
DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;
Members
cbSize
Dimensioni fornite da Spooler, in byte, di questa struttura. Il spooler inizializza questo membro a sizeof(DOCEVENT_FILTER).
cElementsAllocated
Numero di elementi fornito da Spooler nel membro matrice aDocEventCall . Il spooler inizializza questo membro in DOCUMENTEVENT_LAST - 1. La costante DOCUMENTEVENT_LAST è definita nel file di intestazione Winddiui.h.)
cElementsNeeded
Numero totale fornito dal driver di elementi necessari nel membro matrice aDocEventCall . Il spooler inizializza questo membro in 0XFFFFFFFF. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
cElementsReturned
Numero fornito dal driver di DOCUMENTEVENT_**XXX **eventi inseriti nel membro matrice aDocEventCall . Il spooler inizializza questo membro in 0XFFFFFFFF. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
aDocEventCall[ANYSIZE_ARRAY]
Matrice compilata con driver di DWORD che elenca tutti gli eventi DOCUMENTEVENT_ XXX a cui risponderà il driver della stampante. Il spooler inizializza questo membro su 0.
Commenti
Il driver della stampante elenca gli eventi a cui risponderà nella struttura DOCEVENT_FILTER. Poiché questo limita il numero di chiamate al driver che il spooler deve eseguire, le prestazioni della stampante sono migliorate. Quando lo spooler effettua una chiamata al DDI DrvDocumentEvent con il relativo parametro iEsc impostato su DOCUMENTEVENT_QUERYFILTER, lo spooler alloca un buffer che contiene una struttura DOCEVENT_FILTER, inclusa la matrice aDocEventCall . La quantità di memoria allocata per il buffer è:
sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)
Dopo aver allocato un buffer contenente una struttura di DOCEVENT_FILTER, lo spooler inizializza i membri della struttura ai valori seguenti:
| Membro | Inizializzato in |
|---|---|
| cbSize | 0 |
| cElementsAllocated | DOCUMENTEVENT_LAST - 1 La costante DOCUMENTEVENT_LAST è definita in winddiui.h. |
| cElementsNeeded | 0XFFFFFFFF |
| cElementsReturned | 0XFFFFFFFF |
| aDocEventCall | 0 |
Dopo che lo spooler ha inizializzato i membri della struttura ai valori visualizzati nella tabella precedente, quindi chiama DrvDocumentEvent. Quando questa funzione restituisce, lo spooler controlla i membri cElementsNeeded e cElementsReturned per verificare se è stata modificata una delle due funzioni. Se il driver ha scritto in uno di questi membri, ma non l'altro, lo spooler interpreta il membro non scritto come con il valore 0.
Se il driver supporta DOCUMENTEVENT_QUERYFILTER:
Se la matrice aDocEventCall è sufficiente per contenere tutti gli eventi DOCUMENTEVENT_ XXX, il driver della stampante intende inserirlo, il driver della stampante:
Riempie la matrice con tali eventi
Imposta il membro cElementsReturned su tale numero di eventi (che deve essere minore o uguale a cElementsAllocated)
Foglie cElementsNeed invariate
Restituisce DOCUMENTEVENT_SUCCESS
In questo caso, lo spooler usa i primi valori cElementsReturned nella matrice aDocEventCall .
L'evento DOCUMENTEVENT_CREATEDCPRE viene trattato in modo speciale. Quando il spooler chiama DrvDocumentEvent con il parametro iEsc impostato su DOCUMENTEVENT_CREATEDCPRE, lo spooler usa il valore restituito per determinare se sono necessarie chiamate future a questa funzione. A differenza di altri eventi DOCUMENTEVENT_XXX , il driver della stampante riceve sempre chiamate a DrvDocumentEvent con DOCUMENTEVENT_CREATEDCPRE, indipendentemente dal fatto che questo evento venga filtrato o meno.
Se la matrice aDocEventCall non è sufficiente per contenere tutti gli eventi DOCUMENTEVENT_ XXX, il driver della stampante intende inserirlo, il driver della stampante deve:
Impostare cElementsNeeded sul numero di eventi a cui intende rispondere (che deve essere maggiore di cElementsAllocated)
Lasciare invariato cElementsReturned
Restituire DOCUMENTEVENT_SUCCESS
In questo caso, lo spooler alloca quindi un nuovo buffer sufficientemente grande e quindi effettua un'altra chiamata a DrvDocumentEvent con DOCUMENTEVENT_QUERYFILTER.
Se il driver non supporta l'evento DOCUMENTEVENT_QUERYFILTER, deve restituire DOCUMENTEVENT_UNSUPPORTED. Se il driver supporta DOCUMENTEVENT_QUERYFILTER, ma rileva errori interni quando gestisce questo evento, deve restituire DOCUMENTEVENT_FAILURE. In entrambi i casi, lo spooler non è in grado di recuperare il filtro evento dal driver, quindi continua nel comportamento di chiamare DrvDocumentEvent per tutti gli eventi.
Requisiti
| Requisito | Valore |
|---|---|
| Intestazione | winddiui.h (include Winddiui.h) |