structure DOCEVENT_FILTER (winddiui.h)

La structure DOCEVENT_FILTER contient une liste d’événements de document auxquels le pilote d’imprimante répondra. Pour obtenir la liste complète des événements de document, consultez DrvDocumentEvent .

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 sur sizeof(DOCEVENT_FILTER).

cElementsAllocated

Nombre d’éléments fournis par le spouleur dans le membre du tableau aDocEventCall . Le spouleur initialise ce membre en 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 nécessaires dans le membre du tableau aDocEventCall . Le spouleur initialise ce membre pour 0XFFFFFFFF. Pour plus d'informations, consultez la section Notes qui suit.

cElementsReturned

Nombre d’événements DOCUMENTEVENT_**XXX ** fournis par le pilote qu’il a placés dans le membre du tableau aDocEventCall . Le spouleur initialise ce membre pour 0XFFFFFFFF. Pour plus d'informations, consultez la section Notes qui suit.

aDocEventCall[ANYSIZE_ARRAY]

Tableau de DWORD remplis par le pilote répertoriant tous les événements DOCUMENTEVENT_XXX auxquels le pilote d’imprimante répondra. Le spouleur initialise ce membre sur 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 à la DDI DrvDocumentEvent 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 à 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 :

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 pour voir si l’un ou l’autre a été modifié. Si le pilote a écrit dans l’un de ces membres, mais pas dans 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 d’y placer, le pilote d’imprimante :

  • Remplit le tableau avec ces événements

  • Définit le membre cElementsReturned sur ce nombre d’événements (qui doit être inférieur ou égal à cElementsAllocated)

  • Laisse cElementsNeed 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é de 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 assez grand pour contenir tous les événements DOCUMENTEVENT_XXX que le pilote d’imprimante a l’intention d’y placer, 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é

  • Retour 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 qu’il rencontre des erreurs internes lorsqu’il gère cet événement, il doit retourner DOCUMENTEVENT_FAILURE. Dans les deux cas, le spouleur n’étant pas en mesure de récupérer le filtre d’événements à partir du pilote, il continue dans son comportement d’appeler DrvDocumentEvent pour tous les événements.

Configuration requise

Voir aussi

DrvDocumentEvent