JavaScript 制約
重要
最新の印刷プラットフォームは、Windows がプリンターと通信するための推奨手段です。 プリンターデバイス開発におけるWindows 10および11での印刷体験をカスタマイズするために、MicrosoftのIPPインボックスクラスドライバーとPrint Support Apps (PSA)の使用を推奨します。
詳細については、 最新の印刷プラットフォーム および 印刷サポート アプリ設計ガイドを参照してください。
v4 プリンター ドライバー モデルは、v3 IPrintOemPrintTicketProvider インターフェイスから派生した拡張制約と PrintTicket 処理の新しいモデルをサポートしています。
ただし、コンパイル済みの構成プラグインを使用する代わりに、v4 プリンター ドライバーは JavaScript を使用して JavaScript 制約と呼ばれる API を実装し、プリンター ドライバーは必要に応じて 1 つ以上を実装できます。 詳細については、このトピックの最後にある JavaScript 制約 API セクションの関数を参照してください。
JavaScript 制約を使用すると、PrintCapabilities の拡張、PrintTicket の検証、PrintTicket から DEVMODE への変換の処理、およびその逆の処理を行うことができます。 ただし、JavaScript 制約にはいくつかの制限があります。 以下は、主な制限事項の一覧です。
CompletePrintCapabilities を使用して追加された機能とオプション、および validatePrintTicket で指定された制約は、デスクトップ プリンターの基本設定ウィンドウには表示されません。
CompletePrintCapabilities を使用して追加された機能とオプションは、パブリック DEVMODE には保持されません。
JavaScript 制約では、リソース dll から言語リソースにアクセスして、追加された機能やオプションまたはパラメーターをローカライズすることはできません。
そのため、JavaScript 制約は、適切な場合にのみ使用することをお勧めします。 機能とオプションは、可能な場合は GPD または PPD ファイルで指定する必要があり、JavaScript では複雑な制約のみを表す必要があります。
JavaScript ファイルのデバッグ
JavaScript ファイルの基本的な構文検証は、Windows ベースのスクリプト ホストで JavaScript ファイルを開くことでサポートされます。 これを行うには、JavaScript ファイルを右クリックし、[プログラムから開く] を選択し、一覧から Windows ベースのスクリプト ホスト エントリを選択します。 エラーがスローされない場合、JavaScript は構文的に有効です。 それ以外の場合は、次のスクリーンショットに示すように、問題の行番号が示されます。
一般公開されている JavaScript 検証ツールは、JavaScript ファイルのスタイルを評価する際の側近としても価値があります。
対話型デバッグを有効にするには、次のレジストリ キーを作成します。
Key Name: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print
値の名前: EnableJavaScriptDebugging
型: DWORD
値: 1
ただし、PrintConfig.dllは頻繁に読み込まれ、アンロードされるため、印刷するアプリのデバッグは、推奨されるテスト/デバッグ戦略ではありません。 代わりに、製造元はこれらのパブリック API PTGetPrintCapabilities、PTConvertDevModeToPrintTicket、PTConvertPrintTicketToDevMode、PTMergeAndValidatePrintTicket を使用して、JavaScript 制約に関連する各エントリ ポイントを呼び出すテスト アプリを構築することをお勧めします。
デバッグを有効にするにはテスト アプリだけで十分ですが、単体テストを追加して、ドライバー全体が PrintTicket、PrintCapabilities、および制約を想定どおりに処理していることを確認することもできます。 Visual Studio で単体テストをビルドする方法の詳細については、次のトピックを参照してください。
Visual Studio チーム テストを使用した単体テストのチュートリアル
前のテキストに示されているレジストリ キーが作成され、ホスティング プロセスが再起動されたら、JavaScript ソース ファイルをデバッグできます。
ソース ファイルの解析に失敗した場合、デバッガーは呼び出されず、デバッグ環境が失敗したかのように見えることに注意してください。 ソース ファイルの解析に失敗した場合、続行方法の詳細については、Windows Script Host を参照してください。
エラーがなく、ソース ファイルが正常に解析された場合は、次のようにソース ファイルをデバッグします。
Microsoft Visual Studio 2012 以降をテスト マシンにインストールする
JavaScript コードの制約があるドライバーを使用して印刷キューを作成する
この印刷キューを既定として設定します。
テスト アプリまたは JavaScript 制約が呼び出されるシナリオを印刷して開始するアプリを起動します。 JavaScript 制約に分割するには、アプリで PrintTicket/PrintCapabilities API を呼び出す必要があります。メモ帳のような古いアプリはこれらの API を呼び出しませんが、XPS ビューアー アプリでは呼び出されません。 Microsoft では、シナリオをより簡単に分離して再現できるため、ここでテスト アプリを使用することをお勧めします。
この時、"Visual Studio Just-In-Time デバッガー" が "<アプリ>でハンドルされない例外が発生しました" というメッセージが表示されます。
Visual Studio 2012 以降の新しいインスタンスを起動する
[デバッグ][プロセスにアタッチ] の順に選びます。
[プロセスにアタッチ] ダイアログで、[アタッチ: ] が [スクリプト コード] に設定されていることを確認します
テスト アプリまたはアプリの印刷を選択し、最後に [アタッチ] を選択します
[すべて中断] をクリックします
[Visual Studio Just-In-Time デバッガー] ダイアログに戻り、[いいえ] をクリックします
Visual Studio は、現在のテストによって呼び出された場所でデバッガーに分割されます。 これで、コードを通常どおりにデバッグできます。
JavaScript 制約 API
このセクションでは、JavaScript 制約ファイルで使用する API エントリ ポイントとして機能する関数を指定します。 以下はその関数です。
validatePrintTicket
completePrintCapabilities
convertDevModeToPrintTicket
convertPrintTicketToDevMode
validatePrintTicket 関数
この API は、PrintTicket オブジェクトが特定のプリンターに対して有効であることを検証するために呼び出されます。 これは、IPrintOemPrintTicketProvider::ValidatePrintTicket API に似ています。
validatePrintTicket 構文
function validatePrintTicket(printTicket, scriptContext)
validatePrintTicket パラメーター
printTicket
[in][out] 検証する IPrintSchemaTicket オブジェクト。
scriptContext
[in]ドライバー プロパティ バッグ、キュー プロパティ バッグ、およびユーザー プロパティ バッグへのアクセスを提供する IPrinterScriptContext オブジェクト。
validatePrintTicket 戻り値
| 戻り値 | 説明 |
|---|---|
| 0 | printTicket パラメーターが無効であり、修正できなかったことを示します。 E_PRINTTICKET_FORMAT と同じです。 |
| 1 | printTicket パラメーターがこのプリンターの有効な PrintTicket であることを示します。 S_PT_NO_CONFLICT と同じです。 |
| 2 | printTicket パラメーターが有効になるように変更されたことを示します。 S_PT_CONFLICT_RESOLVED に相当します。 |
completePrintCapabilities 関数
この API は、PrintCapabilities オブジェクトを変更できるようにするために呼び出されます。 これは、条件付き機能 (たとえば、写真用紙でのみサポートされている罫線なし) や、GPD または PPD ファイルで生成できなかった機能 (入れ子になった機能定義など) を表すために使用する必要があります。 これは、IPrintOemPrintTicketProvider::CompletePrintCapabilities API に似ています。
completePrintCapabilities 構文
function completePrintCapabilities(printTicket, scriptContext, printCapabilities)
completePrintCapabilities パラメーター
printTicket
[in] 生成された PrintCapabilities ドキュメントを制約する IPrintSchemaTicket オブジェクトの入力。
scriptContext
[in]ドライバー プロパティ バッグ、キュー プロパティ バッグ、およびユーザー プロパティ バッグへのアクセスを提供する IPrinterScriptContext オブジェクト。
printCapabilities
[in][out] 構成モジュールによって生成された基本 PrintCapabilities オブジェクトを表す IPrintSchemaCapabilities オブジェクト。
completePrintCapabilities 戻り値
なし。
convertDevModeToPrintTicket 関数
この API は、DEVMODE プロパティ バッグの値を PrintTicket に変換するために呼び出されます。 これは、IPrintOemPrintTicketProvider::ConvertDevModeToPrintTicket API に似ていますが、この実装では DEVMODE のプライベート セクションが IPrinterScriptablePropertyBag オブジェクトにカプセル化され、DEVMODE のパブリック セクションにアクセスできない点が異なります。
convertDevModeToPrintTicket 構文
function convertDevModeToPrintTicket(devModeProperties, scriptContext, printTicket)
convertDevModeToPrintTicket パラメーター
- devModeProperties
[in] DEVMODE プロパティ バッグを表す IPrinterScriptablePropertyBag オブジェクト。
scriptContext
[in]ドライバー プロパティ バッグ、キュー プロパティ バッグ、およびユーザー プロパティ バッグへのアクセスを提供する IPrinterScriptContext オブジェクト。
printTicket
[in][out] PrintTicket を表す IPrintSchemaTicket オブジェクト。
convertDevModeToPrintTicket 戻り値
なし。
convertPrintTicketToDevMode 関数
この API は、PrintTicketからDEVMODEプロパティバッグの値に変換するために呼び出されます。 これは、IPrintOemPrintTicketProvider::ConvertPrintTicketToDevMode API に似ていますが、この実装では DEVMODE のプライベート セクションが IPrinterScriptablePropertyBag オブジェクトにカプセル化され、DEVMODE のパブリック セクションにアクセスできない点が異なります。
convertPrintTicketToDevMode 構文
function convertPrintTicketToDevMode(printTicket, scriptContext, devModeProperties)
convertPrintTicketToDevMode パラメーター
printTicket
[in]変換する PrintTicket を表す IPrintSchemaTicket オブジェクト。
scriptContext
[in] ドライバー プロパティ バッグ、キュー プロパティ バッグ、およびユーザー プロパティ バッグへのアクセスを提供する IPrinterScriptContext オブジェクト。
devModeProperties
[in][out] DEVMODE プロパティ バッグを表す IPrinterScriptablePropertyBag オブジェクト。
convertPrintTicketToDevMode 戻り値
なし。
制約のベスト プラクティス
Windows 8 印刷ダイアログと印刷設定エクスペリエンスでは、印刷スキーマ キーワード名前空間のサブセットのみがサポートされます。 そのため、Windows 8 の印刷ダイアログまたは印刷設定 UI でサポートされている機能と、その UI にない機能の間で制約を使用することはお勧めしません。ユーザーにはそのような制約を解決する機会がないためです。
たとえば、Photo という PageMediaType オプションが PageResolution 値 1200dpi でのみ機能するように制限されている場合、ユーザーは写真メディアの種類を選択できません。 このような場合は、ユーザーの意図 (写真メディア) を一致させ、これを行うために必要な設定を調整することをお勧めします。 これらの調整は、JavaScript 制約コードで行うことができます。
ドライバーが JavaScript 制約を利用しない場合、ファイルを指定する必要はありません。 ドライバーがエントリ ポイントのサブセット (validatePrintTicket など) にのみ JavaScript 制約を使用する場合、他のエントリ ポイントは JavaScript ファイルから完全に省略する必要があります。