Método IPrintOemUI2::D ocumentEvent (prcomoem.h)

Artículo
02/07/2025

El método IPrintOemUI2::DocumentEvent permite que un complemento de interfaz de usuario reemplace la implementación predeterminada del módulo de interfaz de usuario del controlador principal de la DrvDocumentEvent DDI.

Sintaxis

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

Parámetros

hPrinter

Controlador de impresora proporcionado por el autor de la llamada.

hdc

Identificador de contexto de dispositivo proporcionado por el autor de la llamada, generado por una llamada CreateDC. Esto es cero si iEsc es DOCUMENTEVENT_CREATEDCPRE.

iEsc

Código de escape proporcionado por el autor de la llamada que identifica el evento que se va a controlar. Este parámetro puede ser una de las siguientes constantes de entero:

Código de escape	Significado
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 CreateDC o función 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 CreateDC o función CreateIC.
DOCUMENTEVENT_DELETEDC	GDI está a punto de procesar una llamada a su función de 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 colador consulte al controlador una lista de los eventosxxx de 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 de 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.

pvIn

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

constante de 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 se estableció en DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	pvIn apunta a una estructura 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 se estableció en DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	pvIn contiene la dirección de un puntero a una estructura de DEVMODEW proporcionada por el autor de la llamada de ResetDC (que se describe en la documentación del SDK de Microsoft Windows).
DOCUMENTEVENT_STARTDOCPOST	pvIn apunta a un LONG que especifica el identificador de trabajo de impresión devuelto por startDoc (que se describe en la documentación de Windows SDK).
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 (ambos descritos en la documentación de Windows SDK).
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 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.

pvOut

Puntero proporcionado por la función a un búfer de salida, cuyo uso depende del valor proporcionado para iEsc, como se indica a continuación. CreateDC, ExtEscapey ResetDC se describen en la documentación de Windows SDK.

constante de 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 CreateDC llamador. (Si null, GDI usa la estructura proporcionada por el autor de la llamada).
DOCUMENTEVENT_ESCAPE	Puntero de búfer que se usa como parámetro de lpszOutData para 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 ResetDC llamador. (Si null, GDI usa la estructura proporcionada por el autor de la llamada).
Todos los demás valores de iEsc	No se usa.

piResult

Puntero a una ubicación de memoria que recibe uno de los siguientes valores:

Valor devuelto	Definició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. Consulte también la sección Comentarios para obtener más información.
DOCUMENTEVENT_UNSUPPORTED	El controlador no admite el código de escape identificado por iEsc.

Valor devuelto

Este método debe devolver uno de los siguientes valores. Consulte la sección Comentarios para obtener más información.

Código devuelto	Descripción
S_OK	El complemento de interfaz de usuario implementa este método.
E_NOTIMPL	El complemento de interfaz de usuario no implementa este método.

Observaciones

El método IPrintOemUI2::DocumentEvent de un complemento de interfaz de usuario realiza los mismos tipos de operaciones que el DDI DrvDocumentEvent que exporta los archivos DLL de la interfaz de impresora en modo de usuario. Para obtener información sobre los eventos de documento y cómo se deben procesar, consulte la descripción de la DrvDocumentEvent DDI.

Si proporciona un complemento de interfaz de usuario, drvDocumentEvent DDI del controlador de impresora llama al método IPrintOemUI2::DocumentEvent. DrvDocumentEvent DDI realiza su propio procesamiento para el evento especificado y, a continuación, llama al método IPrintOemUI2::DocumentEvent para controlar el procesamiento adicional del evento.

Cuando se llama a este método con un valor del parámetro iEsc de DOCUMENTEVENT_QUERYFILTER y devuelve con *piResult == DOCUMENTEVENT_SUCCESS, el colador puede interpretar este valor de dos maneras, dependiendo de si determinados miembros de la estructura DOCEVENT_FILTER cambiaron valores. Para obtener más información, vea la sección Comentarios de DrvDocumentEvent.

Cuando se desencadena el evento DOCUMENTEVENT_QUERYFILTER, el controlador principal llama a complementos en el orden en que se instalaron, hasta que uno de ellos devuelve S_OK, o hasta que se haya llamado a todos los complementos y ninguno de ellos devuelva S_OK. De este modo, se permite al máximo un complemento controlar el evento DOCUMENTEVENT_QUERYFILTER y el filtro que especifica se aplica a todos los complementos de la cadena del complemento.

Para un escritor de complementos que implemente la interfaz IPrintOemUI2, pero no es necesario admitir el método IPrintOemUI2::DocumentEvent, este método debe devolver E_NOTIMPL para todos los valores de iEsc. Si necesita implementar este método, debe devolver S_OK para todos los valores de iEsc. Esto indica al controlador principal que este método ha controlado el evento pertinente. El controlador principal usa el valor que este método coloca en piResult como valor devuelto del DrvDocumentEvent DDI.