Compartir a través de

Función DocumentEvent

  • Artículo

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]

Controlador de un objeto de impresora. Use la función OpenPrinter o AddPrinter para recuperar un controlador de impresora.

hdc [in]

Controlador de contexto de dispositivo generado por una llamada de CreateDC. 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, 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 de enteros.

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 AbortDoc.
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 AbortDoc.
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 trabajos en cola consulte al controlador para obtener 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 se debe usar a menos que haya habido 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 utilizado.
DOCUMENTEVENT_CREATEDCPOST
 pvIn contiene la dirección de un puntero a la estructura DEVMODE especificada en el parámetro pvOut de 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 utilizado.
DOCUMENTEVENT_ENDDOCPOST
 No utilizado.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC
 No utilizado.
DOCUMENTEVENT_ENDPAGE
 No utilizado.
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 de 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 utilizado.

cbOut

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

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 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 autor de llamada 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 siguiente lista indica qué códigos de escape requieren un valor devuelto y cuáles no, y explica el significado de los códigos devueltos DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE y DOCUMENTEVENT_UNSUPPORTED.

Valor devuelto Significado
DOCUMENTEVENT_ABORTDOC El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_CREATEDCPOST El valor devuelto no se usa y no debe leerse.
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 El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_ENDDOCPOST El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_ENDPAGE El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_ESCAPE El valor devuelto no se usa y no debe leerse.
DOCUMENTEVENT_QUERYFILTER Vea la sección Comentarios.
DOCUMENTEVENT_RESETDCPOST El valor devuelto no se usa y no debe leerse.
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 en cola puede interpretar un valor de DOCUMENTEVENT_SUCCESS devuelto por DocumentEvent de dos maneras, dependiendo de si el controlador modificó determinados miembros de la estructura 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 en cola asigna memoria para una estructura de este tipo, inicializa dos miembros de esta estructura, cElementsReturned y cElementsNeeded, a valores conocidos. Una vez devuelto DocumentEvent, el administrador de trabajos en cola determina si los valores de estos miembros han cambiado y usa esa información para interpretar el valor devuelto 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 en cola interpreta este valor devuelto como equivalente a DOCUMENTEVENT_UNSUPPORTED. El administrador de trabajos en cola no puede recuperar el filtro de eventos del controlador, por lo que persiste al llamar a DocumentEvent para todos los eventos.
DOCUMENTEVENT_SUCCESS
 El controlador escribió a uno o ambos miembros.
 El administrador de trabajos en cola acepta este valor devuelto sin interpretación. Si el controlador escribió solo en uno de los valores cElementsNeeded y cElementsReturned, el administrador de trabajos en cola considera que el miembro sin cambios tiene un valor de cero.
El administrador de trabajos en cola 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 trabajos en cola no puede recuperar el filtro de eventos del controlador, por lo que persiste al llamar a DocumentEvent para todos los eventos.
DOCUMENTEVENT_FAILURE
 No aplicable
 El controlador admite DOCUMENTEVENT_QUERYFILTER, pero encontró un error interno.
El administrador de trabajos en cola no puede recuperar el filtro de eventos del controlador, por lo que persiste al llamar 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 colas, 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á agrupando, 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 que DocumentEvent debe llamar es ExtEscape, y solo se deben usar escapes privados. Las llamadas 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
WinIoCtl.h (incluye Windows.h)
Nombres Unicode y ANSI
 DocumentEventW (Unicode) y DocumentEventA (ANSI)

Consulte también