Función DrvDocumentEvent (winddiui.h)

La función DrvDocumentEvent de una interfaz de impresora DLL puede controlar determinados eventos asociados a la impresión de un documento.

Sintaxis

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

Parámetros

hPrinter

Controlador de impresora suministrado por el autor de la llamada.

hdc

Identificador de contexto del dispositivo proporcionado por el autor de la llamada, generado por un CreateDC Esto es cero si iEsc está establecido en DOCUMENTEVENT_CREATEDCPRE. Para obtener restricciones sobre la impresión desde una aplicación de 32 bits en una versión de 64 bits de Windows, consulte la sección Comentarios a continuación.

iEsc

Código de escape proporcionado por el autor de la llamada que identifica el evento que se va a controlar.

Para obtener restricciones sobre la impresión desde una aplicación de 32 bits en una versión de 64 bits de Windows, consulte la sección Comentarios a continuación.

Este parámetro puede ser una de las siguientes constantes de entero:

Constante iEsc	Evento
DOCUMENTEVENT_ABORTDOC	GDI está a punto de procesar una llamada a su función AbortDoc .
DOCUMENTEVENT_CREATEDCPOST	GDI acaba de procesar una llamada a su función CreateDC o CreateIC . Este código de escape no se debe usar a menos que haya habido una llamada anterior a DrvDocumentEvent con iEsc establecido en DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	GDI está a punto de procesar una llamada a su función CreateDC o CreateIC .
DOCUMENTEVENT_DELETEDC	GDI está a punto de procesar una llamada a su función DeleteDC .
DOCUMENTEVENT_ENDDOCPOST	GDI acaba de procesar una llamada a su función EndDoc .
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	GDI está a punto de procesar una llamada a su función EndDoc .
DOCUMENTEVENT_ENDPAGE	GDI está a punto de procesar una llamada a su función EndPage .
DOCUMENTEVENT_ESCAPE	GDI está a punto de procesar una llamada a su función ExtEscape .
DOCUMENTEVENT_QUERYFILTER	El evento DOCUMENTEVENT_QUERYFILTER representa una oportunidad para que el administrador de cola consulte al controlador una lista de los eventos DOCUMENTEVENT_XXX a los que responderá el controlador. Este evento se emite justo antes de una llamada a DrvDocumentEvent que pasa el evento DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	GDI acaba de procesar una llamada a su función ResetDC . Este código de escape no se debe usar a menos que haya habido una llamada anterior a DrvDocumentEvent con iEsc establecido en DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	GDI está a punto de procesar una llamada a su función ResetDC .
DOCUMENTEVENT_STARTDOCPOST	GDI acaba de procesar una llamada a su función StartDoc .
DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC	GDI está a punto de procesar una llamada a su función StartDoc .
DOCUMENTEVENT_STARTPAGE	GDI está a punto de procesar una llamada a su función StartPage .

cbIn

Tamaño proporcionado por el autor de la llamada, en bytes, del búfer al que apunta pvIn.

[in] pvIn

Puntero proporcionado por el autor de la llamada, el uso del cual depende del valor proporcionado para iEsc, como se indica a continuación:

Constante iEsc	contenido de pvIn
DOCUMENTEVENT_ABORTDOC	No se usa.
DOCUMENTEVENT_CREATEDCPOST	pvIn contiene la dirección de un puntero a la estructura DEVMODEW especificada en el parámetro pvOut en una llamada anterior a esta función, para la que el parámetro iEsc se estableció en DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	pvIn apunta a una estructura de DOCEVENT_CREATEDCPRE .
DOCUMENTEVENT_DELETEDC	No se usa.
DOCUMENTEVENT_ENDDOCPOST	No se usa.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	No se usa.
DOCUMENTEVENT_ENDPAGE	No se usa.
DOCUMENTEVENT_ESCAPE	pvIn apunta a una estructura de DOCEVENT_ESCAPE .
DOCUMENTEVENT_QUERYFILTER	Igual que para DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn contiene la dirección de un puntero a la estructura DEVMODEW especificada en el parámetro pvOut en una llamada anterior a esta función, para la que el parámetro iEsc se estableció en DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	pvIn contiene la dirección de un puntero a la estructura DEVMODEW proporcionada por el autor de la llamada de la función ResetDC .
DOCUMENTEVENT_STARTDOCPOST	pvIn apunta a un LONG que especifica el identificador del trabajo de impresión devuelto por la función StartDoc .
DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC	pvIn contiene la dirección de un puntero a una estructura DOCINFO proporcionada por el autor de la llamada de la función StartDoc .
DOCUMENTEVENT_STARTPAGE	No se usa.

cbOut

Si iEsc es DOCUMENTEVENT_ESCAPE

Valor proporcionado por la función que se usa como parámetro cbOutput para la función ExtEscape .

Si iEsc es DOCUMENTEVENT_QUERYFILTER

Tamaño proporcionado por el autor de la llamada, en bytes, del puntero del búfer a por pvOut.

Para todos los demás valores de iEsc

No se usa.

[out] pvOut

Puntero proporcionado por la función a un búfer de salida, el uso del cual depende del valor proporcionado para iEsc, como se indica a continuación:

Constante iEsc	contenido de pvOut
DOCUMENTEVENT_CREATEDCPRE	Puntero a una estructura DEVMODEW proporcionada por el controlador, que GDI usa en lugar de la proporcionada por el autor de la llamada de CreateDC . (Si es NULL, GDI usa la estructura proporcionada por el autor de la llamada).
DOCUMENTEVENT_ESCAPE	Puntero de búfer que se usa como parámetro lpszOutData para la función ExtEscape .
DOCUMENTEVENT_QUERYFILTER	Puntero proporcionado por el autor de la llamada al búfer que contiene una estructura de DOCEVENT_FILTER .
DOCUMENTEVENT_RESETDCPRE	Puntero a una estructura DEVMODEW proporcionada por el controlador, que GDI usa en lugar de la proporcionada por el autor de llamada de la función ResetDC . (Si es NULL, GDI usa la estructura proporcionada por el autor de la llamada).
Todos los demás valores de iEsc	No se usa.

Valor devuelto

El valor devuelto de la función depende del escape proporcionado para iEsc. Para algunos códigos de escape, no se usa el valor devuelto (vea la segunda lista de valores). Si la función proporciona un valor devuelto, debe ser una de las siguientes:

Código devuelto	Descripción
DOCUMENTEVENT_FAILURE	El controlador admite el código de escape identificado por iEsc, pero se produjo un error.
DOCUMENTEVENT_SUCCESS	El controlador controló correctamente el código de escape identificado por iEsc.
DOCUMENTEVENT_UNSUPPORTED	El controlador no admite el código de escape identificado por iEsc.

Comentarios

Opcionalmente, un archivo DLL de interfaz de impresora puede proporcionar una función DrvDocumentEvent para realizar el preprocesamiento o posprocesamiento de llamadas GDI asociadas con la representación de un documento. Las llamadas a la función DrvDocumentEvent se realizan desde el cliente GDI en modo de usuario, cuando una aplicación realiza llamadas al cliente GDI.

Para un valor iEsc de DOCUMENTEVENT_QUERYFILTER, el administrador de colas puede interpretar un valor de DOCUMENTEVENT_SUCCESS devuelto por DrvDocumentEvent de dos maneras, dependiendo de si el controlador modificó determinados miembros de la estructura de DOCEVENT_FILTER . (El parámetro pvOut apunta a esta estructura). Cuando el administrador de colas asigna memoria para una estructura de este tipo, inicializa dos miembros de esta estructura, cElementsReturned y cElementsNeeded, en valores conocidos. Una vez devuelto DrvDocumentEvent , el administrador determina si los valores de estos miembros han cambiado y usa esa información para interpretar el valor devuelto DrvDocumentEvent . En la tabla siguiente se resume esta situación.

Valor devuelto	Estado de cElementsReturned, cElementsNeeded	Significado
DOCUMENTEVENT_SUCCESS	El controlador no realizó ningún cambio en ninguno de los miembros.	El administrador de cola interpreta este valor devuelto como equivalente a DOCUMENTEVENT_UNSUPPORTED. El administrador de colas no puede recuperar el filtro de eventos del controlador, por lo que persiste en llamar a DrvDocumentEvent para todos los eventos.
DOCUMENTEVENT_SUCCESS	El controlador escribió en uno o ambos miembros.	El administrador de colas acepta este valor devuelto sin interpretación. Si el controlador escribió en solo uno de cElementsNeeded y cElementsReturned, el administrador considera que el miembro sin cambios tiene un valor de cero. El colador filtra todos los eventos enumerados en el miembro aDocEventCall de DOCEVENT_FILTER.
DOCUMENTEVENT_UNSUPPORTED	No aplicable	El controlador no admite DOCUMENTEVENT_QUERYFILTER. El administrador de colas no puede recuperar el filtro de eventos del controlador, por lo que persiste en llamar a DrvDocumentEvent para todos los eventos.
DOCUMENTEVENT_FAILURE	No aplicable	El controlador admite DOCUMENTEVENT_QUERYFILTER, pero encontró un error interno. El administrador de colas no puede recuperar el filtro de eventos del controlador, por lo que persiste en llamar a DrvDocumentEvent para todos los eventos.

Si el nombre del código de escape no tiene sufijo o está sufijo con PRE, el cliente GDI llama a DrvDocumentEvent justo antes de llamar al motor de representación GDI en modo kernel. Si el nombre del código de escape está sufijo con POST, el cliente GDI llama a DrvDocumentEvent justo después de que el motor de representación GDI en modo kernel devuelva.

Si el código de escape proporcionado en el parámetro iEsc es DOCUMENTEVENT_CREATEDCPRE, se aplican las reglas siguientes:

• Si el trabajo se envía directamente a la impresora sin colar, pvIn -> pszDevice apunta al nombre de la impresora. (Consulte la estructura DOCEVENT_CREATEDCPRE para obtener más información).

• Si el trabajo se está colando, pvIn -> pszDevice apunta al nombre del puerto de la impresora.

La función DrvDocumentEvent se ejecuta en el contexto del autor de la llamada en modo de usuario de la función cliente GDI. Cuando la cola de EMF está deshabilitada, la función puede mostrar una interfaz de usuario. Por ejemplo, la función DrvDocumentEvent para un controlador FAX podría mostrar un cuadro de diálogo al usuario antes de que se procese la función StartDoc de GDI.

Las restricciones siguientes se aplican al ejecutar una aplicación de 32 bits en una versión de 64 bits de Windows:

• La única función GDI a la que debe llamar DrvDocumentEvent es ExtEscape y solo se deben usar escapes privados.

• Las llamadas DrvDocumentEvent a otras funciones de GDI pueden producir un comportamiento indefinido.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	winddiui.h (incluya Winddiui.h)

Consulte también

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER