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

Artículo
02/27/2024

El IPrintOemUI2::DocumentEvent método permite que un complemento de interfaz de usuario reemplace la implementación predeterminada del módulo de interfaz de usuario del controlador principal de 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 del 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 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 colas 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.

pvIn

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

iEsc Constante	pvIn Contenido
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 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 .
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 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 una estructura DEVMODEW proporcionada por el autor de la llamada de ResetDC (que se describe en la documentación de Microsoft Windows SDK).
DOCUMENTEVENT_STARTDOCPOST	pvIn apunta a un LONG que especifica el identificador del trabajo de impresión devuelto por StartDoc (descrito 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 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, ExtEscape y ResetDC se describen en la documentación de Windows SDK.

iEsc Constante	pvOut Contenido
DOCUMENTEVENT_CREATEDCPRE	Puntero a una estructura DEVMODEW proporcionada por el controlador, que GDI usa en lugar de la proporcionada por el llamador 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 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 llamador de 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.

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 valores siguientes. Vea 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.

Comentarios

El método de un complemento de interfaz de IPrintOemUI2::DocumentEvent usuario realiza los mismos tipos de operaciones que la 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 DrvDocumentEvent DDI.

Si proporciona un complemento de interfaz de usuario, drvDocumentEvent DDI del controlador de impresora llama al IPrintOemUI2::DocumentEvent método . DrvDocumentEvent DDI realiza su propio procesamiento para el evento especificado y, a continuación, llama al método para controlar el IPrintOemUI2::DocumentEvent 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 administrador de colas puede interpretar este valor de dos maneras, dependiendo de si determinados miembros de la estructura de 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 los 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, como máximo un complemento puede controlar el evento de DOCUMENTEVENT_QUERYFILTER y el filtro que especifica se aplica a todos los complementos de la cadena de complementos.

Para un escritor de complementos que implementa la interfaz IPrintOemUI2 , pero no necesita admitir el IPrintOemUI2::DocumentEvent método , 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 para drvDocumentEvent DDI.