Función DocumentEvent

Artículo
05/11/2022
Tiempo de lectura: 8 minutos

La función DocumentEvent es un controlador de eventos para eventos asociados a la impresión de un documento.

Sintaxis

HRESULT DocumentEvent(
  _In_  HANDLE hPrinter,
  _In_  HDC    hdc,
        INT    iEsc,
        ULONG  cbIn,
  _In_  PVOID  pvIn,
        ULONG  cbOut,
  _Out_ PVOID  pvOut
);

Parámetros

hPrinter [in]

Identificador de un objeto de impresora. Use la función OpenPrinter o AddPrinter para recuperar un identificador de impresora.

hdc [in]

Identificador de contexto del dispositivo generado por una llamada de CreateDC. Esto es cero si iEsc se establece 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, vea Comentarios.

iEsc

Código de escape que identifica el evento que se va a controlar. Este parámetro puede ser una de las siguientes constantes enteras.

Constante	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 DocumentEvent 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 DocumentEvent 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 debe usarse a menos que se haya realizado una llamada anterior a DocumentEvent 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, en bytes, del búfer al que apunta pvIn.

pvIn [in]

Puntero a un búfer. Lo que contiene el búfer depende del valor de iEsc, como se muestra en la tabla siguiente.

Constante	Contenido de pvin
DOCUMENTEVENT_ABORTDOC	No se usa.
DOCUMENTEVENT_CREATEDCPOST	pvIn contiene la dirección de un puntero a la estructura DEVMODE 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 que se documenta en el kit de desarrollo de controladores de Windows.
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 que se documenta en el kit de desarrollo de controladores de Windows.
DOCUMENTEVENT_QUERYFILTER	Igual que para DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn contiene la dirección de un puntero a la estructura DEVMODE 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 DEVMODE proporcionada por el autor de la llamada de ResetDC.
DOCUMENTEVENT_STARTDOCPOST	pvIn apunta a un LONG que especifica el identificador del trabajo de impresión devuelto por 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 StartDoc.
DOCUMENTEVENT_STARTPAGE	No se usa.

*cbOut*

Valor	Significado
IDOCUMENTEVENT_QUERYFILTER	Tamaño, en bytes, del puntero del búfer a por pvOut.
DOCUMENTEVENT_ESCAPE	Valor que se usa como parámetro cbOutput para ExtEscape.
Para todos los demás valores	iEsc no se usa.

pvOut [out]

Puntero a un búfer. El contenido del búfer depende del valor proporcionado para iEsc, como se muestra en la tabla siguiente.

Constante	contenido de pvOut
DOCUMENTEVENT_CREATEDCPRE	Puntero a una estructura DEVMODE proporcionada por el controlador, que GDI usa en lugar de la proporcionada por el autor de la llamada createDC . (Si es NULL, GDI usa la estructura proporcionada por el autor de la llamada).
DOCUMENTEVENT_ESCAPE	Puntero a un búfer que se usa como parámetro lpszOutData para ExtEscape.
DOCUMENTEVENT_QUERYFILTER	Puntero al búfer que contiene una estructura de DOCEVENT_FILTER que se documenta en el kit de desarrollo de controladores de Windows.
DOCUMENTEVENT_RESETDCPRE	Puntero a una estructura DEVMODE proporcionada por el controlador, que GDI usa en lugar de la proporcionada por el llamador de ResetDC . (Si es NULL, GDI usa la estructura proporcionada por el autor de la llamada).

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 (consulte a continuación). Si la función proporciona un valor devuelto, debe ser uno de los siguientes.

Valor devuelto	Significado
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.

La lista siguiente indica qué códigos de escape requieren un valor devuelto y cuáles no, y explica el significado de la DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE y DOCUMENTEVENT_UNSUPPORTED códigos de retorno.

Valor devuelto	Significado
DOCUMENTEVENT_ABORTDOC	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_CREATEDCPOST	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_CREATEDCPRE	DOCUMENTEVENT_FAILURE: GDI no crea el contexto del dispositivo ni el contexto de información y proporciona un valor devuelto de 0 para CreateDC o CreateIC.
DOCUMENTEVENT_DELETEDC	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_ENDDOCPOST	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_ENDPAGE	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_ESCAPE	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_QUERYFILTER	Vea la sección Comentarios.
DOCUMENTEVENT_RESETDCPOST	No se usa el valor devuelto y no se debe leer.
DOCUMENTEVENT_RESETDCPRE	DOCUMENTEVENT_FAILURE: GDI no restablece el contexto del dispositivo y proporciona un valor devuelto de 0 para ResetDC.
DOCUMENTEVENT_STARTDOCPOST	DOCUMENTEVENT_FAILURE: GDI llama a AbortDoc para detener el documento y, a continuación, proporciona un valor devuelto de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC	DOCUMENTEVENT_FAILURE: GDI no inicia el documento y proporciona un valor devuelto de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTPAGE	DOCUMENTEVENT_FAILURE: GDI no inicia la página y proporciona un valor devuelto de SP_ERROR para StartPage.

Comentarios

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

Valor devuelto	Estado de cElementsReturned y cElementsNeeded	Significado
DOCUMENTEVENT_SUCCESS	El controlador no realizó ningún cambio en ninguno de los miembros.	El administrador de trabajos 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 la llamada a DocumentEvent para todos los eventos.
DOCUMENTEVENT_SUCCESS	Driver escribió a uno o ambos miembros.	El administrador de trabajos 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 administrador de colas filtra todos los eventos enumerados en el miembro aDocEventCall de DOCEVENT_FILTER (que se documenta en el kit de desarrollo de controladores de Windows ).
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 la llamada a DocumentEvent 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 la llamada a DocumentEvent para todos los eventos.

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. (Para obtener más información, consulte la documentación de la estructura de DOCEVENT_CREATEDCPRE en el kit de desarrollo de controladores de Windows).
Si el trabajo se está colando, pvIn-pszDevice> apunta al nombre del puerto de la impresora.

Nota

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 DocumentEvent es ExtEscape y solo se deben usar escapes privados. Las llamadas de DocumentEvent a otras funciones de GDI pueden producir un comportamiento indefinido.

Requisitos

Requisito	Valor
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Encabezado	Winspool.h (include Windows.h)
Nombres Unicode y ANSI	DocumentEventW (Unicode) y DocumentEventA (ANSI)

Vea también

Impresión
Funciones de la API del administrador de trabajos de impresión
Kit de desarrollo de controladores de Windows