Eventos do documento do driver XPS

Importante

A moderna plataforma de impressão é o meio preferido do Windows para comunicar com as impressoras. Recomendamos que utilize o controlador de classe da caixa de entrada IPP da Microsoft, juntamente com as Aplicações de Suporte de Impressão (PSA), 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 Guia de design do aplicativo de suporte de impressão v1 e v2.

O suporte de impressão do Microsoft Windows Presentation Foundation (WPF) envia eventos de notificação para drivers de impressão XPSDrv durante o spooling de documentos, de forma semelhante à forma como o suporte de impressão GDI envia notificações para drivers de impressão GDI. O suporte de impressão WPF também usa a mesma função DDI DrvDocumentEvent que o suporte de impressão GDI usa, mas novos eventos foram definidos para suportar eventos de processamento de documento XPS. O suporte de 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 aplicações 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 intercetar as 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 de impressão do WPF chama a função DrvDocumentEvent do driver de impressão XPSDrv enquanto faz spool do documento 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 documento XPS que o suporte de impressão 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

hImpressora
A alça de impressora que o suporte de impressão WPF fornece.

HDC
Um identificador de contexto de dispositivo fornecido pelo chamador, gerado por uma chamada CreateDC. Este parâmetro será 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 motorista 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. Esta verificação é aplicável apenas aos controladores de impressão XPSDrv.

iEsc
Um código de escape fornecido pelo chamador que identifica o evento a ser manipulado. Este parâmetro pode ser uma das seguintes constantes inteiras.

DOCUMENTEVENT_QUERYFILTER
O suporte de 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á. Este evento é emitido antes de quaisquer outros eventos relacionados ao Documento XPS.

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
O suporte de impressão do WPF envia esse evento depois que ele adiciona FixedDocumentSequence ao arquivo de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
O suporte de impressão do WPF envia este evento antes de adicionar o FixedDocument ao ficheiro de spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
O suporte de impressão do WPF envia este evento depois de adicionar o 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
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
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 à FixedPage (Nível de Página).

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

DOCUMENTEVENT_XPS_CANCELJOB
O suporte de impressão do WPF envia este evento antes de chamar uma ação de cancelamento de tarefa.

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 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 os eventos DOCUMENTEVENT_XPS_Xxx 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, cujo valor é EPrintPropertyType::kPropertyTypeInt32 (ULONG). O EscapeCode é o valor do evento.
JobIdentifier, que é um valor de EPrintPropertyType::kPropertyTypeInt32 (ULONG). O JobIdentifier é a ID necessária 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 de EPrintPropertyType::kPropertyTypeInt32 (ULONG).
JobName, que é um valor EPrintPropertyType:: kPropertyTypeString (UNICODE).
PrintTicket, que é um valor do tipo 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ê suporta o evento, mas não está interessado em alterar o PrintTicket para um determinado documento ou página. O plug-in nunca deve descarregar entre os eventos "PRE" e "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn é o mesmo ponteiro que o pvOut do DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

O motorista deve liberar 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 do tipo EPrintPropertyType::kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn é o mesmo ponteiro que pvOut de DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

O motorista deve liberar 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 é do tipo 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 pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn é NULL.

cbOut
Se o parâmetro iEsc contiver DOCUMENTEVENT_QUERYFILTER, o suporte de 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 que o suporte à impressão WPF fornece. 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 do tipo PrintPropertiesCollection (consulte Winspool.h) que tem uma propriedade "PrintTicket" do tipo EPrintPropertyType::kPropertyTypeBuffer. Esta propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf é NULL.

A propriedade contém o XML PrintTicket, a partir do qual o Microsoft Windows Presentation Foundation (WPF) usará o PrintTicket em vez daquele que o chamador XPSDocumentWriter fornece. (Se pvOut é 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. Esta propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf é NULL.

A propriedade contém o PrintTicket em formato XML, que o WPF usará em vez do fornecido pelo chamador XPSDocumentWriter. (Se pvOut é 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. Esta propriedade está sempre presente. Quando nenhum PrintTicket está disponível, o valor de PrintPropertyValue.propertyBlob.pBuf é 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 de retorno

DrvDocumentEvent retorna um dos seguintes valores:

DOCUMENTEVENT_SUCCESS
O motorista manipulou com sucesso o código de escape que iEsc identificou.

DOCUMENTEVENT_FAILURE
O driver suporta o código de escape que iEsc identificou, mas ocorreu uma falha.

DOCUMENTEVENT_UNSUPPORTED
O driver não suporta o código de escape que iEsc identificou.

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

O exemplo de código a seguir mostra as estruturas e constantes que os novos eventos XPS Document 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

Feedback

Esta página foi útil?

Last updated on 2025-07-18

Partilhar via

Eventos do documento do driver XPS

Visão geral do manipulador de eventos DrvDocumentEvent

Descrição do manipulador de eventos DrvDocumentEvent

Parâmetros

Valor de retorno

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

Feedback

Recursos adicionais