XPS 驱动程序文档事件

Microsoft Windows Presentation Foundation （WPF） 打印支持在文档后台处理期间发送 XPSDrv 打印驱动程序通知事件，这与 GDI 打印支持将通知发送到 GDI 打印驱动程序的方式类似。 WPF 打印支持也使用相同的 DrvDocumentEvent DDI 函数，GDI 打印支持使用，但已定义新事件以支持 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_ADDFIXEDDOCUMENT标准版QUENCEPRE
WPF 打印支持在将 FixedDocumentSequence 添加到 XPS 后台处理程序文件之前发送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPOST
WPF 打印支持在将 FixedDocumentSequence 添加到 XPS 后台处理程序文件后发送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
WPF 打印支持在将 FixedDocument 添加到 XPS 后台处理程序文件之前发送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
WPF 打印支持在将 FixedDocument 添加到 XPS 后台处理程序文件后发送此事件。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPRE
WPF 即将将 PrintTicket 添加到 FixedDocumentSequence （作业级别）。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPOST
WPF 应释放驱动程序在相应 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPRE 事件上返回的数据。

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_ADDFIXEDDOCUMENT标准版QUENCEPRE
pvIn 指向一个 PrintPropertiesCollection 结构（请参阅 Winspool.h），该结构包含三个属性：

• EscapeCode，即 EPrintPropertyType：：kPropertyTypeInt32 （ULONG） 值。 EscapeCode 是事件值。

• JobIdentifier，它是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG） 值。 JobIdentifier 是调用 GetJob（） 和 SetJob（）所需的 ID。

• JobName，它是 EPrintPropertyType：： kPropertyTypeString （UNICODE） 值。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPOST
与 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRE 相同。

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_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPRE
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_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPOS
pvIn 与来自 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPRE 的 pvOut 相同

驱动程序必须释放 pvIn。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn 指向一个 PrintPropertiesCollection 结构（请参阅 Winspool.h），该结构包含三个属性：

• EscapeCode，它是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG） 值。 EscapeCode 是事件值。

• DocumentNumber，它是 EPrintPropertyType：：kPropertyTypeInt32 （ULONG） 值。

• PrintTicket，它是 EPrintPropertyType：： kPropertyTypeByte 值。

必须在“PRE”事件上分配 PrintPropertiesCollection 结构及其属性，并在相应的“POST”事件上释放它。 可以将 pvOut 设置为 NULL，以指示你支持该事件，但对更改给定文档或页面的 PrintTicket 不感兴趣。 插件不应在“PRE”和“POST”事件之间卸载。

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。

必须在“PRE”事件上分配 PrintPropertiesCollection 结构及其属性，并在相应的“POST”事件上释放它。 可以将 pvOut 设置为 NULL，以指示你支持该事件，但对更改给定文档或页面的 PrintTicket 不感兴趣。 插件不应在“PRE”和“POST”事件之间卸载。

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_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPRE
指向 PrintPropertiesCollection 结构（请参阅 Winspool.h）的指针，该结构包含 EPrintPropertyType：：kPropertyTypeBuffer 类型的“PrintTicket”属性。 此属性始终存在。 如果没有 PrintTicket 可用，PrintPropertyValue.propertyBlob.pBuf 的值为 NULL。

该属性包含 XML PrintTicket，Microsoft Windows Presentation Foundation （WPF）将使用 PrintTicket，而不是 XPSDocumentWriter 调用方 提供的 XML PrintTicket。 （如果 pvOut 为 NULL 或属性不存在或属性数据为 NULL，WPF 将使用调用方提供的 PrintTicket。

处理此事件后，WPF 将使用 DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPOST 调用 DocumentEvent，以便驱动程序释放 pvOut。

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENT标准版QUENCEPRINTTICKETPOS
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。

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

处理此事件后，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