次の方法で共有

V4 プリンター ドライバー プロパティ バッグ

  • [アーティクル]

重要

Windows でプリンターとの通信手段として推奨されるのは、最新の印刷プラットフォームです。 プリンターデバイス開発におけるWindows 10および11での印刷体験をカスタマイズするために、MicrosoftのIPPインボックスクラスドライバーとPrint Support Apps (PSA)の使用を推奨します。

詳細については、最新の印刷プラットフォームに関する記事および「印刷サポート アプリの設計ガイド」を参照してください。

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 マニフェスト ファイルで指定する必要があるプロパティ バッグ ファイルです。

ユーザー プロパティ バッグ

ユーザー プロパティ バッグを使用すると、パートナーはユーザーごとのマシン ローカル コンテキストに設定を格納できます。 このプロパティ バッグは、「2度と表示しない」などのユーザー設定のストレージ メカニズムとして適しています。 このプロパティ バッグは管理者が管理できず、プリンターの共有中にクライアントとサーバー間で同期されません。 ユーザー プロパティ バッグは実行時にのみ設定され、プリンター拡張機能、UWP デバイス アプリ、JavaScript の制約でのみ使用できます。

JavaScript 制約はユーザー コンテキストの外部でも呼び出される可能性があるため、デスプール中、ユーザー プロパティ バッグはこの時点で使用できず、Windows は HRESULT_FROM_WIN32(ERROR_NOT_FOUND) を返します。

DEVMODE プロパティ バッグ

DEVMODE プロパティ バッグは、DEVMODE 構造体のプライベート セクション内のコンテンツを整理するために使用されます。 ConvertPrintTicketToDevMode の呼び出し中に、DEVMODE プロパティ バッグの内容を設定するために JavaScript が呼び出されます。 ConvertDevModeToPrintTicket の呼び出し中に JavaScript が呼び出され、DEVMODE プロパティ バッグから永続化された設定が読み取られ、PrintTicket に格納されます。

このプロパティ バッグのサイズは 60 KB 未満に制限されます (正確な量は、DEVMODE の割り当てられたセクションのサイズによって異なります)。これは一部のシナリオではデータ損失を回避するために DEVMODE 構造体にシリアル化する必要があるためです。 使用可能な正確なサイズは、DEVMODE のパブリック セクションのサイズと構成モジュールによって管理されるプライベート セクションによって決まるため、ドライバーごとに異なります。

DEVMODE プロパティ バッグは、XML ファイルを使用してプロパティ バッグのメンバーを指定し、convertPrintTicketToDevMode API と 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 プロパティ バッグ

Queue プロパティ バッグには、フォームからトレイへのマッピングや、インストール可能なオプションなどのプリンター プロパティの構成など、キューごとの構成設定が格納されます。 ドライバー定義のプロパティとプリンターのプロパティは PowerShell で構成できます。一方、フォームとトレイのマッピングはプリンターのプロパティ UI で構成できます。 プリンター拡張機能では、プロパティ値を編集できません。

Queue プロパティ バッグは、多くの v4 印刷ドライバーに対して自動的に作成されますが、ドライバーは XML ファイルを使用して構成するための追加のプロパティを提供することもできます。 この XML ファイルは、ドライバー プロパティ バッグ ツールを使用してコンパイルしないでください。 Queue プロパティ バッグは、v4 印刷ドライバーでサポートされているプリンターで使用できます。次のいずれかの操作を行います。

  1. 複数のトレイを指定する、または

  2. GPD または PPD ファイルでインストール可能なオプションを指定する、または

  3. QueueProperties ディレクティブを使用して、ドライバー マニフェストで Queue プロパティ バッグを指定する。

管理者は、PowerShell を使用して Queue プロパティ バッグを構成します。 次のコマンド レット (cmdlets) は、Get-Printer cmdlet を使用して取得できるプリンター オブジェクトの子です。

コマンドレット名 説明
Get-PrinterProperty -printerName <printerName> -name <propertyName*> 1 つ以上のプロパティを取得します (-name は globbing をサポートします)。
Set-PrinterProperty -inputObject <printerPropertyObject> 永続化された printerPropertyObject を使用して、印刷キューのプロパティを変更します。
Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value> 指定されたプロパティを、指定された値に変更します。

インストール可能なオプション

これらのオプション (たとえば、デュプレクサの状態) は、個々のプロパティとして Queue プロパティ バッグに公開されます。 各プロパティの名前は次のようになります。この名前は、ドライバーの GPD または PPD ファイルの機能の名前に基づいています。

Config:<feature name>

たとえば、Config:DuplexUnit のように指定します。

プロパティの値は、管理者が選択したオプションのキーワード名です。 たとえば、インストール済みです。 インストール可能なオプションは、キューのプロパティに使用されるのと同じ Set-PrinterProperty コマンドレットを使用して編集可能です。

Windows 8.1 以降では、管理者権限を持つユーザー、または印刷キューを作成したユーザーは、UWP デバイス アプリから Queu プロパティ バッグのインストール可能なオプションとキューごとの構成設定を変更できます。

フォームからトレイへのマッピング

v4 プリンター ドライバーと複数のトレイを持つプリンターの場合、「FormTrayTable」という名前のプロパティの Queue プロパティ バッグを介して「フォームからトレイ」へのマッピングが公開されます。

このプロパティは、フォーム名が次のいずれかである <tray name>, <form name>, 形式のペアを含む null で終わる文字列として書式設定されます。

  1. (標準の *PaperSize/*PageSize キーワードまたは *(MS)PrintSchemaKeywordMap を使用して) GPD または PPD ファイルの印刷スキーマに用紙サイズがマップされている場合、フォーム名は次の形式になります。

    PrintSchema:<Paper Size name>

    たとえば、PrintSchema:NorthAmericaLetter のように指定します。

  2. FORM_USER フラグによって決定されるフォームがユーザー定義フォームの場合、フォーム名は次のようになります。 フォーム インデックスは、スプーラーのフォーム データベースで使用される値と同じです。 これは、次のように PrintTicket で用紙サイズを指定するときに使用されるインデックスと一致します。

    UserForm<form index>

    たとえば、UserForm123 のように指定します。

  3. それ以外の場合、フォーム名は次の形式に従います。ここで、フォーム名は 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 サンプル

次のコード スニペットは、Name1、Name2、Name3 の 3 つのプロパティとその子要素に使用できる 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>

Queue プロパティ バッグ XML スキーマ

次のスクリーンショットは、Queue プロパティ バッグ XML スキーマを示しており、WDK インストール フォルダーの次のパスにあります: \Include\um\printqueueproperties.xsd.

Queue プロパティ バッグ XML スキーマ

IPrinterExtensionContext

IPrinterExtensionEventArgs

IPrinterPropertyBag

IPrinterScriptablePropertyBag

IPrinterScriptContext

印刷 フィルター パイプライン プロパティ バッグ