Eventi del documento del driver XPS

  • Articolo

Importante

La piattaforma di stampa moderna è il mezzo preferito di Windows per comunicare con le stampanti. Ti consigliamo di usare il driver di classe IPP di Microsoft, insieme a Print Support Apps (PSA), per personalizzare l'esperienza di stampa in Windows 10 e 11 per lo sviluppo di dispositivi per stampanti.

Per altre informazioni, vedere Piattaforma di stampa moderna e guida alla progettazione dell'app di supporto per la stampa.

Il supporto per la stampa di Microsoft Windows Presentation Foundation (WPF) invia eventi di notifica dei driver di stampa XPSDrv durante lo spooling dei documenti in modo analogo al modo in cui il supporto di stampa GDI invia notifiche ai driver di stampa GDI. Il supporto di stampa WPF usa anche la stessa funzione DDI DrvDocumentEvent usata dal supporto di stampa GDI, ma sono stati definiti nuovi eventi per supportare gli eventi di elaborazione dei documenti XPS. Il supporto di stampa GDI continuerà a rilasciare gestori eventi DrvDocumentEvent ai driver di stampa basati su GDI e ai driver di stampa XPSDrv per la stampa di applicazioni Win32 di Microsoft.

Panoramica del gestore eventi DrvDocumentEvent

Se necessario, i driver di stampa XPSDrv possono esportare il gestore eventi DrvDocumentEvent dal modulo di configurazione per intercettare le funzioni di elaborazione dei documenti. I nuovi eventi correlati a XPS Document sono identificati da un nome simbolico che inizia con "DOCUMENTEVENT_XPS_".

Il supporto di stampa WPF chiama la funzione DrvDocumentEvent del driver di stampa XPSDrv mentre esegue lo spooling del documento per la stampa. Ogni chiamata viene eseguita in un passaggio diverso del processo. Il passaggio di elaborazione di ogni chiamata viene identificato dal valore dell'argomento iEsc . Il contenuto dei buffer a cui fanno riferimento gli argomenti pvIn e pvOut varia a seconda del passaggio di elaborazione.

Nelle sottosezioni seguenti di questo argomento vengono descritti solo gli eventi di elaborazione dei documenti XPS prodotti dal supporto di stampa WPF.

Descrizione del gestore eventi DrvDocumentEvent

Il gestore eventi DrvDocumentEvent ha il formato chiamante seguente. Il codice e le definizioni dei parametri in questa sezione sono solo per informazioni.

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

Parametri

hPrinter
Handle della stampante fornito dal supporto di stampa WPF.

hdc
Handle del contesto di dispositivo fornito dal chiamante generato da una chiamata CreateDC . Questo parametro è zero se iEsc è impostato su DOCUMENTEVENT_CREATEDCPRE.

Quando un documento viene stampato, il sistema utilizzerà gli stessi valori di evento per i documenti XPS e GDI. Il driver deve essere a conoscenza di questa somiglianza e determinare il tipo di processo in base all'hdc. hdc è uguale a INVALID_HANDLE_VALUE per tutti gli eventi DOCUMENTEVENT_XPS_Xxx . Questo controllo determinerà l'interpretazione corretta dei valori dell'evento DrvDocumentEvent in base all'applicazione chiamante. Questo controllo è applicabile solo ai driver di stampa XPSDrv.

iEsc
Codice di escape fornito dal chiamante che identifica l'evento da gestire. Questo parametro può essere una delle costanti integer seguenti.

DOCUMENTEVENT_QUERYFILTER
Il supporto di stampa WPF invia questo evento per eseguire una query sul driver di stampa per un elenco di eventi di elaborazione dei documenti XPS a cui risponderà il driver. Questo evento viene generato prima di qualsiasi altro evento correlato al documento XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Il supporto di stampa WPF invia questo evento prima di aggiungere FixedDocumentSequence al file di spooling XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Il supporto di stampa WPF invia questo evento dopo l'aggiunta di FixedDocumentSequence al file di spooling XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Il supporto di stampa WPF invia questo evento prima di aggiungere FixedDocument al file di spooling XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Il supporto di stampa WPF invia questo evento dopo l'aggiunta di FixedDocument al file di spooling XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF sta per aggiungere un printticket a FixedDocumentSequence (livello di processo).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF deve liberare i dati restituiti dal driver nell'evento di DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE corrispondente.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF sta per aggiungere un printticket a FixedDocument (livello documento).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF deve liberare i dati restituiti dal driver nell'evento DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE corrispondente.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF sta per aggiungere un printticket a FixedPage (livello di pagina).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF libera i dati restituiti dal driver sull'evento DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE corrispondente.

DOCUMENTEVENT_XPS_CANCELJOB
Il supporto di stampa WPF invia questo evento prima di chiamare un'azione annulla processo.

DOCUMENTEVENT_XPS_COMMITJOB
WPF ha completato la scrittura della data nel file corrente.

cbIn
Dimensione, in byte, del buffer a cui fa riferimento il parametro pvln . Questo valore viene fornito dal supporto di stampa WPF e letto dal gestore eventi.

pvIn
Puntatore fornito dal chiamante. L'uso di questo parametro dipende dal valore iEsc , come descritto nell'elenco seguente. (Per il DOCUMENTEVENT_XPS_Xxx eventi non visualizzati in questo elenco, pvIn non viene usato.

DOCUMENTEVENT_QUERYFILTER
pvIn punta a una struttura PDOCEVENT_FILTER (uguale a per DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene tre proprietà:

  • EscapeCode, ovvero il valore EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode è il valore dell'evento.

  • JobIdentifier, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG). JobIdentifier è l'ID necessario per chiamare GetJob() e SetJob().

  • JobName, ovvero un valore EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Uguale a per DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene due proprietà:

  • EscapeCode, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode è il valore dell'evento.

  • DocumentNumber, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Uguale a per DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene due proprietà:

  • EscapeCode, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PageNumber, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Uguale a per DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene quattro proprietà:

  • EscapeCode, che è un EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode è il valore dell'evento.

  • JobIdentifier, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • JobName, ovvero un valore EPrintPropertyType:: kPropertyTypeString (UNICODE).

  • PrintTicket, che è un valore EPrintPropertyType:: kPropertyTypeByte.

È necessario allocare la struttura PrintPropertiesCollection e le relative proprietà nell'evento "PRE" e liberarla nell'evento "POST" corrispondente. È possibile impostare pvOut su NULL per indicare che si supporta l'evento, ma non si è interessati a modificare PrintTicket per un determinato documento o pagina. Il plug-in non deve mai scaricare tra gli eventi "PRE" e "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn è lo stesso puntatore di pvOut di DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Il driver deve liberare pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene tre proprietà:

  • EscapeCode, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode è il valore dell'evento.

  • DocumentNumber, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, che è un valore EPrintPropertyType:: kPropertyTypeByte.

È necessario allocare la struttura PrintPropertiesCollection e le relative proprietà nell'evento "PRE" e liberarla nell'evento "POST" corrispondente. È possibile impostare pvOut su NULL per indicare che si supporta l'evento, ma non si è interessati a modificare PrintTicket per un determinato documento o pagina. Il plug-in non deve mai scaricare tra gli eventi "PRE" e "POST".

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn è lo stesso puntatore di pvOut di DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Il driver deve liberare pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn punta a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene tre proprietà:

  • EscapeCode, che è un valore EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode è il valore dell'evento.

  • PageNumber, che è un EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, che è un EPrintPropertyType:: kPropertyTypeByte.

È necessario allocare la struttura PrintPropertiesCollection e le relative proprietà nell'evento "PRE" e liberarla nell'evento "POST" corrispondente. È possibile impostare pvOut su NULL per indicare che si supporta l'evento, ma non si è interessati a modificare PrintTicket per un determinato documento o pagina. Il plug-in non deve mai scaricare tra gli eventi "PRE" e "POST".

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn è lo stesso puntatore di pvOut di DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Il driver deve liberare pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn è NULL.

cbOut
Se il parametro iEsc contiene DOCUMENTEVENT_QUERYFILTER, il supporto di stampa WPF fornisce le dimensioni del buffer a cui fa riferimento il parametro pvOut nel parametro cbOut . Per tutti gli altri valori di iEsc, cbOut non viene usato.

pvOut
Puntatore a un buffer fornito dal supporto di stampa WPF. Le dimensioni e il contenuto del buffer dipendono dal valore del parametro iEsc . L'elenco seguente descrive il contenuto del buffer pvOut per ogni valore iEsc .

DOCUMENTEVENT_QUERYFILTER
Puntatore fornito dal chiamante a un buffer contenente una struttura DOCEVENT_FILTER.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Puntatore a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene una proprietà "PrintTicket" di tipo EPrintPropertyType::kPropertyTypeBuffer. Questa proprietà è sempre presente. Quando non è disponibile printticket, il valore di PrintPropertyValue.propertyBlob.pBuf è NULL.

La proprietà contiene l'xml PrintTicket, da cui microsoft Windows Presentation Foundation (WPF) utilizzerà PrintTicket anziché quello fornito dal chiamante XPSDocumentWriter . Se pvOut è NULL o la proprietà non è presente o i dati della proprietà sono NULL, WPF usa il metodo PrintTicket fornito dal chiamante.

Dopo l'elaborazione di questo evento, WPF chiamerà DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST affinché il driver rilascierà pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Puntatore a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene una proprietà "PrintTicket" di tipo EPrintPropertyType::P ropertyTypeBuffer. Questa proprietà è sempre presente. Quando non è disponibile printticket, il valore di PrintPropertyValue.propertyBlob.pBuf è NULL.

La proprietà contiene l'xml PrintTicket, da cui WPF userà PrintTicket anziché quello fornito dal chiamante XPSDocumentWriter . Se pvOut è NULL o la proprietà non è presente o i dati della proprietà sono NULL, WPF usa il metodo PrintTicket fornito dal chiamante.

Dopo l'elaborazione di questo evento, WPF chiamerà DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST affinché il driver rilascierà pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Puntatore a una struttura PrintPropertiesCollection (vedere Winspool.h) che contiene una proprietà "PrintTicket" di tipo EPrintPropertyType:: PropertyTypeBuffer. Questa proprietà è sempre presente. Quando non è disponibile printticket, il valore di PrintPropertyValue.propertyBlob.pBuf è NULL.

La proprietà contiene l'xml PrintTicket, da cui WPF userà PrintTicket anziché quello fornito dal chiamante XPSDocumentWriter . Se pvOut è NULL o la proprietà non è presente o i dati della proprietà sono NULL, WPF usa il metodo PrintTicket fornito dal chiamante.

Dopo l'elaborazione di questo evento, WPF chiamerà DocumentEvent con DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST affinché il driver rilascierà pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Valore restituito

DrvDocumentEvent restituisce uno dei valori seguenti:

DOCUMENTEVENT_SUCCESS
Il driver ha gestito correttamente il codice di escape identificato da iEsc .

DOCUMENTEVENT_FAILURE
Il driver supporta il codice di escape identificato da iEsc , ma si è verificato un errore.

DOCUMENTEVENT_UNSUPPORTED
Il driver non supporta il codice di escape identificato da iEsc .

Strutture di eventi del documento XPS e valori del codice evento

Nell'esempio di codice seguente vengono illustrate le strutture e le costanti usate dai nuovi eventi XPS Document.

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

Le strutture nell'esempio di codice precedente sono definite in Winspool.h.

I codici di escape seguenti sono definiti in 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