XPS 驅動程式檔事件

發行項
05/03/2024

重要

新式列印平臺是 Windows 與印表機通訊的慣用方法。我們建議您使用Microsoft的 IPP 收件匣類別驅動程式，以及列印支援應用程式（PSA），自定義 Windows 10 和 11 中的列印體驗，以進行印表機裝置開發。

Microsoft Windows Presentation Foundation （WPF）列印支援會在檔多任務緩衝處理期間傳送 XPSDrv 列印驅動程式通知事件，類似於 GDI 列印支援將通知傳送至 GDI 列印驅動程式的方式。 WPF 列印支援也會使用 GDI 列印支援所使用的相同 DrvDocumentEvent DDI 函式，但已定義新的事件以支援 XPS 檔處理事件。 GDI 列印支援將繼續向以 GDI 為基礎的列印驅動程式和 XPSDrv 列印驅動程式發出 DrvDocumentEvent 事件處理程式，以用於Microsoft Win32 應用程式列印。

DrvDocumentEvent事件處理程式概觀

如有必要，XPSDrv 列印驅動程式可以從組態模組導出 DrvDocumentEvent 事件處理程式，以攔截文件處理函式。新的 XPS 檔相關事件是由以「DOCUMENTEVENT_XPS_」開頭的符號名稱來識別。

WPF 列印支援會在多任務緩衝處理檔以進行列印時，呼叫 XPSDrv 列印驅動程式的 DrvDocumentEvent 函式。每個呼叫都會在程式中的不同步驟進行。每個呼叫的處理步驟都會由iEsc自變數的值來識別。 pvIn 和 pvOut 自變數所參考之緩衝區的內容會根據處理步驟而有所不同。

本主題中的下列小節只會描述 WPF 列印支援產生的 XPS 檔案處理事件。

DrvDocumentEvent事件處理程式描述

DrvDocumentEvent 事件處理程式具有下列呼叫格式。本節中的程式代碼和參數定義僅適用於資訊。

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

參數

hPrinter
WPF 印表支援提供的印表機句柄。

hdc
CreateDC 呼叫所產生的呼叫端提供的裝置內容句柄。如果 iEsc 設定為 DOCUMENTEVENT_CREATEDCPRE，則此參數為零。

列印檔時，系統會針對 XPS 和 GDI 檔使用相同的事件值。驅動程式必須注意此相似性，並根據 hdc 判斷作業的類型。 hdc 等於所有 DOCUMENTEVENT_XPS_Xxx 事件的INVALID_HANDLE_VALUE。此檢查會根據呼叫的應用程式判斷DrvDocumentEvent事件值的正確解譯。這項檢查僅適用於 XPSDrv 列印驅動程式。

iEsc
呼叫端提供的逸出程式碼，可識別要處理的事件。此參數可以是下列其中一個整數常數。

DOCUMENTEVENT_QUERYFILTER
WPF 列印支援會傳送此事件來查詢列印驅動程式，以取得驅動程式將回應的 XPS 檔案處理事件清單。此事件會在任何其他 XPS 檔相關事件之前發出。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
WPF 列印支援會在將 FixedDocumentSequence 新增至 XPS 多任務緩衝處理檔案之前傳送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
WPF 列印支援會在將 FixedDocumentSequence 新增至 XPS 多任務緩衝處理檔案之後傳送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
WPF 列印支援會在將 FixedDocument 新增至 XPS 多任務緩衝處理檔案之前傳送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
WPF 列印支援會在將 FixedDocument 新增至 XPS 多任務緩衝處理檔案之後傳送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF 即將將 PrintTicket 新增至 FixedDocumentSequence （作業層級）。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF 應該釋放驅動程式在對應 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE 事件上傳回的數據。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF 即將將 PrintTicket 新增至 FixedDocument （檔層級）。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF 應該釋放驅動程式在對應DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE事件上傳回的數據。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF 即將將 PrintTicket 新增至 FixedPage （頁面層級）。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF 釋放驅動程式在對應DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE事件上傳回的數據。

DOCUMENTEVENT_XPS_CANCELJOB
WPF 列印支援會在呼叫取消作業動作之前傳送此事件。

DOCUMENTEVENT_XPS_COMMITJOB
WPF 已完成將日期寫入目前檔案。

cbIn
pvln 參數參考之緩衝區的大小，以位元組為單位。這個值是由 WPF 列印支援所提供，並由事件處理程式讀取。

pvIn
提供呼叫端的指標。此參數的使用取決於 iEsc 值，如下列清單所述。（針對DOCUMENTEVENT_XPS_未在此清單中顯示的 Xxx 事件， 不會使用 pvIn 。

DOCUMENTEVENT_QUERYFILTER
pvIn 指向PDOCEVENT_FILTER結構（與DOCUMENTEVENT_QUERYFILTER相同）。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含三個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。 EscapeCode 是事件值。
JobIdentifier，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。 JobIdentifier 是呼叫 GetJob（）和 SetJob（）所需的識別碼。
JobName，這是 EPrintPropertyType：： kPropertyTypeString （UNICODE）值。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
與 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE 相同。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含兩個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。 EscapeCode 是事件值。
DocumentNumber，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
與 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE 相同。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含兩個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。
PageNumber，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
與 DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE 相同。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含四個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）。 EscapeCode 是事件值。
JobIdentifier，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。
JobName，這是 EPrintPropertyType：： kPropertyTypeString （UNICODE）值。
PrintTicket，這是 EPrintPropertyType：： kPropertyTypeByte 值。

您必須在「PRE」事件上配置 PrintPropertiesCollection 結構及其屬性，並在對應的「POST」事件上釋放它。您可以將 pvOut 設定為 NULL，表示您支援事件，但對變更指定檔或頁面的 PrintTicket 並不感興趣。外掛程式不應該在「PRE」和「POST」事件之間卸除。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn 與來自 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE 的 pvOut 指標相同

驅動程式必須免費 pvIn。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含三個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。 EscapeCode 是事件值。
DocumentNumber，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。
PrintTicket，這是 EPrintPropertyType：： kPropertyTypeByte 值。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn 與來自 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE 的 pvOut 指標相同。

驅動程式必須免費 pvIn。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn 指向 PrintPropertiesCollection 結構（請參閱 Winspool.h），其中包含三個屬性：

EscapeCode，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）值。 EscapeCode 是事件值。
PageNumber，這是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG）。
PrintTicket，這是 EPrintPropertyType：： kPropertyTypeByte。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn 與來自 DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE 的 pvOut 相同。

驅動程式必須免費 pvIn。

DOCUMENTEVENT_XPS_CANCELJOB
pvIn 為 NULL。

cbOut
如果 iEsc 參數包含 DOCUMENTEVENT_QUERYFILTER，WPF 列印支援會提供 cbOut 參數中 pvOut 參數參考的緩衝區大小。對於 iEsc 的其他所有值，不會使用 cbOut。

pvOut
WPF 列印支援之緩衝區的指標。緩衝區大小和內容取決於iEsc參數的值。下列清單描述每個 iEsc 值的 pvOut 緩衝區內容。

DOCUMENTEVENT_QUERYFILTER
呼叫端提供的緩衝區指標，其中包含DOCEVENT_FILTER結構。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
PrintPropertiesCollection 結構的指標（請參閱 Winspool.h），其中包含 EPrintPropertyType：：kPropertyTypeBuffer 類型的 “PrintTicket” 屬性。這個屬性一律存在。當沒有 PrintTicket 可用時，PrintPropertyValue.propertyBlob.pBuf 的值會是 NULL。

屬性包含 XML PrintTicket，Microsoft Windows Presentation Foundation （WPF）會使用 PrintTicket，而不是 XPSDocumentWriter 呼叫端 提供的 PrintTicket。（如果 pvOut 為 NULL 或屬性不存在，或屬性數據為 NULL，WPF 會使用呼叫端提供的 PrintTicket。

處理此事件之後，WPF 會使用 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST 呼叫 DocumentEvent ，讓驅動程式釋放 pvOut。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
PrintPropertiesCollection 結構的指標（請參閱 Winspool.h），其中包含 EPrintPropertyType：:P ropertyTypeBuffer 類型的 “PrintTicket” 屬性。這個屬性一律存在。當沒有 PrintTicket 可用時，PrintPropertyValue.propertyBlob.pBuf 的值會是 NULL。

屬性包含 XML PrintTicket，WPF 會從中使用 PrintTicket，而不是 XPSDocumentWriter 呼叫端 提供的 XML PrintTicket。（如果 pvOut 為 NULL 或屬性不存在，或屬性數據為 NULL，WPF 會使用呼叫端提供的 PrintTicket。

處理此事件之後，WPF 會使用 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST 呼叫 DocumentEvent ，讓驅動程序釋放 pvOut。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
PrintPropertiesCollection 結構的指標（請參閱 Winspool.h），其中包含 EPrintPropertyType：： PropertyTypeBuffer 類型的 “PrintTicket” 屬性。這個屬性一律存在。當沒有 PrintTicket 可用時，PrintPropertyValue.propertyBlob.pBuf 的值會是 NULL。

處理此事件之後，WPF 會使用 DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST呼叫 DocumentEvent ，讓驅動程序釋放 pvOut。

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

傳回值

DrvDocumentEvent 會傳回下列其中一個值：

DOCUMENTEVENT_SUCCESS
驅動程式已成功處理 iEsc 識別的逸出程式代碼。

DOCUMENTEVENT_FAILURE
驅動程式支援 iEsc 識別的逸出程式代碼，但發生失敗。

DOCUMENTEVENT_UNSUPPORTED
驅動程式不支援 iEsc 識別的逸出程式代碼。

XPS 檔案事件結構和事件程式代碼值

下列程式代碼範例顯示新 XPS 檔案事件所使用的結構和常數。

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

上述程式代碼範例中的結構定義於 Winspool.h 中。

下列逸出碼定義於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

共用方式為

XPS 驅動程式檔事件

DrvDocumentEvent事件處理程式概觀

DrvDocumentEvent事件處理程式描述

參數

傳回值

XPS 檔案事件結構和事件程式代碼值

意見反應

其他資源