estrutura DOCEVENT_FILTER (winddiui.h)

A estrutura DOCEVENT_FILTER contém uma lista de eventos de documento aos quais o driver da impressora responderá. Consulte DrvDocumentEvent para obter uma lista completa dos eventos do documento.

Sintaxe

typedef struct _DOCEVENT_FILTER {
  UINT  cbSize;
  UINT  cElementsAllocated;
  UINT  cElementsNeeded;
  UINT  cElementsReturned;
  DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;

Membros

cbSize

Tamanho fornecido pelo spooler, em bytes, dessa estrutura. O spooler inicializa esse membro para sizeof(DOCEVENT_FILTER).

cElementsAllocated

Número de elementos fornecidos pelo spooler no membro da matriz aDocEventCall . O spooler inicializa esse membro para DOCUMENTEVENT_LAST - 1. (A constante DOCUMENTEVENT_LAST é definida no arquivo de cabeçalho Winddiui.h.)

cElementsNeeded

Número total de elementos necessários no membro da matriz aDocEventCall fornecido pelo driver. O spooler inicializa esse membro para 0XFFFFFFFF. Para obter mais informações, consulte a seção Comentários a seguir.

cElementsReturned

Número fornecido pelo driver de eventos DOCUMENTEVENT_**XXX **que ele colocou no membro da matriz aDocEventCall . O spooler inicializa esse membro para 0XFFFFFFFF. Para obter mais informações, consulte a seção Comentários a seguir.

aDocEventCall[ANYSIZE_ARRAY]

Matriz de DWORDs preenchida pelo driver listando todos os eventos DOCUMENTEVENT_XXX aos quais o driver da impressora responderá. O spooler inicializa esse membro como 0.

Comentários

O driver da impressora lista os eventos aos quais ele responderá na estrutura DOCEVENT_FILTER. Como isso limita o número de chamadas para o driver que o spooler precisa fazer, o desempenho da impressora é aprimorado. Quando o spooler faz uma chamada para o DDI DrvDocumentEvent com seu parâmetro iEsc definido como DOCUMENTEVENT_QUERYFILTER, o spooler aloca um buffer que contém uma estrutura DOCEVENT_FILTER, incluindo sua matriz aDocEventCall . A quantidade de memória alocada para o buffer é:

sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)

Depois de alocar um buffer que contém uma estrutura DOCEVENT_FILTER, o spooler inicializa os membros da estrutura com os seguintes valores:

Membro	Inicializado para
cbSize	0
cElementsAllocated	DOCUMENTEVENT_LAST - 1 A constante DOCUMENTEVENT_LAST é definida em winddiui.h.
cElementsNeeded	0XFFFFFFFF
cElementsReturned	0XFFFFFFFF
aDocEventCall	0

Depois que o spooler inicializar os membros da estrutura para os valores mostrados na tabela anterior, ele chamará DrvDocumentEvent. Quando essa função retorna, o spooler inspeciona os membros cElementsNeeded e cElementsReturned para ver se algum deles foi alterado. Se o driver tiver gravado em um desses membros, mas não no outro, o spooler interpretará o membro não escrito como tendo o valor 0.

Se o driver der suporte a DOCUMENTEVENT_QUERYFILTER:

• Se a matriz aDocEventCall for grande o suficiente para conter todos os eventos DOCUMENTEVENT_XXX que o driver da impressora pretende colocar nele, o driver da impressora:

  • Preenche a matriz com esses eventos

  • Define o membro cElementsReturned para esse número de eventos (que devem ser menores ou iguais a cElementsAllocated)

  • Deixa cElementsNeeded inalterado

  • Retorna DOCUMENTEVENT_SUCCESS

Nesse caso, o spooler usa os primeiros valores cElementsReturned na matriz aDocEventCall .

O evento DOCUMENTEVENT_CREATEDCPRE é tratado de maneira especial. Quando o spooler chama DrvDocumentEvent com o parâmetro iEsc definido como DOCUMENTEVENT_CREATEDCPRE, o spooler usa o valor retornado para determinar se chamadas futuras para essa função são necessárias. Ao contrário de outros eventos DOCUMENTEVENT_XXX , o driver de impressora sempre recebe chamadas para DrvDocumentEvent com DOCUMENTEVENT_CREATEDCPRE, independentemente de esse evento ser filtrado ou não.

• Se a matriz aDocEventCall não for grande o suficiente para conter todos os eventos DOCUMENTEVENT_XXX que o driver da impressora pretende colocar nele, o driver da impressora deverá:

  • Defina cElementsNeeded como o número de eventos aos quais ele pretende responder (que deve ser maior que cElementsAllocated)

  • Deixar cElementsReturned inalterado

  • Retornar DOCUMENTEVENT_SUCCESS

Nesse caso, o spooler aloca um novo buffer suficientemente grande e, em seguida, faz outra chamada para DrvDocumentEvent com DOCUMENTEVENT_QUERYFILTER.

Se o driver não der suporte ao evento DOCUMENTEVENT_QUERYFILTER, ele deverá retornar DOCUMENTEVENT_UNSUPPORTED. Se o driver der suporte a DOCUMENTEVENT_QUERYFILTER, mas encontrar erros internos ao manipular esse evento, ele deverá retornar DOCUMENTEVENT_FAILURE. Em ambos os casos, o spooler não é capaz de recuperar o filtro de eventos do driver, portanto, ele continua em seu comportamento de chamar DrvDocumentEvent para todos os eventos.

Requisitos

Requisito	Valor
Cabeçalho	winddiui.h (inclua Winddiui.h)

Confira também

DrvDocumentEvent