struttura DOCEVENT_FILTER (winddiui.h)

  • Articolo

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)

Vedi anche

DrvDocumentEvent