estructura DOCEVENT_FILTER (winddiui.h)
La estructura DOCEVENT_FILTER contiene una lista de eventos de documento a los que responderá el controlador de impresora. Consulte DrvDocumentEvent para obtener una lista completa de los eventos de documento.
Sintaxis
typedef struct _DOCEVENT_FILTER {
UINT cbSize;
UINT cElementsAllocated;
UINT cElementsNeeded;
UINT cElementsReturned;
DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;
Miembros
cbSize
Tamaño proporcionado por Spooler, en bytes, de esta estructura. El administrador de cola inicializa este miembro en sizeof(DOCEVENT_FILTER).
cElementsAllocated
Número de elementos proporcionados por Spooler en el miembro de matriz aDocEventCall . El administrador de cola inicializa este miembro en DOCUMENTEVENT_LAST - 1. (La constante DOCUMENTEVENT_LAST se define en el archivo de encabezado Winddiui.h).
cElementsNeeded
Número total de elementos proporcionados por el controlador necesarios en el miembro de matriz aDocEventCall . El administrador de cola inicializa este miembro en 0XFFFFFFFF. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
cElementsReturned
Número proporcionado por el controlador de DOCUMENTEVENT_**XXX **eventos que colocó en el miembro de la matriz aDocEventCall . El administrador de cola inicializa este miembro en 0XFFFFFFFF. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
aDocEventCall[ANYSIZE_ARRAY]
Matriz rellenada por controladores de DWORDs que enumeran todos los eventos DOCUMENTEVENT_XXX a los que responderá el controlador de impresora. El administrador de cola inicializa este miembro en 0.
Comentarios
El controlador de impresora muestra los eventos a los que responderá en la estructura DOCEVENT_FILTER. Dado que esto limita el número de llamadas al controlador, el administrador de colas necesita realizar, se mejora el rendimiento de la impresora. Cuando el administrador de colas realiza una llamada al DDI DrvDocumentEvent con su parámetro iEsc establecido en DOCUMENTEVENT_QUERYFILTER, el administrador de colas asigna un búfer que contiene una estructura de DOCEVENT_FILTER, incluida su matriz aDocEventCall . La cantidad de memoria asignada para el búfer es:
sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)
Después de asignar un búfer que contiene una estructura de DOCEVENT_FILTER, el administrador de cola inicializa los miembros de la estructura en los valores siguientes:
| Miembro | Inicializado en |
|---|---|
| cbSize | 0 |
| cElementsAllocated | DOCUMENTEVENT_LAST - 1 La constante DOCUMENTEVENT_LAST se define en winddiui.h. |
| cElementsNeeded | 0XFFFFFFFF |
| cElementsReturned | 0XFFFFFFFF |
| aDocEventCall | 0 |
Después de inicializar los miembros de la estructura en los valores que se muestran en la tabla anterior, llama a DrvDocumentEvent. Cuando se devuelve esta función, el administrador de trabajos inspecciona los miembros cElementsNeeded y cElementsReturned para ver si se ha cambiado alguna. Si el controlador ha escrito en uno de estos miembros, pero no en el otro, el administrador interpreta al miembro no escrito como que tiene el valor 0.
Si el controlador admite DOCUMENTEVENT_QUERYFILTER:
Si la matriz aDocEventCall es lo suficientemente grande como para contener todos los eventos DOCUMENTEVENT_XXX , el controlador de impresora tiene previsto colocarlo, el controlador de impresora:
Rellena la matriz con esos eventos.
Establece el miembro cElementsReturned en ese número de eventos (que debe ser menor o igual que cElementsAllocated).
Deja cElementsNeed sin cambios
Devuelve DOCUMENTEVENT_SUCCESS
En este caso, el administrador de trabajos usa los primeros valores cElementsReturned en la matriz aDocEventCall .
El evento DOCUMENTEVENT_CREATEDCPRE se trata de forma especial. Cuando el administrador de colas llama a DrvDocumentEvent con el parámetro iEsc establecido en DOCUMENTEVENT_CREATEDCPRE, el administrador de colas usa el valor devuelto para determinar si son necesarias futuras llamadas a esta función. A diferencia de otros eventos DOCUMENTEVENT_XXX , el controlador de impresora siempre recibe llamadas a DrvDocumentEvent con DOCUMENTEVENT_CREATEDCPRE, independientemente de si este evento se filtra o no.
Si la matriz aDocEventCall no es lo suficientemente grande como para contener todos los eventos DOCUMENTEVENT_XXX , el controlador de impresora pretende colocarlo, el controlador de impresora debe:
Establezca cElementsNeeded en el número de eventos a los que pretende responder (que debe ser mayor que cElementsAllocated).
Deje cElementsReturned sin cambios
Devolver DOCUMENTEVENT_SUCCESS
En este caso, el administrador de colas asigna un nuevo búfer suficientemente grande y, a continuación, realiza otra llamada a DrvDocumentEvent con DOCUMENTEVENT_QUERYFILTER.
Si el controlador no admite el evento DOCUMENTEVENT_QUERYFILTER, debe devolver DOCUMENTEVENT_UNSUPPORTED. Si el controlador admite DOCUMENTEVENT_QUERYFILTER, pero encuentra errores internos cuando controla este evento, debe devolver DOCUMENTEVENT_FAILURE. En cualquier caso, el administrador de colas no puede recuperar el filtro de eventos del controlador, por lo que continúa en su comportamiento de llamar a DrvDocumentEvent para todos los eventos.
Requisitos
| Requisito | Valor |
|---|---|
| Header | winddiui.h (incluya Winddiui.h) |