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 del 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 para tamaño de(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 en el miembro de matriz aDocEventCall. El administrador de cola inicializa este miembro en 0XFFFFFFFF. Para obtener más información, vea la siguiente sección Comentarios.
cElementsReturned
Número proporcionado por el controlador de DOCUMENTEVENT_**XXX **eventos que colocó en el miembro de matriz aDocEventCall. El administrador de cola inicializa este miembro en 0XFFFFFFFF. Para obtener más información, vea la siguiente sección Comentarios.
aDocEventCall[ANYSIZE_ARRAY]
Matriz rellenada por controladores de DWORDs que enumeran todos los eventos de DOCUMENTEVENT_XXX a los que responderá el controlador de impresora. El administrador de cola inicializa este miembro en 0.
Observaciones
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 que necesita realizar el administrador, se mejora el rendimiento de la impresora. Cuando el administrador de cola realiza una llamada a la DrvDocumentEvent DDI con su parámetro iEsc establecido en DOCUMENTEVENT_QUERYFILTER, el administrador 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 colas inspecciona el cElementsNeeded y miembros de cElementsReturned para ver si se ha cambiado alguna de estas. Si el controlador ha escrito en uno de estos miembros, pero no en el otro, el administrador interpreta el miembro no escrito en como que tiene el valor 0.
Si el controlador admite DOCUMENTEVENT_QUERYFILTER:
Si el matriz aDocEventCall es lo suficientemente grande como para contener todos los eventos de DOCUMENTEVENT_XXX que el controlador de impresora pretende colocar en él, 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 cElementsNeeded sin cambios
Devuelve DOCUMENTEVENT_SUCCESS
En este caso, el administrador de trabajos usa los primeros valores de cElementsReturned de 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 es necesario realizar llamadas futuras a esta función. A diferencia de otros eventos deXXX de DOCUMENTEVENT_ XXX, el controlador de impresora siempre recibe llamadas a drvDocumentEvent con DOCUMENTEVENT_CREATEDCPRE, si este evento se filtra o no.
Si el matriz aDocEventCall no es lo suficientemente grande como para contener todos los eventos de DOCUMENTEVENT_XXX que el controlador de impresora pretende colocar en él, 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 trabajos asigna un nuevo búfer que es lo 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 |
|---|---|
| encabezado de | winddiui.h (incluya Winddiui.h) |