Eventos de documentos do driver XPS

Artigo
10/07/2024

Importante

A plataforma de impressão moderna é o meio preferido do Windows para se comunicar com as impressoras. Recomendamos que você use o driver de classe de caixa de entrada IPP da Microsoft juntamente com PSA (Aplicativos de Suporte à Impressão) para personalizar a experiência de impressão no Windows 10 e 11 para o desenvolvimento de dispositivos de impressora.

Para obter mais informações, consulte Plataformade impressão moderna e o Guia de design do aplicativo de suporte de impressão.

O suporte de impressão do Microsoft Windows Presentation Foundation (WPF) envia eventos de notificação de drivers de impressão XPSDrv durante o spool de documentos, da mesma forma que o suporte à impressão GDI envia notificações para drivers de impressão GDI. O suporte de impressão do WPF também usa a mesma função DDI DrvDocumentEvent que o suporte de impressão GDI usa, mas novos eventos foram definidos para dar suporte a eventos de processamento de documentos XPS. O suporte à impressão GDI continuará a emitir manipuladores de eventos DrvDocumentEvent para drivers de impressão baseados em GDI e drivers de impressão XPSDrv para impressão de aplicativos Microsoft Win32.

Visão geral do manipulador de eventos DrvDocumentEvent

Se necessário, os drivers de impressão XPSDrv podem exportar o manipulador de eventos DrvDocumentEvent do módulo de configuração para interceptar funções de processamento de documentos. Os novos eventos relacionados ao Documento XPS são identificados por um nome simbólico que começa com "DOCUMENTEVENT_XPS_".

O suporte à impressão do WPF chama a função DrvDocumentEvent do driver de impressão XPSDrv enquanto ele coloca o documento em spool para impressão. Cada chamada ocorre em uma etapa diferente do processo. A etapa de processamento de cada chamada é identificada pelo valor do argumento iEsc. O conteúdo dos buffers referenciados pelos argumentos pvIn e pvOut varia, dependendo da etapa de processamento.

As subseções a seguir neste tópico descrevem apenas os eventos de processamento de documentos XPS que o suporte de impressão do WPF produz.

Descrição do manipulador de eventos DrvDocumentEvent

O manipulador de eventos DrvDocumentEvent tem o seguinte formato de chamada. As definições de código e parâmetro nesta seção são apenas para informação.

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

Parâmetros

hPrinter
O identificador de impressora que o suporte de impressão do WPF fornece.

hdc
Um identificador de contexto de dispositivo fornecido pelo chamador que uma chamada CreateDC gera. Este parâmetro é zero se iEsc estiver definido como DOCUMENTEVENT_CREATEDCPRE.

Quando um documento é impresso, o sistema usará os mesmos valores de evento para documentos XPS e GDI. O driver deve estar ciente dessa semelhança e determinar o tipo de trabalho com base no hdc. hdc é igual a INVALID_HANDLE_VALUE para todos os eventos DOCUMENTEVENT_XPS_Xxx. Essa verificação determinará a interpretação adequada dos valores de evento DrvDocumentEvent com base no aplicativo de chamada. Essa verificação é aplicável somente aos drivers de impressão XPSDrv.

iEsc
Um código de escape fornecido pelo chamador que identifica o evento a ser manipulado. Esse parâmetro pode usar uma das constantes de inteiro a seguir.

DOCUMENTEVENT_QUERYFILTER
O suporte à impressão do WPF envia esse evento para consultar o driver de impressão para obter uma lista de eventos de processamento de documentos XPS aos quais o driver responderá. Esse evento é emitido antes de qualquer outro evento relacionado ao documento XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
O suporte à impressão do WPF envia esse evento antes de adicionar FixedDocumentSequence ao arquivo de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
O suporte à impressão do WPF envia esse evento depois de adicionar FixedDocumentSequence ao arquivo de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
O suporte à impressão do WPF envia esse evento antes de adicionar FixedDocument ao arquivo de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
O suporte à impressão do WPF envia esse evento depois de adicionar FixedDocument ao arquivo de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
O WPF está prestes a adicionar um PrintTicket ao FixedDocumentSequence (nível de trabalho).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
O WPF deve liberar os dados que o driver retorna no evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE correspondente.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
O WPF está prestes a adicionar um PrintTicket ao FixedDocument (Nível do Documento).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
O WPF deve liberar os dados que o driver retorna no evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE correspondente.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
O WPF está prestes a adicionar um PrintTicket ao FixedPage (nível de página).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
O WPF deve liberar os dados que o driver retorna no evento DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE correspondente.

DOCUMENTEVENT_XPS_CANCELJOB
O suporte à impressão do WPF envia esse evento antes de chamar uma ação de trabalho de cancelamento.

DOCUMENTEVENT_XPS_COMMITJOB
O WPF terminou de gravar a data no arquivo atual.

cbIn
O tamanho, em bytes, do buffer ao qual o parâmetro pvln faz referência. Esse valor é fornecido pelo suporte de impressão do WPF e lido pelo manipulador de eventos.

pvIn
Um ponteiro fornecido pelo chamador. O uso desse parâmetro depende do valor iEsc, conforme descrito na lista a seguir. (Para o DOCUMENTEVENT_XPS_Xxx eventos que não são mostrados nesta lista, pvIn não é usado.)

DOCUMENTEVENT_QUERYFILTER
pvIn aponta para uma estrutura PDOCEVENT_FILTER (a mesma que para DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém três propriedades:

EscapeCode, que é o valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
JobIdentifier, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). O JobIdentifier é o ID necessário para chamar GetJob() e SetJob().
JobName, que é um valor EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
O mesmo que para DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém duas propriedades:

EscapeCode, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
DocumentNumber, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
O mesmo que para DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém duas propriedades:

EscapeCode, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PageNumber, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
O mesmo que para DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém quatro propriedades:

EscapeCode, que é um EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
JobIdentifier, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).
JobName, que é um valor EPrintPropertyType:: kPropertyTypeString (UNICODE).
PrintTicket, que é um valor EPrintPropertyType:: kPropertyTypeByte.

Você deve alocar a estrutura PrintPropertiesCollection e suas propriedades no evento "PRE" e liberá-la no evento "POST" correspondente. Você pode definir pvOut como NULL para indicar que você dá suporte ao evento, mas não está interessado em alterar o PrintTicket de um determinado documento ou página. O plug-in nunca deve ser descarregado entre os eventos "PRE" e "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn é o mesmo ponteiro que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

O motorista deve liberar o pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém três propriedades:

EscapeCode, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
DocumentNumber, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PrintTicket, que é um valor EPrintPropertyType:: kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn é o mesmo ponteiro que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

O motorista deve liberar o pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn aponta para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém três propriedades:

EscapeCode, que é um valor EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
PageNumber, que é um EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PrintTicket, que é um EPrintPropertyType:: kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn é o mesmo ponteiro que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

O motorista deve liberar o pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn é NULL.

cbOut
Se o parâmetro iEsc contiver DOCUMENTEVENT_QUERYFILTER, o suporte à impressão do WPF fornecerá o tamanho do buffer ao qual o parâmetro pvOut faz referência no parâmetro cbOut. Para todos os outros valores de iEsc, cbOut não é usado.

pvOut
O ponteiro para um buffer fornecido pelo suporte de impressão do WPF. O tamanho e o conteúdo do buffer dependem do valor do parâmetro iEsc. A lista a seguir descreve o conteúdo do buffer pvOut para cada valor iEsc.

DOCUMENTEVENT_QUERYFILTER
Um ponteiro fornecido pelo chamador para um buffer que contém uma estrutura DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Um ponteiro para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém uma propriedade "PrintTicket" do tipo EPrintPropertyType::kPropertyTypeBuffer. A propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf é NULL.

A propriedade contém o XML PrintTicket, do qual o Microsoft Windows Presentation Foundation (WPF) usará o PrintTicket em vez daquele fornecido pelo chamador XPSDocumentWriter. (Se pvOut for NULL ou a propriedade não estiver presente ou os dados da propriedade forem NULL, o WPF usará o PrintTicket fornecido pelo chamador.)

Depois que esse evento for processado, o WPF chamará DocumentEvent com DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST para que o driver libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Um ponteiro para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém uma propriedade "PrintTicket" do tipo EPrintPropertyType::PropertyTypeBuffer. A propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf is NULL.

A propriedade contém o XML PrintTicket, do qual o WPF usará o PrintTicket em vez daquele fornecido pelo chamador XPSDocumentWriter. (Se pvOut for NULL ou a propriedade não estiver presente ou os dados da propriedade forem NULL, o WPF usará o PrintTicket fornecido pelo chamador.)

Depois que esse evento for processado, o WPF chamará DocumentEvent com DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST para que o driver libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Um ponteiro para uma estrutura PrintPropertiesCollection (consulte Winspool.h) que contém uma propriedade "PrintTicket" do tipo EPrintPropertyType:: PropertyTypeBuffer. A propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf is NULL.

Depois que esse evento for processado, o WPF chamará DocumentEvent com DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST para que o driver libere pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Valor retornado

DrvDocumentEvent retorna um dos seguintes valores:

DOCUMENTEVENT_SUCCESS
O driver manipulou com êxito o código de escape que o iEsc identificou.

DOCUMENTEVENT_FAILURE
O driver dá suporte ao código de escape que o iEsc identificou, mas ocorreu uma falha.

DOCUMENTEVENT_UNSUPPORTED
O driver não dá suporte ao código de escape identificado pelo iEsc .

Estruturas de eventos de documentos XPS e valores de código de eventos

O exemplo de código a seguir mostra as estruturas e constantes que os novos eventos de documento XPS usam.

//
// 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;

As estruturas no exemplo de código anterior são definidas em Winspool.h.

Os seguintes códigos de escape são definidos em 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

Compartilhar via

Eventos de documentos do driver XPS

Visão geral do manipulador de eventos DrvDocumentEvent

Descrição do manipulador de eventos DrvDocumentEvent

Parâmetros

Valor retornado

Estruturas de eventos de documentos XPS e valores de código de eventos

Comentários

Recursos adicionais