structure DOCEVENT_FILTER (winddiui.h)
La structure DOCEVENT_FILTER contient une liste d’événements de document auxquels le pilote d’imprimante répond. Consultez DrvDocumentEvent pour obtenir la liste complète des événements de document.
Syntaxe
typedef struct _DOCEVENT_FILTER {
UINT cbSize;
UINT cElementsAllocated;
UINT cElementsNeeded;
UINT cElementsReturned;
DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;
Membres
cbSize
Taille fournie par le spouleur, en octets, de cette structure. Le spouleur initialise ce membre pour taille de(DOCEVENT_FILTER).
cElementsAllocated
Nombre d’éléments fournis par le spouleur dans le membre de tableau aDocEventCall. Le spouleur initialise ce membre à DOCUMENTEVENT_LAST - 1. (La constante DOCUMENTEVENT_LAST est définie dans le fichier d’en-tête Winddiui.h.)
cElementsNeeded
Nombre total d’éléments fournis par le pilote requis dans le membre de tableau aDocEventCall. Le spouleur initialise ce membre à 0XFFFFFFFF. Pour plus d’informations, consultez la section Remarques suivante.
cElementsReturned
Nombre d’événements DOCUMENTEVENT_**XXX **XXX qu’il a placés dans le membre de tableau aDocEventCall. Le spouleur initialise ce membre à 0XFFFFFFFF. Pour plus d’informations, consultez la section Remarques suivante.
aDocEventCall[ANYSIZE_ARRAY]
Tableau rempli de pilotes de DWORD répertoriant tous les événements DOCUMENTEVENT_XXX auxquels le pilote d’imprimante répond. Le spouleur initialise ce membre à 0.
Remarques
Le pilote d’imprimante répertorie les événements auxquels il répondra dans la structure DOCEVENT_FILTER. Étant donné que cela limite le nombre d’appels au pilote que le spouleur doit effectuer, les performances de l’imprimante sont améliorées. Lorsque le spouleur effectue un appel au DrvDocumentEvent DDI avec son paramètre iEsc défini sur DOCUMENTEVENT_QUERYFILTER, le spouleur alloue une mémoire tampon qui contient une structure DOCEVENT_FILTER, y compris son tableau aDocEventCall. La quantité de mémoire allouée pour la mémoire tampon est la suivante :
sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)
Après avoir alloué une mémoire tampon qui contient une structure DOCEVENT_FILTER, le spouleur initialise les membres de la structure aux valeurs suivantes :
| Membre | Initialisé à |
|---|---|
| cbSize | 0 |
| cElementsAllocated | DOCUMENTEVENT_LAST - 1 La constante DOCUMENTEVENT_LAST est définie dans winddiui.h. |
| cElementsNeeded | 0XFFFFFFFF |
| cElementsReturned | 0XFFFFFFFF |
| aDocEventCall | 0 |
Une fois que le spouleur a initialisé les membres de la structure sur les valeurs indiquées dans le tableau précédent, il appelle ensuite DrvDocumentEvent. Lorsque cette fonction est retournée, le spouleur inspecte les membres cElementsNeeded et cElementsReturned membres pour voir si l’un ou l’autre a été modifié. Si le pilote a écrit dans l’un de ces membres, mais pas l’autre, le spouleur interprète le membre non écrit comme ayant la valeur 0.
Si le pilote prend en charge DOCUMENTEVENT_QUERYFILTER :
Si le tableau aDocEventCall est suffisamment grand pour contenir tous les événements DOCUMENTEVENT_XXX que le pilote d’imprimante a l’intention de placer dans celui-ci, le pilote d’imprimante :
Remplit le tableau avec ces événements
Définit le membre cElementsReturned sur ce nombre d’événements (qui doivent être inférieurs ou égaux à cElementsAllocated)
Feuilles cElementsNeeded inchangé
Retourne DOCUMENTEVENT_SUCCESS
Dans ce cas, le spouleur utilise les premières valeurs cElementsReturned dans le tableau aDocEventCall.
L’événement DOCUMENTEVENT_CREATEDCPRE est traité d’une manière spéciale. Lorsque le spouleur appelle DrvDocumentEvent avec le paramètre iEsc défini sur DOCUMENTEVENT_CREATEDCPRE, le spouleur utilise la valeur de retour pour déterminer si les appels futurs à cette fonction sont nécessaires. Contrairement à d’autres événements DOCUMENTEVENT_XXX, le pilote d’imprimante reçoit toujours des appels à DrvDocumentEvent avec DOCUMENTEVENT_CREATEDCPRE, que cet événement soit filtré ou non.
Si le tableau aDocEventCall n’est pas suffisamment grand pour contenir tous les événements DOCUMENTEVENT_XXX que le pilote d’imprimante a l’intention de placer dans celui-ci, le pilote d’imprimante doit :
Définissez cElementsNeeded sur le nombre d’événements auxquels il a l’intention de répondre (qui doit être supérieur à cElementsAllocated)
Laissez cElementsReturned inchangé
Retourner DOCUMENTEVENT_SUCCESS
Dans ce cas, le spouleur alloue ensuite une nouvelle mémoire tampon suffisamment volumineuse, puis effectue un autre appel à DrvDocumentEvent avec DOCUMENTEVENT_QUERYFILTER.
Si le pilote ne prend pas en charge l’événement DOCUMENTEVENT_QUERYFILTER, il doit retourner DOCUMENTEVENT_UNSUPPORTED. Si le pilote prend en charge DOCUMENTEVENT_QUERYFILTER, mais rencontre des erreurs internes lorsqu’il gère cet événement, il doit retourner DOCUMENTEVENT_FAILURE. Dans les deux cas, le spouleur n’est pas en mesure de récupérer le filtre d’événements du pilote. Il continue donc son comportement d’appel DrvDocumentEvent pour tous les événements.
Exigences
| Exigence | Valeur |
|---|---|
| d’en-tête | winddiui.h (include Winddiui.h) |