Compartir a través de

Eventos de documento del controlador XPS

  • Artículo

Importante

La plataforma de impresión moderna es el medio preferido de Windows para comunicarse con impresoras. Se recomienda usar el controlador de clase de bandeja de entrada IPP de Microsoft, junto con aplicaciones de soporte técnico de impresión (PSA), para personalizar la experiencia de impresión en Windows 10 y 11 para el desarrollo de dispositivos de impresora.

Para obtener más información, consulte Plataforma de impresión moderna y la Guía de diseño de aplicaciones para compatibilidad con impresión.

La compatibilidad con impresión de Microsoft Windows Presentation Foundation (WPF) envía eventos de notificación de controladores de impresión XPSDrv durante la cola de documentos de forma similar a cómo la compatibilidad con impresión GDI envía notificaciones a los controladores de impresión GDI. La compatibilidad con impresión de WPF también usa la misma función de DDI DrvDocumentEvent que usa la compatibilidad con impresión GDI, pero se han definido nuevos eventos para admitir eventos de procesamiento de documentos XPS. La compatibilidad con impresión GDI seguirá emitiendo controladores de eventos DrvDocumentEvent a controladores de impresión basados en GDI y controladores de impresión XPSDrv para la impresión desde aplicaciones de Microsoft Win32.

Información general sobre el controlador de eventos DrvDocumentEvent

Si es necesario, los controladores de impresión XPSDrv pueden exportar el controlador de eventos DrvDocumentEvent desde el módulo de configuración para interceptar las funciones de procesamiento de documentos. Los nuevos eventos relacionados con documentos XPS se identifican mediante un nombre simbólico que comienza por "DOCUMENTEVENT_XPS_".

La compatibilidad con impresión de WPF llama a la función DrvDocumentEvent del controlador de impresión XPSDrv mientras pone en cola el documento para imprimir. Cada llamada se produce en un paso diferente del proceso. El paso de procesamiento de cada llamada se identifica mediante el valor del argumento iEsc. El contenido de los búferes a los que hacen referencia los argumentos pvIn y pvOut varía, en función del paso de procesamiento.

En las subsecciones siguientes de este tema se describen solo los eventos de procesamiento de documentos XPS que genera la compatibilidad con la impresión de WPF.

Descripción del controlador de eventos DrvDocumentEvent

El controlador de eventos DrvDocumentEvent tiene el siguiente formato de llamada. Las definiciones de código y parámetros de esta sección solo son meramente informativas.

INT
  DrvDocumentEvent(
    HANDLE  hPrinter,
    HDC  hdc,
    int  iEsc,
    ULONG  cbIn,
    PVOID  pvIn,
    ULONG  cbOut,
    PVOID  pvOut
    );

Parámetros

hPrinter
Identificador de impresora que proporciona la compatibilidad de impresión de WPF.

hdc
Identificador de contexto de dispositivo proporcionado por el llamador que genera una llamada CreateDC. Este parámetro es cero si iEsc se establece en DOCUMENTEVENT_CREATEDCPRE.

Cuando se imprime un documento, el sistema usará los mismos valores de evento para los documentos XPS y GDI. El controlador debe tener en cuenta esta similitud y determinar el tipo del trabajo en función de hdc. hdc es igual a INVALID_HANDLE_VALUE para todos los eventos DOCUMENTEVENT_XPS_Xxx. Esta comprobación determinará la interpretación adecuada de los valores de evento DrvDocumentEvent en función de la aplicación que llama. Esta comprobación solo es aplicable a los controladores de impresión XPSDrv.

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

DOCUMENTEVENT_QUERYFILTER
La compatibilidad con impresión de WPF envía este evento para consultar el controlador de impresión para obtener una lista de eventos de procesamiento de documentos XPS a los que responderá el controlador. Este evento se emite antes de cualquier otro evento relacionado con documentos XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
La compatibilidad con impresión de WPF envía este evento antes de agregar FixedDocumentSequence al archivo de cola XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
La compatibilidad con impresión de WPF envía este evento después de agregar FixedDocumentSequence al archivo de cola XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
La compatibilidad con impresión de WPF envía este evento antes de agregar FixedDocument al archivo de cola XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
La compatibilidad con impresión de WPF envía este evento después de agregar FixedDocument al archivo de cola XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF está a punto de agregar un PrintTicket a FixedDocumentSequence (nivel de trabajo).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF debe liberar los datos que devuelve el controlador en el evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE correspondiente.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF está a punto de agregar un PrintTicket a FixedDocument (nivel de documento).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF debe liberar los datos que devuelve el controlador en el evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE correspondiente.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF está a punto de agregar un PrintTicket a FixedPage (nivel de página).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF debe liberar los datos que devuelve el controlador en el evento DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE correspondiente.

DOCUMENTEVENT_XPS_CANCELJOB
La compatibilidad con impresión de WPF envía este evento antes de llamar a una acción de cancelar trabajo.

DOCUMENTEVENT_XPS_COMMITJOB
WPF terminó de escribir la fecha en el archivo actual.

cbIn
Tamaño, en bytes, del búfer al que hace referencia el parámetro pvln. Este valor se proporciona mediante la compatibilidad con impresión de WPF y lo lee el controlador de eventos.

pvIn
Puntero proporcionado por el llamador. El uso de este parámetro depende del valor de iEsc, como se describe en la lista siguiente. (Para los eventos DOCUMENTEVENT_XPS_Xxx que no se muestran en esta lista, no se usa pvIn).

DOCUMENTEVENT_QUERYFILTER
pvIn apunta a una estructura PDOCEVENT_FILTER (igual que para DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene tres propiedades:

  • EscapeCode, que es el valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode es el valor del evento.

  • JobIdentifier, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). JobIdentifier es el identificador necesario para llamar a GetJob() y SetJob().

  • JobName, que es un valor EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Igual que para DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene dos propiedades:

  • EscapeCode, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode es el valor del evento.

  • DocumentNumber, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Igual que para DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene dos propiedades:

  • EscapeCode, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PageNumber, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Igual que para DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene cuatro propiedades:

  • EscapeCode, que es un EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode es el valor del evento.

  • JobIdentifier, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • JobName, que es un valor EPrintPropertyType:: kPropertyTypeString (UNICODE).

  • PrintTicket, que es un valor EPrintPropertyType:: kPropertyTypeByte.

Debe asignar la estructura PrintPropertiesCollection y sus propiedades en el evento "PRE" y liberarla en el evento "POST" correspondiente. Puede establecer pvOut en NULL para indicar que admite el evento, pero no está interesado en cambiar PrintTicket para un documento o página determinado. El complemento nunca debe descargarse entre eventos "PRE" y "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn es el mismo puntero que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

El controlador debe liberar pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene tres propiedades:

  • EscapeCode, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode es el valor del evento.

  • DocumentNumber, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, que es un valor EPrintPropertyType:: kPropertyTypeByte.

Debe asignar la estructura PrintPropertiesCollection y sus propiedades en el evento "PRE" y liberarla en el evento "POST" correspondiente. Puede establecer pvOut en NULL para indicar que admite el evento, pero no está interesado en cambiar PrintTicket para un documento o página determinado. El complemento nunca debe descargarse entre eventos "PRE" y "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn es el mismo puntero que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

El controlador debe liberar pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn apunta a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene tres propiedades:

  • EscapeCode, que es un valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode es el valor del evento.

  • PageNumber, que es un EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, que es un EPrintPropertyType:: kPropertyTypeByte.

Debe asignar la estructura PrintPropertiesCollection y sus propiedades en el evento "PRE" y liberarla en el evento "POST" correspondiente. Puede establecer pvOut en NULL para indicar que admite el evento, pero no está interesado en cambiar PrintTicket para un documento o página determinado. El complemento nunca debe descargarse entre eventos "PRE" y "POST".

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn es el mismo puntero que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

El controlador debe liberar pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn es NULL.

cbOut
Si el parámetro iEsc contiene DOCUMENTEVENT_QUERYFILTER, la compatibilidad con impresión de WPF proporciona el tamaño del búfer al que hace referencia el parámetro pvOut en el parámetro cbOut. Para todos los demás valores de iEsc, no se usa cbOut.

pvOut
Puntero a un búfer que proporciona la compatibilidad de impresión de WPF. El tamaño del búfer y el contenido dependen del valor del parámetro iEsc. En la lista siguiente se describe el contenido del búfer pvOut para cada valor de iEsc.

DOCUMENTEVENT_QUERYFILTER
Puntero proporcionado por el llamador a un búfer que contiene una estructura DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Puntero a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene una propiedad "PrintTicket" de tipo EPrintPropertyType::kPropertyTypeBuffer. Esta propiedad siempre está presente. Cuando no hay disponible PrintTicket, el valor de PrintPropertyValue.propertyBlob.pBuf es NULL.

La propiedad contiene el PrintTicket XML, a partir del cual Microsoft Windows Presentation Foundation (WPF) usará PrintTicket en lugar del que proporciona el llamador XPSDocumentWriter. (Si pvOut es NULL o la propiedad no está presente o los datos de propiedad son NULL, WPF usa printTicket proporcionado por el autor de la llamada).

Una vez procesado este evento, WPF llamará a DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST para que el controlador libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Puntero a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene una propiedad "PrintTicket" de tipo EPrintPropertyType::PropertyTypeBuffer. Esta propiedad siempre está presente. Cuando no hay disponible PrintTicket, el valor de PrintPropertyValue.propertyBlob.pBuf es NULL.

La propiedad contiene el objeto PrintTicket XML, desde el que WPF usará PrintTicket en lugar del que proporciona el llamador XPSDocumentWriter. (Si pvOut es NULL o la propiedad no está presente o los datos de propiedad son NULL, WPF usa printTicket proporcionado por el autor de la llamada).

Una vez procesado este evento, WPF llamará a DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST para que el controlador libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Puntero a una estructura PrintPropertiesCollection (consulte Winspool.h) que contiene una propiedad "PrintTicket" de tipo EPrintPropertyType:: PropertyTypeBuffer. Esta propiedad siempre está presente. Cuando no hay disponible PrintTicket, el valor de PrintPropertyValue.propertyBlob.pBuf es NULL.

La propiedad contiene el objeto PrintTicket XML, desde el que WPF usará PrintTicket en lugar del que proporciona el llamador XPSDocumentWriter. (Si pvOut es NULL o la propiedad no está presente o los datos de propiedad son NULL, WPF usa printTicket proporcionado por el autor de la llamada).

Una vez procesado este evento, WPF llamará a DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST para que el controlador libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Valor devuelto

DrvDocumentEvent devuelve uno de los siguientes valores:

DOCUMENTEVENT_SUCCESS
El controlador manejó correctamente el código de escape que iEsc identificó.

DOCUMENTEVENT_FAILURE
El controlador admite el código de escape que iEsc identificó, pero se produjo un error.

DOCUMENTEVENT_UNSUPPORTED
El controlador no es compatible con el código de escape que iEsc identificó.

Estructuras de eventos de documentos XPS y valores de código de evento

En el ejemplo de código siguiente se muestran las estructuras y constantes que usan los nuevos eventos de documento XPS.

//
// structures used in XPS Document events
//
 
typedef enum
    {
        kPropertyTypeString = 1,
        kPropertyTypeInt32,
        kPropertyTypeInt64,
        kPropertyTypeByte,
        kPropertyTypeTime,
        kPropertyTypeDevMode,
        kPropertyTypeSD,
        kPropertyTypeNotificationReply,
        kPropertyTypeNotificationOptions,

    } EPrintPropertyType;

    typedef struct
    {
        EPrintPropertyType       ePropertyType;
        union
        {
            BYTE                 propertyByte;
            PWSTR                propertyString;
            LONG                 propertyInt32;
            LONGLONG             propertyInt64;
            struct {
                DWORD  cbBuf;
                LPVOID pBuf;
            }                    propertyBlob;
        } value;

    }PrintPropertyValue;

    typedef struct
    {
        WCHAR*                  propertyName;
        PrintPropertyValue      propertyValue;

    }PrintNamedProperty;

    typedef struct
    {
        ULONG                   numberOfProperties;
        PrintNamedProperty*     propertiesCollection;

    }PrintPropertiesCollection;

Las estructuras del ejemplo de código anterior se definen en Winspool.h.

Los siguientes códigos de escape se definen en Winddiui.h.

//
 // Escape code for XPS Document events
//
#define DOCUMENTEVENT_QUERYFILTER                                     14
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE                 1
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE must have same value as //DOCUMENTEVENT_CREATEDCPRE for Winspool.drv to query the driver for supported events and reset the cached events.
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE                         2
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE        3                           
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST                            4
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST                        5
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST                13
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST must have same value as //DOCUMENTEVENT_STARTDOCPOST for Winspool.drv to signal the tray balloon that //the document is completed
#define DOCUMENTEVENT_XPS_CANCELJOB                                   6
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE      7
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE              8
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE                  9
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST                 10
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST             11
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST     12