V4 打印机驱动程序属性包

项目
10/16/2024

重要

新式打印平台是 Windows 与打印机通信的首选方式。建议使用 Microsoft 的 IPP 收件箱类驱动程序以及打印支持应用 (PSA) 来自定义 Windows 10 和 11 中的打印体验，以便进行打印机设备开发。

v4 打印驱动程序模型提供了许多属性包，它们有助于从自定义 UI 应用程序到呈现流程的数据流。

这些属性包允许在自定义 UI 中创建自定义属性和功能定义，然后在呈现过程中使用。所有属性包都是通过在 JavaScript 中使用 IPrinterScriptablePropertyBag 接口或在其他环境中使用 IPrinterPropertyBag 接口公开的。

下表概述了如何使用不同组件从 v4 打印驱动程序的不同部分获取属性包对象。

组件	说明
JavaScript 约束脚本	驱动程序和队列属性包使用 scriptContext 参数传递给 JavaScript 约束脚本。此参数的类型为 IPrinterScriptContext，并且包含子参数： DriverProperties - 表示驱动程序属性包。 QueueProperties – 表示队列属性包。 UserProperties – 用户属性包。 DEVMODE 属性包会作为 devModeProperties 参数（其类型为 IPrinterScriptablePropertyBag）被传入 DEVMODE <-> PrintTicket 转换方法中。它无法用在其他方法中。
USB Bidi JavaScript	驱动程序和队列属性包通过 scriptContext 参数传递给 USB Bidi JavaScript 脚本。此参数的类型为 IPrinterScriptContext，并且包含子参数： DriverProperties - 表示驱动程序属性包。 QueueProperties – 表示队列属性包。
打印机扩展应用	所有属性包都会作为 IPrinterExtensionEventArgs 参数的一部分被传入 OnDriverEvent 处理程序。它们都属于 IPrinterPropertyBag 类型。它们被指定为如下： DriverProperties - 表示驱动程序属性包。 UserProperties – 用户属性包。 PrinterQueue.GetProperties()– 表示队列属性包
UWP 设备应用	所有属性包都是在激活过程中使用 IPrinterExtensionContext 对象传入的。它们被指定为： DriverProperties - 表示驱动程序属性包。 UserProperties – 用户属性包。 PrinterQueue.GetProperties()– 表示队列属性包
XPS 呈现筛选器	XPS 筛选器可以使用打印筛选器管道属性包中的属性名称“DriverPropertyBag”或 filterpipeline.h 中定义的值 XPS_FP_PROPERTY_BAG 访问其中的驱动程序属性包。以下是有关 DriverPropertyBag 的信息：属性类型： VT_UNKNOWN 说明：一个指向 IUnknown 接口的指针。调用 QueryInterface 以获取指向驱动程序属性包 IPrinterPropertyBag 接口的指针。 XPS 筛选器可以使用“QueuePropertyBag”属性名称或 filterpipeline.h 中定义的值 XPS_FP_QUEUE_PROPERTY_BAG 从打印筛选器管道属性包中访问队列属性包。以下是有关 QueuePropertyBag 的信息：属性类型： VT_UNKNOWN 说明：一个指向 IUnknown 接口的指针。调用 QueryInterface 以获取指向队列属性包 IPrinterPropertyBag 接口的指针。

在 JavaScript 实现中，属性包会作为参数传递。在打印机扩展应用程序中，属性包作为用于启动应用程序的事件参数的成员传入。

如果未指定或未找到属性包，COM IPrinterQueue、IPrinterExtensionContext 和 IPrinterExtensionEventArgs 接口提供的属性包访问器以及 Javascript 实现中的属性包访问器都会引发异常。此外，在 IPrinterPropertyBag 接口上查询单个属性时，如果未找到该属性，则会引发异常。如果属性不可用，则应使用 try catch 语句来避免崩溃。

驱动程序属性包

驱动程序属性包是一个数据存储库，供驱动程序用于预定义属性或数据 Blob，由驱动程序只读使用。可以通过在 v4 清单文件中使用“PropertyBag”指令来指定，并且在运行时不得修改。

Windows 驱动程序工具包包含一个驱动程序属性包模板项目。驱动程序属性包是一个经过编译的二进制 Blob。 Visual Studio 包含一个用于生成编译驱动程序属性包的模板。此模板生成的 XML 文件不是属性包，而是此模板的编译输出，即应在 v4 清单文件中指定的属性包文件。

用户属性包

用户属性包允许合作伙伴在每个用户的计算机本地上下文中存储设置。此属性包非常适合作为用户首选项（如“不再显示此内容”）的存储机制。管理员无法管理该属性包，而且在打印机共享期间，客户端和服务器之间也不会同步。用户属性包仅在运行时设置，且仅适用于打印机扩展、UWP 设备应用和 JavaScript 约束。

由于 JavaScript 约束也可能在用户上下文之外调用，因此取消过程中，用户属性包此时不可用，Windows 将返回 HRESULT_FROM_WIN32(ERROR_NOT_FOUND)。

DEVMODE 属性包

DEVMODE 属性包用于整理 DEVMODE 结构专有部分中的内容。在调用 ConvertPrintTicketToDevMode 过程中，会调用 JavaScript 来填充 DEVMODE 属性包的内容。在调用 ConvertDevModeToPrintTicket 期间，会调用 JavaScript 从 DEVMODE 属性包中读取持久设置，并将其存储回 PrintTicket 中。

此属性包的大小限制在 60 KB 以下（具体大小根据 DEVMODE 分配部分的大小而定），因为它必须序列化到 DEVMODE 结构中，以避免在某些情况下丢失数据。每个驱动程序可用的具体大小会有所不同，因为它取决于 DEVMODE 公共部分的大小，以及配置模块管理的专有部分的大小。

DEVMODE 属性包使用 XML 文件指定属性包的成员，并使用 convertPrintTicketToDevMode 和 convertDevModeToPrintTicket API 来处理转换。必须在 v4 清单中使用 DevModeMap 指令指定 XML DEVMODE 映射文件。

以下代码片段显示了 DEVMODE 属性包映射 XML 示例。

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns="https://schemas.microsoft.com/windows/2011/08/printing/devmodemap">
  <Property Name="FabrikamAccountCode">
    <String Length="32"></String>
  </Property>  
</Properties>

以下屏幕截图显示了 DEVMODE 属性包映射 XML 架构，可以在 WDK 安装文件夹中的以下路径找到它：\Include\um\printerdriverdevmodemap.xsd.pr

devmode 属性包映射 xml 架构。

DEVMODE 属性包映射的 XML 文件由 INFGate 工具验证。

队列属性包

队列属性包存储每个队列的配置设置，包括表格到托盘的映射以及打印机属性（如可安装选项）的配置。驱动程序定义的属性和打印机属性可在 PowerShell 中配置，而窗体到托盘的映射可在打印机属性 UI 中配置。打印机扩展无法编辑任何属性值。

队列属性包是为许多 v4 打印驱动程序自动创建的，但驱动程序也可能提供其他属性，以便使用 XML 文件进行配置。此 XML 文件不应使用驱动程序属性包工具进行编译。队列属性包适用于 v4 打印驱动程序支持的打印机，它们可执行以下任一操作：

指定多个托盘，或
在 GPD 或 PPD 文件中指定可安装选项，或
使用 QueueProperties 指令在驱动程序清单中指定队列属性包。

管理员使用 PowerShell 配置队列属性包。下列命令行 (cmdlet) 是打印机对象的子对象，可以使用 Get-Printer cmdlet 来获取。

cmdlet 名称	说明
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	检索一个或多个属性（-name 支持通配）。
Set-PrinterProperty -inputObject <printerPropertyObject>	使用持久化的 printerPropertyObject 更改打印队列属性。
Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value>	将指定的属性更改为指定的值。

可安装选项

这些选项，例如双工器的状态，将作为单个属性显示在队列属性包中。每个属性的命名如下所示，其中功能名称将以驱动程序 GPD 或 PPD 文件中的功能名称为准：

Config:<feature name>

例如： Config:DuplexUnit

该属性的值是管理员所选选项的关键字名称。例如，已安装。可安装选项可使用与队列属性相同的 Set-PrinterProperty cmdlet 进行编辑。

从 Windows 8.1 开始，具有管理员权限的用户或创建了打印队列的用户可以通过 UWP 设备应用程序来更改队列属性包的可安装选项和每个队列的配置设置。

表单到托盘映射

对于使用 v4 打印驱动程序且有多个托盘的打印机，“表单到托盘”映射可通过名为“FormTrayTable”的队列属性包来公开。

此属性格式是以 null 结尾的字符串，包含格式为 <tray name>, <form name>, 的表格对，其中表格名称为以下格式之一：

如果纸张大小已映射到 GPD 或 PPD 文件中的打印架构（使用标准 *PaperSize/*PageSize 关键字或 *(MS)PrintSchemaKeywordMap），则表格名称将采用以下格式：

PrintSchema:<Paper Size name>

例如： PrintSchema:NorthAmericaLetter
如果表格是用户定义的表格（由 FORM_USER 标志决定），则表格名称如下所示。表单索引与后台处理程序的表单数据库中使用的相同值。这与在 PrintTicket 中指定纸张大小时使用的索引一致，如下所示：

UserForm<form index>

例如： UserForm123
否则，表格名称将遵循以下格式，其中表格名称是在 GPD 的 *PaperSize 或 PPD 的 *PageSize 中指定的名称。

Config:<name>

例如： Config:_8_5x16

完整的字符串示例如下：

Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0

呈现筛选器应读取传入的 PrintTicket 的 PageMediaSize 设置，并在 FormTrayTable 的表单名称值中搜索该值。

队列属性包 XML 示例

以下代码片段显示了 Name1、Name2、Name3 三个属性及其子元素可使用的 XML 语法：

<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns= "https://schemas.microsoft.com/windows/2011/08/printing/queueproperties">
  <Property Name="Name1">
    <String>String1</String>
  </Property>
  <Property Name="Name2">
    <Int32>3244</Int32>
  </Property>
  <Property Name="Name3">
    <Bool>true</Bool>
  </Property>
</Properties>