Eventos de documento do driver XPS
Importante
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 o Guia de design do aplicativo de suporte à 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 spooling de documentos de forma semelhante a 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 oferecer suporte a eventos de processamento de documentos 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 aplicativo 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 de impressão WPF chama a função DrvDocumentEvent do driver de impressão XPSDrv enquanto ele spools o 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 que são 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 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
hImpressora
O identificador de impressora que o suporte de impressão WPF fornece.
hdc
Um identificador de contexto de dispositivo fornecido pelo chamador que uma chamada CreateDC gera. Esse 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 driver deve estar ciente dessa semelhança e determinar o tipo do 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 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 de impressão 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 de impressão WPF envia esse evento antes de adicionar FixedDocumentSequence ao arquivo de spool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
O suporte de impressão WPF envia esse evento depois que ele adiciona FixedDocumentSequence ao arquivo de spool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
O suporte de impressão WPF envia esse evento antes de adicionar FixedDocument ao arquivo de spool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
O suporte de impressão WPF envia esse evento depois que ele adiciona FixedDocument ao arquivo de spool XPS.
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF está prestes a adicionar um PrintTicket para o 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
WPF está prestes a adicionar um PrintTicket para o FixedDocument (nível de documento).
DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
O WPF deve liberar os dados que o driver retorna no evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE correspondente.
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF está prestes a adicionar um PrintTicket para o FixedPage (nível de página).
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
O WPF libera os dados que o driver retorna no evento DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE correspondente.
DOCUMENTEVENT_XPS_CANCELJOB
O suporte de impressão do WPF envia esse evento antes de chamar uma ação de cancelamento de trabalho.
DOCUMENTEVENT_XPS_COMMITJOB
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 , como descreve a lista a seguir. (Para os 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 é 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 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ê oferece suporte ao evento, mas não está interessado em alterar o PrintTicket para um determinado documento ou página. O plug-in nunca deve descarregar entre 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.
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ê oferece suporte ao evento, mas não está interessado em alterar o PrintTicket para um determinado documento ou página. O plug-in nunca deve descarregar entre eventos "PRE" e "POST".
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.
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ê oferece suporte ao evento, mas não está interessado em alterar o PrintTicket para um determinado documento ou página. O plug-in nunca deve descarregar entre eventos "PRE" e "POST".
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 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 de 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 PrintPropertiesCollection (consulte Winspool.h) que contém 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 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 o 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::P ropertyTypeBuffer. 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 WPF usará o PrintTicket em vez daquele que o chamador XPSDocumentWriter fornece. (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 o 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.
A propriedade contém o XML PrintTicket, a partir do qual o WPF usará o PrintTicket em vez daquele que o chamador XPSDocumentWriter fornece. (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_ADDFIXEDPAGEPRINTTICKETPOST para que o driver libere o pvOut.
DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL
Valor retornado
DrvDocumentEvent retorna um dos seguintes valores:
DOCUMENTEVENT_SUCCESS
O motorista manipulou com êxito o código de escape que o iEsc identificou.
DOCUMENTEVENT_FAILURE
O driver suporta o código de escape que o iEsc identificou, mas ocorreu uma falha.
DOCUMENTEVENT_UNSUPPORTED
O driver não suporta o código de escape que o iEsc identificou.
Estruturas de eventos de documento XPS e valores de código de evento
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 códigos de escape a seguir 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de