V4 印表機驅動程序屬性包

發行項
10/01/2024

重要

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

v4 列印驅動程式模型提供數個屬性包，可協助從自定義UI應用程式流向轉譯程序的數據。

這些屬性包允許在自定義UI中建立自訂屬性和功能定義，然後由轉譯程序取用。所有屬性包都是使用 JavaScript 中的 IPrinterScriptablePropertyBag 介面，或在其他環境中使用 IPrinterPropertyBag 介面來公開。

下表提供如何使用不同元件，從 v4 列印驅動程式的不同部分取得屬性包物件的概觀。

元件	描述
JavaScript 條件約束腳本	驅動程式和佇列屬性包會使用 scriptContext 參數傳遞至 JavaScript 條件約束腳本。此參數的類型為 IPrinterScriptContext ，且包含子系： DriverProperties – 參考驅動程序屬性包。 QueueProperties – 參考佇列屬性包。 UserProperties – 使用者屬性包。 DEVMODE 屬性包會傳遞至 DEVMODE <-> PrintTicket 轉換方法作為 devModeProperties 參數（其類型為 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定義的值，從 Print Filter Pipeline 屬性包記憶體取驅動程式屬性包。以下是 DriverPropertyBag 的相關信息：屬性類型： VT_UNKNOWN 描述： IUnknown 介面的指標。呼叫 QueryInterface 以取得驅動程式屬性包之 IPrinterPropertyBag 介面的指標。而 XPS 篩選器可以使用屬性名稱「QueuePropertyBag」，或 filterpipeline.h XPS_FP_QUEUE_PROPERTY_BAG定義的值，從 Print Filter Pipeline 屬性包記憶體取佇列屬性包。以下是 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 指令清單檔中指定的屬性包檔案。

User 屬性包

使用者屬性包可讓合作夥伴將設定儲存在每個使用者、計算機本機內容中。這個屬性包非常適合作為使用者喜好設定的儲存機制，例如「不要再顯示這個」。系統管理員無法管理此屬性包，而且在印表機共享期間不會在用戶端與伺服器之間同步處理。使用者屬性包只會在運行時間設定，而且僅適用於印表機擴充功能、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 來處理轉換。 XML DEVMODE 對應檔必須使用 DevModeMap 指示詞，在 v4 指令清單中指定。

下列代碼段顯示 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 工具驗證。

Queue 屬性包

佇列屬性包會儲存每個佇列組態設定，包括窗體到匣對應，以及列印機屬性的設定，例如可安裝的選項。驅動程式定義的屬性和印表機屬性可在PowerShell中設定，而表單到紙匣對應則可在印表機屬性UI中設定。印表機延伸模組無法編輯任何屬性值。

佇列屬性包會自動為許多 v4 列印驅動程式建立，但驅動程式也可能提供其他屬性來使用 XML 檔案進行設定。此 XML 檔案不應該使用驅動程式屬性包工具進行編譯。佇列屬性包適用於 v4 印表驅動程式支援的印表機，這些驅動程式會執行下列其中一項：

指定多個匣、OR
在 GPD 或 PPD 檔案中指定可安裝的選項，或
使用 QueueProperties 指示詞在驅動程式指令清單中指定佇列屬性包。

系統管理員會使用PowerShell設定佇列屬性包。下列 command-lets （Cmdlet）是可使用 Get-Printer Cmdlet 取得的印表機物件的子系。

Cmdlet 名稱	描述
Get-PrinterProperty -printerName <printerName> -name <propertyName*>	擷取一或多個屬性（-name 支援 Globbing）。
Set-PrinterProperty -inputObject <printerPropertyObject>	使用保存的印表機PropertyObject 變更列印佇列屬性。
Set-PrinterProperty -printerName <printerName -PropertyName <> propertyName> -Value <值>	將指定的屬性變更為指定的值。

可安裝的選項

例如，這些選項會將雙工的狀態公開到佇列屬性包中做為個別屬性。每個屬性的名稱會如下所示，其中功能名稱是以驅動程式 GPD 或 PPD 檔案的功能名稱為基礎：

Config:<feature name>

例如，Config:DuplexUnit

屬性的值是系統管理員已選取之選項的關鍵詞名稱。例如，Installed。可安裝的選項可以使用用於佇列屬性的相同 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 的表單名稱值中搜尋該值。

Queue 屬性包 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>