V4 打印机驱动程序属性包

项目
03/08/2023

重要

建议使用 Microsoft 的 IPP 收件箱类驱动程序以及打印支持应用 (PSA) ，自定义 Windows 10 和 11 中的打印体验，以便进行打印机设备开发。

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

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

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

组件	说明
JavaScript 约束脚本	驱动程序和队列属性包使用 scriptContext 参数传递给 JavaScript 约束脚本。此参数的类型为 IPrinterScriptContext ，包含子级： DriverProperties – 指驱动程序属性包。 QueueProperties – 指队列属性包。 UserProperties – 用户属性包。 DEVMODE 属性包作为 devModeProperties 参数传递到 DEVMODE <-> PrintTicket 转换方法中，该参数 (类型为 IPrinterScriptablePropertyBag) 。在其他方法上不可用。
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 语句来避免崩溃。

Driver 属性包

驱动程序属性包是供驱动程序预定义属性或数据 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 来处理转换。必须使用 DevModeMap 指令在 v4 清单中指定 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 架构。

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

Queue 属性包

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

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

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

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

Cmdlet 名称	说明
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	检索一个或多个属性， (名称支持) 。
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>, ，其中窗体名称为下列值之一：

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

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 示例

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

<?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>