XPS-Treiberdokument Ereignisse

Wichtig

Die Modern Print-Plattform ist die von Windows bevorzugte Methode zur Kommunikation mit Druckern. Wir empfehlen die Verwendung des Microsoft IPP-Treibers für die Posteingangsklasse zusammen mit Print Support Apps (PSA), um das Druckverhalten in Windows 10 und 11 für die Entwicklung von Druckergeräten anzupassen.

Weitere Informationen finden Sie unter Modern Print-Plattform und der Anleitung zum Design der Print-Support-App.

Die Druckunterstützung der Microsoft Windows Presentation Foundation (WPF) sendet Benachrichtigungsereignisse an XPSDrv-Druckertreiber während des Spoolings von Dokumenten, ähnlich wie die GDI-Druckunterstützung Benachrichtigungen an GDI-Druckertreiber sendet. Die WPF-Druckunterstützung verwendet ebenfalls die gleiche DDI-Funktion DrvDocumentEvent wie die GDI-Druckunterstützung, aber es wurden neue Ereignisse definiert, um XPS-Dokumentverarbeitungsereignisse zu unterstützen. Die GDI-Druckunterstützung wird weiterhin DrvDocumentEvent-Ereignishandler an GDI-basierte Druckertreiber und XPSDrv-Druckertreiber für den Druck aus Microsoft Win32-Anwendungen ausgeben.

Übersicht der DrvDocumentEvent-Ereignishandler

Falls erforderlich, können XPSDrv-Druckertreiber den Ereignishandler DrvDocumentEvent aus dem Konfigurationsmodul exportieren, um Funktionen zur Dokumentenverarbeitung abzufangen. Die neuen XPS-Dokument-bezogenen Ereignisse werden durch einen symbolischen Namen gekennzeichnet, der mit „DOCUMENTEVENT_XPS_“ beginnt.

Die WPF-Druckunterstützung fragt die Funktion DrvDocumentEvent des XPSDrv-Druckertreibers an, während sie das Dokument zum Drucken spoolt. Jeder Aufruf erfolgt in einem anderen Schritt des Prozesses. Der Verarbeitungsschritt jedes Aufrufs wird durch den Wert des Arguments iEsc identifiziert. Der Inhalt der Puffer, auf die die Argumente pvIn und pvOut verweisen, variiert je nach Verarbeitungsschritt.

Die folgenden Unterabschnitte in diesem Thema beschreiben nur die XPS-Dokumentverarbeitungsereignisse, die die WPF-Druckunterstützung erzeugt.

DrvDocumentEvent Ereignishandler Beschreibung

Der DrvDocumentEvent Ereignishandler hat das folgende Anfrageformat. Der Code und die Parameterdefinitionen in diesem Abschnitt dienen nur zur Information.

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

Parameter

hPrinter
Das Druckerhandle, das die WPF-Druckunterstützung bereitstellt.

hdc
Ein vom Anrufer geliefertes Gerätekontext-Handle, das durch einen CreateDC-Aufruf erzeugt wird. Dieser Parameter ist Null, wenn iEsc auf DOCUMENTEVENT_CREATEDCPRE gesetzt ist.

Wenn ein Dokument gedruckt wird, verwendet das System die gleichen Ereigniswerte für XPS- und GDI-Dokumente. Der Treiber muss sich dieser Ähnlichkeit bewusst sein und den Typ des Auftrags anhand des hdc bestimmen. hdc ist gleich INVALID_HANDLE_VALUE für alle DOCUMENTEVENT_XPS_Xxx Ereignisse. Durch diese Überprüfung wird die richtige Interpretation der DrvDocumentEvent-Ereigniswerte auf der Grundlage der anfragenden Anwendung ermittelt. Diese Überprüfung gilt nur für XPSDrv-Druckertreiber.

iEsc
Ein vom Aufrufer bereitgestellter Escape-Code, der das zu behandelnde Ereignis identifiziert. Dieser Parameter kann eine der folgenden Integerkonstanten sein.

DOCUMENTEVENT_QUERYFILTER
Die WPF-Druckunterstützung sendet dieses Ereignis, um den Druckertreiber nach einer Liste von XPS-Dokumentverarbeitungsereignissen zu fragen, auf die der Treiber reagieren soll. Dieses Ereignis wird vor allen anderen XPS-Dokument-bezogenen Ereignissen ausgegeben.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Die WPF-Druckunterstützung sendet dieses Ereignis, bevor sie FixedDocumentSequence zur XPS-Spooldatei hinzufügt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Die WPF-Druckunterstützung sendet dieses Ereignis, nachdem sie der XPS-Spooldatei FixedDocumentSequence hinzugefügt hat.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Die WPF-Druckunterstützung sendet dieses Ereignis, bevor sie FixedDocument zur XPS-Spooldatei hinzufügt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Die WPF-Druckunterstützung sendet dieses Ereignis, nachdem sie FixedDocument zur XPS-Spooldatei hinzugefügt hat.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF ist dabei, ein PrintTicket zur FixedDocumentSequence (Job Level) hinzuzufügen.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF sollte die Daten freigeben, die der Treiber bei dem entsprechenden Ereignis DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE zurückgibt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF ist dabei, dem FixedDocument (Dokumentenebene) ein PrintTicket hinzuzufügen.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF sollte die Daten freigeben, die der Treiber bei dem entsprechenden Ereignis DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE zurückgibt.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF ist dabei, der FixedPage (Seitenebene) ein PrintTicket hinzuzufügen.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF gibt die Daten frei, die der Treiber bei dem entsprechenden Ereignis DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE zurückgibt.

DOCUMENTEVENT_XPS_CANCELJOB
Die WPF-Druckunterstützung sendet dieses Ereignis, bevor sie eine Auftragsabbruchaktion anfragt.

DOCUMENTEVENT_XPS_COMMITJOB
WPF hat das Schreiben des Datums in die aktuelle Datei beendet.

cbIn
Die Größe des Puffers, auf den der Parameter pvln verweist, in Bytes. Dieser Wert wird von der WPF-Druckunterstützung bereitgestellt und vom Ereignishandler gelesen.

pvIn
Ein vom Aufrufer bereitgestellter Pointer. Die Verwendung dieses Parameters hängt vom iEsc-Wert ab, wie in der folgenden Liste beschrieben. (Für die DOCUMENTEVENT_XPS_Xxx-Ereignisse, die nicht in dieser Liste aufgeführt sind, wird pvIn nicht verwendet).

DOCUMENTEVENT_QUERYFILTER
pvIn zeigt auf eine PDOCEVENT_FILTER-Struktur (dieselbe wie bei DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die drei Eigenschaften enthält:

• EscapeCode, der den Wert EPrintPropertyType::kPropertyTypeInt32 (ULONG) hat. Der EscapeCode ist der Ereigniswert.

• JobIdentifier, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist. Der JobIdentifier ist die ID, die für die Anfragen GetJob() und SetJob() benötigt wird.

• JobName, der ein EPrintPropertyType:: kPropertyTypeString (UNICODE) Wert ist.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Dasselbe wie für DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die zwei Eigenschaften enthält:

• EscapeCode, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist. Der EscapeCode ist der Ereigniswert.

• DocumentNumber, die ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Dasselbe wie bei DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die zwei Eigenschaften enthält:

• EscapeCode, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist.

• PageNumber, die ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Dasselbe wie bei DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die vier Eigenschaften enthält:

• EscapeCode, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) ist. Der EscapeCode ist der Ereigniswert.

• JobIdentifier, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist.

• JobName, der ein EPrintPropertyType:: kPropertyTypeString (UNICODE) Wert ist.

• PrintTicket, das ein EPrintPropertyType:: kPropertyTypeByte-Wert ist.

Sie müssen die Struktur PrintPropertiesCollection und ihre Eigenschaften beim Ereignis „PRE“ zuweisen und beim entsprechenden Ereignis „POST“ freigeben. Sie können pvOut auf NULL setzen, um anzuzeigen, dass Sie das Ereignis unterstützen, aber nicht daran interessiert sind, das PrintTicket für ein bestimmtes Dokument oder eine Seite zu ändern. Das Plug-in sollte niemals zwischen den Ereignissen „PRE“ und „POST“ entladen werden.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn ist der gleiche Pointer wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Der Treiber muss pvIn freigeben.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die drei Eigenschaften enthält:

• EscapeCode, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist. Der EscapeCode ist der Ereigniswert.

• DocumentNumber, die ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist.

• PrintTicket, das ein EPrintPropertyType:: kPropertyTypeByte-Wert ist.

Sie müssen die Struktur PrintPropertiesCollection und ihre Eigenschaften beim Ereignis „PRE“ zuweisen und beim entsprechenden Ereignis „POST“ freigeben. Sie können pvOut auf NULL setzen, um anzuzeigen, dass Sie das Ereignis unterstützen, aber nicht daran interessiert sind, das PrintTicket für ein bestimmtes Dokument oder eine Seite zu ändern. Das Plug-in sollte niemals zwischen den Ereignissen „PRE“ und „POST“ entladen werden.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn ist der gleiche Pointer wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Der Treiber muss pvIn freigeben.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn zeigt auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die drei Eigenschaften enthält:

• EscapeCode, der ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) Wert ist. Der EscapeCode ist der Ereigniswert.

• PageNumber, die ein EPrintPropertyType::kPropertyTypeInt32 (ULONG) ist.

• PrintTicket, das ein EPrintPropertyType:: kPropertyTypeByte ist.

Sie müssen die Struktur PrintPropertiesCollection und ihre Eigenschaften beim Ereignis „PRE“ zuweisen und beim entsprechenden Ereignis „POST“ freigeben. Sie können pvOut auf NULL setzen, um anzuzeigen, dass Sie das Ereignis unterstützen, aber nicht daran interessiert sind, das PrintTicket für ein bestimmtes Dokument oder eine Seite zu ändern. Das Plug-in sollte niemals zwischen den Ereignissen „PRE“ und „POST“ entladen werden.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn ist der gleiche Pointer wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Der Treiber muss pvIn freigeben.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn ist NULL.

cbOut
Wenn der iEsc-Parameter DOCUMENTEVENT_QUERYFILTER enthält, liefert die WPF-Druckunterstützung die Größe des Puffers, auf den der pvOut-Parameter im cbOut-Parameter verweist. Für alle anderen Werte von iEsc wird cbOut nicht verwendet.

pvOut
Der Pointer auf einen Puffer, den die WPF-Druckunterstützung bereitstellt. Die Größe und der Inhalt des Puffers hängen vom Wert des Parameters iEsc ab. Die folgende Liste beschreibt den Inhalt des pvOut-Puffers für jeden iEsc-Wert.

DOCUMENTEVENT_QUERYFILTER
Ein vom Aufrufer bereitgestellter Pointer auf einen Puffer, der eine DOCEVENT_FILTER-Struktur enthält.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Ein Pointer auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die eine Eigenschaft „PrintTicket“ vom Typ EPrintPropertyType::kPropertyTypeBuffer enthält. Diese Eigenschaft ist immer vorhanden. Wenn kein PrintTicket verfügbar ist, ist der Wert von PrintPropertyValue.propertyBlob.pBuf NULL.

Die Eigenschaft enthält das XML PrintTicket, aus dem die Microsoft Windows Presentation Foundation (WPF) das PrintTicket anstelle desjenigen verwendet, das der XPSDocumentWriter Aufrufer liefert. (Wenn pvOut NULL ist oder die Eigenschaft nicht vorhanden ist oder die Eigenschaftsdaten NULL sind, verwendet WPF das vom Aufrufer gelieferte PrintTicket).

Nachdem dieses Ereignis verarbeitet wurde, ruft WPF DocumentEvent mit DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST auf, damit der Treiber pvOut freigibt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Ein Pointer auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die eine Eigenschaft „PrintTicket“ vom Typ EPrintPropertyType::PropertyTypeBuffer enthält. Diese Eigenschaft ist immer vorhanden. Wenn kein PrintTicket verfügbar ist, wird der Wert von PrintPropertyValue.propertyBlob.pBuf NULL sein.

Die Eigenschaft enthält das XML PrintTicket, von dem WPF das PrintTicket anstelle des vom XPSDocumentWriter-Anrufer gelieferten verwendet. (Wenn pvOut NULL ist oder die Eigenschaft nicht vorhanden ist oder die Eigenschaftsdaten NULL sind, verwendet WPF das vom Aufrufer gelieferte PrintTicket).

Nachdem dieses Ereignis verarbeitet wurde, ruft WPF DocumentEvent mit DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST auf, damit der Treiber pvOut freigibt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Ein Pointer auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die eine Eigenschaft „PrintTicket“ vom Typ EPrintPropertyType: enthält: PropertyTypeBuffer. Diese Eigenschaft ist immer vorhanden. Wenn kein PrintTicket verfügbar ist, wird der Wert von PrintPropertyValue.propertyBlob.pBuf NULL sein.

Die Eigenschaft enthält das XML PrintTicket, von dem WPF das PrintTicket anstelle des vom XPSDocumentWriter-Anrufer gelieferten verwendet. (Wenn pvOut NULL ist oder die Eigenschaft nicht vorhanden ist oder die Eigenschaftsdaten NULL sind, verwendet WPF das vom Aufrufer gelieferte PrintTicket).

Nachdem dieses Ereignis verarbeitet wurde, wird WPF DocumentEvent mit DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST anfragen, damit der Treiber pvOut freigibt.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Rückgabewert

DrvDocumentEvent gibt einen der folgenden Werte zurück:

DOCUMENTEVENT_SUCCESS
Der Treiber hat den von iEsc identifizierten Escape-Code erfolgreich verarbeitet.

DOCUMENTEVENT_FAILURE
Der Treiber unterstützt den von iEsc identifizierten Escape-Code, aber es ist ein Fehler aufgetreten.

DOCUMENTEVENT_UNSUPPORTED
Der Treiber unterstützt den von iEsc identifizierten Escape-Code nicht.

XPS-Dokument-Ereignisstrukturen und Ereigniscodewerte

Das folgende Codebeispiel zeigt die Strukturen und Konstanten, die die neuen XPS-Dokumentereignisse verwenden.

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

Die Strukturen im vorangehenden Codebeispiel sind in Winspool.h definiert.

Die folgenden Escape-Codes sind in Winddiui.h definiert.

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