XPS 驱动程序文档事件

项目
02/12/2024

重要

建议使用 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 (Page Level) 。

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 () 所需的 ID。
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 结构的指针 (请参阅包含 EPrintPropertyType：：kPropertyTypeBuffer 类型的“PrintTicket”属性的 Winspool.h) 。此属性始终存在。如果没有 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 结构的指针 (请参阅包含 EPrintPropertyType：:P ropertyTypeBuffer 类型的“PrintTicket”属性的 Winspool.h) 。此属性始终存在。如果没有 PrintTicket 可用， PrintPropertyValue.propertyBlob.pBuf 的值为 NULL。

属性包含 XML PrintTicket，WPF 将使用 PrintTicket 而不是 XPSDocumentWriter 调用方 提供的 PrintTicket。 (如果 pvOut 为 NULL 或属性不存在或属性数据为 NULL，WPF 将使用调用方提供的 PrintTicket.)

处理此事件后，WPF 将使用 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST 调用 DocumentEvent ，以便驱动程序释放 pvOut。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
指向 PrintPropertiesCollection 结构的指针 (请参阅包含 EPrintPropertyType：： PropertyTypeBuffer 类型的“PrintTicket”属性的 Winspool.h) 。此属性始终存在。如果没有 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 ballon 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 文档事件结构和事件代码值

反馈

反馈

其他资源