XPS-Treiberdokumentereignisse

Artikel
05/03/2024

Wichtig

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 im Print support app design guide.

Die Microsoft Windows Presentation Foundation (WPF)-Druckunterstützung sendet XPSDrv-Drucktreiberbenachrichtigungsereignisse während der Dokumentspoolung ähnlich wie die GDI-Druckunterstützung sendet Benachrichtigungen an GDI-Drucktreiber. Die WPF-Druckunterstützung verwendet auch die gleiche DrvDocumentEvent DDI-Funktion, die die GDI-Druckunterstützung verwendet, aber neue Ereignisse wurden definiert, um XPS-Dokumentverarbeitungsereignisse zu unterstützen. Die GDI-Druckunterstützung stellt weiterhin DrvDocumentEvent-Ereignishandler für GDI-basierte Drucktreiber und XPSDrv-Drucktreiber für den Microsoft Win32-Anwendungsdruck aus.

Übersicht über den DrvDocumentEvent-Ereignishandler

Bei Bedarf können XPSDrv-Drucktreiber den DrvDocumentEvent-Ereignishandler aus dem Konfigurationsmodul exportieren, um Dokumentverarbeitungsfunktionen abzufangen. Die neuen XPS Document-bezogenen Ereignisse werden durch einen symbolischen Namen identifiziert, der mit "DOCUMENTEVENT_XPS_" beginnt.

Die WPF-Druckunterstützung ruft die DrvDocumentEvent-Funktion des XPSDrv-Drucktreibers auf, während das Dokument zum Drucken gepoolt wird. Jeder Aufruf erfolgt in einem anderen Schritt im Prozess. Der Verarbeitungsschritt jedes Aufrufs wird durch den Wert des iEsc-Arguments identifiziert. Der Inhalt der Puffer, auf die durch die PvIn - und PvOut-Argumente verwiesen wird, variieren je nach Verarbeitungsschritt.

In den folgenden Unterabschnitten in diesem Thema werden nur die XPS-Dokumentverarbeitungsereignisse beschrieben, die von der WPF-Druckunterstützung erzeugt werden.

Beschreibung des DrvDocumentEvent-Ereignishandlers

Der DrvDocumentEvent-Ereignishandler hat das folgende Aufrufformat. Die Code- und Parameterdefinitionen in diesem Abschnitt sind nur für Informationen vorgesehen.

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

Parameter

hPrinter
Der Druckerhandle, den die WPF-Druckunterstützung bereitstellt.

Hdc
Ein vom Aufrufer bereitgestellter Gerätekontexthandle, das ein CreateDC-Aufruf generiert. Dieser Parameter ist null, wenn iEsc auf DOCUMENTEVENT_CREATEDCPRE festgelegt ist.

Wenn ein Dokument gedruckt wird, verwendet das System dieselben Ereigniswerte für XPS- und GDI-Dokumente. Der Treiber muss sich dieser Ähnlichkeit bewusst sein und den Typ des Auftrags basierend auf dem hdc bestimmen. hdc ist gleich INVALID_HANDLE_VALUE für alle DOCUMENTEVENT_XPS_Xxx-Ereignisse . Diese Überprüfung bestimmt die richtige Interpretation der DrvDocumentEvent-Ereigniswerte basierend auf der aufrufenden Anwendung. Diese Überprüfung gilt nur für XPSDrv-Drucktreiber.

iEsc
Ein vom Aufrufer bereitgestellter Escapecode, 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 Drucktreiber nach einer Liste der XPS-Dokumentverarbeitungsereignisse abzufragen, auf die der Treiber reagiert. Dieses Ereignis wird vor allen anderen XPS-Dokumentereignissen ausgegeben.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Die WPF-Druckunterstützung sendet dieses Ereignis, bevor fixedDocumentSequence zur XPS-Spooldatei hinzugefügt wird.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Die WPF-Druckunterstützung sendet dieses Ereignis, nachdem fixedDocumentSequence zur XPS-Spooldatei hinzugefügt wurde.

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Die WPF-Druckunterstützung sendet dieses Ereignis, nachdem fixedDocument zur XPS-Spooldatei hinzugefügt wurde.

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF sollte die Daten freigeben, die der Treiber für das entsprechende DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE-Ereignis zurückgibt.

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF sollte die Daten freigeben, die der Treiber für das entsprechende DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE-Ereignis zurückgibt.

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

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF gibt die Daten frei, die der Treiber für das entsprechende DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE-Ereignis zurückgibt.

DOCUMENTEVENT_XPS_CANCELJOB
Die WPF-Druckunterstützung sendet dieses Ereignis, bevor sie eine Abbruchauftragsaktion aufruft.

DOCUMENTEVENT_XPS_COMMITJOB
WPF hat das Datum in die aktuelle Datei geschrieben.

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

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

DOCUMENTEVENT_QUERYFILTER
pvIn verweist auf eine PDOCEVENT_FILTER Struktur (identisch mit DOCUMENTEVENT_QUERYFILTER).

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

EscapeCode, der EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert ist. EscapeCode ist der Ereigniswert.
JobIdentifier, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt. Der JobIdentifier ist die ID, die zum Aufrufen von GetJob() und SetJob() erforderlich ist.
JobName, ein EPrintPropertyType:: kPropertyTypeString (UNICODE)-Wert.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Identisch mit DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

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

EscapeCode, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt. EscapeCode ist der Ereigniswert.
DocumentNumber, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Identisch mit DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

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

EscapeCode, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt.
PageNumber, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
Identisch mit DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

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

EscapeCode, ein EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode ist der Ereigniswert.
JobIdentifier, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt.
JobName, ein EPrintPropertyType:: kPropertyTypeString (UNICODE)-Wert.
PrintTicket, ein EPrintPropertyType:: kPropertyTypeByte-Wert.

Sie müssen die PrintPropertiesCollection-Struktur und deren Eigenschaften für das "PRE"-Ereignis zuweisen und für das entsprechende POST-Ereignis freigeben. Sie können pvOut auf NULL festlegen, um anzugeben, dass Sie das Ereignis unterstützen, aber nicht daran interessiert sind, das PrintTicket für ein bestimmtes Dokument oder eine bestimmte Seite zu ändern. Das Plug-In sollte niemals zwischen "PRE"- und "POST"-Ereignissen entladen werden.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn ist derselbe Zeiger wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Der Fahrer muss pvIn frei geben.

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

EscapeCode, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt. EscapeCode ist der Ereigniswert.
DocumentNumber, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt.
PrintTicket, ein EPrintPropertyType:: kPropertyTypeByte-Wert.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn ist derselbe Zeiger wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Der Fahrer muss pvIn frei geben.

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

EscapeCode, bei dem es sich um einen EPrintPropertyType::kPropertyTypeInt32 (ULONG)-Wert handelt. EscapeCode ist der Ereigniswert.
PageNumber, ein EPrintPropertyType::kPropertyTypeInt32 (ULONG).
PrintTicket, ein EPrintPropertyType:: kPropertyTypeByte.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn ist derselbe Zeiger wie pvOut aus DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Der Fahrer muss pvIn frei geben.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn ist NULL.

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

pvOut
Der Zeiger auf einen Puffer, den die WPF-Druckunterstützung bereitstellt. Die Puffergröße und der Inhalt hängen vom Wert des iEsc-Parameters ab. In der folgenden Liste werden die Inhalte des PvOut-Puffers für jeden iEsc-Wert beschrieben.

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Ein Zeiger auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die eine "PrintTicket"-Eigenschaft 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) anstelle des PrintTicket verwendet, das der XPSDocumentWriter-Aufrufer bereitstellt. (Wenn pvOut NULL ist oder die Eigenschaft nicht vorhanden ist oder die Eigenschaftendaten NULL sind, verwendet WPF das vom Aufrufer bereitgestellte PrintTicket.)

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Ein Zeiger auf eine PrintPropertiesCollection-Struktur (siehe Winspool.h), die eine "PrintTicket"-Eigenschaft vom Typ "EPrintPropertyType::P ropertyTypeBuffer" 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 WPF das PrintTicket anstelle des vom XPSDocumentWriter-Aufrufer bereitstellt. (Wenn pvOut NULL ist oder die Eigenschaft nicht vorhanden ist oder die Eigenschaftendaten NULL sind, verwendet WPF das vom Aufrufer bereitgestellte PrintTicket.)

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

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

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

Nachdem dieses Ereignis verarbeitet wurde, ruft WPF DocumentEvent mit DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST auf, damit der Treiber pvOut freigeben kann.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Rückgabewert

DrvDocumentEvent gibt einen der folgenden Werte zurück:

DOCUMENTEVENT_SUCCESS
Der Treiber hat den von iEsc identifizierten Escapecode erfolgreich verarbeitet.

DOCUMENTEVENT_FAILURE
Der Treiber unterstützt den von iEsc identifizierten Escapecode, aber ein Fehler ist aufgetreten.

DOCUMENTEVENT_UNSUPPORTED
Der Treiber unterstützt den von iEsc identifizierten Escapecode nicht.

XPS-Dokumentereignisstrukturen und Ereigniscodewerte

Das folgende Codebeispiel zeigt die Strukturen und Konstanten, die von den neuen XPS-Dokumentereignissen verwendet werden.

//
// 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 vorherigen Codebeispiel werden in Winspool.h definiert.

Die folgenden Escapecodes werden 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

XPS-Treiberdokumentereignisse

Übersicht über den DrvDocumentEvent-Ereignishandler

Beschreibung des DrvDocumentEvent-Ereignishandlers

Parameter

Rückgabewert

XPS-Dokumentereignisstrukturen und Ereigniscodewerte

Feedback

Feedback

Zusätzliche Ressourcen