IPrintTicketProvider::BindPrinter メソッド (prdrvcom.h)

[アーティクル]
08/07/2023

IPrintTicketProvider::BindPrinter メソッドは、プリンターまたは印刷キューを印刷チケットスキーマの特定のバージョンにバインドします。これにより、コアドライバーはプライベート名前空間の一様リソース識別子 (URI) のセットをデバイスに関連付けることができます。

構文

HRESULT BindPrinter(
  [in]  IN HANDLE     hPrinter,
  [in]  IN INT        version,
  [out] OUT PSHIMOPTS pOptions,
  [out] OUT DWORD     *pDevModeFlags,
  [out] OUT INT       *cNamespaces,
  [out] OUT BSTR      **ppNamespaces
);

パラメーター

[in] hPrinter

スプーラーの印刷ハンドル。これはコアドライバーによって提供されます。プロバイダーのクライアントは、このハンドルの有効期間を管理する責任があるため、プロバイダーはいつでもこのハンドルを閉じてはいけません。プロバイダーは、印刷ハンドルをキャッシュできます。今後のすべての呼び出しは、このハンドルに関連付けられているプリンターに対して相対的です。

[in] version

印刷チケットマネージャーが OEM プラグインプロバイダーにサポートを要求する印刷チケットまたは印刷チケットスキーマのメジャーバージョン番号。 Windows Vista では、バージョン 1 のみがサポートされています。プロバイダーは、サポートされていないバージョンまたは認識されないバージョンへのバインドの試行を失敗させる必要があります。

[out] pOptions

次のいずれかの列挙値を受け取る変数へのポインター。

PTSHIM_DEFAULT

システムは、 DEVMODEW 構造体のプライベート部分のバイナリエンコード (BLOB - バイナリラージオブジェクト) を、 DEVMODEW から印刷チケットへの変換で印刷チケットに配置します。
PTSHIM_NOSNAPSHOT

DEVMODEW から印刷チケットへの変換では、システムは DEVMODEW 構造体のプライベート部分のバイナリエンコード (BLOB) を印刷チケットに配置しません。すべてのパブリックおよびプライベート DEVMODEW メンバーが印刷チケットで完全に表されている場合は、この値を使用します。

[out] pDevModeFlags

DEVMODEW から印刷チケットへの変換または印刷チケットから DEVMODEW への変換で印刷チケット shim によって処理されないパブリック DEVMODEW メンバーを示す一連のビットフラグを受け取る DWORD 型の変数へのポインター。このパラメーターに存在するビットフラグは、プリンターが関連付けられている DEVMODEW メンバーをサポートしていないか、プロバイダーがその DEVMODEW 特性を処理することを示します。たとえば、DM_MEDIATYPEが *pDevModeFlags で設定されている場合、プリンターで複数のメディアの種類がサポートされていないか、プロバイダーが複数のメディアの種類をサポートします。 (DM_XXX ビットフラグはすべて wingdi.h で定義され、Microsoft Windows SDKで説明されています)。既定では、印刷チケット shim は、既定の DEVMODEW 構造体の dmFlags メンバーで表されるすべてのメンバーを処理します。

[out] cNamespaces

プラグインで使用されるプライベート名前空間 URI の数を受け取る変数へのポインター。この数値は、 ppNamespaces が指す配列内の文字列の数を表します。

[out] ppNamespaces

BSTR 配列の最初の要素のアドレスを受け取る変数へのポインター。プラグインは、各配列位置に名前空間 URI を入力します。このパラメーターの詳細については、次の「解説」セクションを参照してください。

戻り値

IPrintTicketProvider::BindPrinter は、次のいずれかの値を返す必要があります。

リターンコード	説明
S_OK	操作が成功しました。
E_VERSION_NOT_SUPPORTED	プラグインは、version パラメーターで指定された印刷スキーマのバージョンをサポートしていません。

注釈

デバイスへのバインドにより、プロバイダーは特定のオブジェクトをキャッシュし、そのデバイス上の今後の印刷チケットまたはデバイス機能サービスに必要な処理を行うことができます。たとえば、hPrinter パラメーターのプリンターハンドルをキャッシュできます。 IPrintTicketProvider::BindPrinter メソッドは、1 回だけ呼び出される保証があります。

ドライバーは、ppNamespaces パラメーターによって指される配列と名前空間 URI 文字列にメモリを割り当てる役割を担います。 配列は、CoTaskMemAlloc 関数を使用して割り当てる必要があります。名前空間文字列は、SysAllocString 関数を使用して割り当てる必要があります。どちらの関数も、Windows SDK のドキュメントで説明されています。 ppNamespaces パラメーターが指す配列は、印刷スキーマキーワードまたは印刷スキーマフレームワークの名前空間を含める必要はありません。

IPrintTicketProvider オブジェクトを複数回バインドできる必要はありません。印刷チケットマネージャーは、異なるデバイスにバインドするために、常に異なる IPrintTicketProvider オブジェクトインスタンスを使用します。 IPrintTicketProvider::BindPrinter への正常な呼び出しで取得されたすべてのリソースは、IPrintTicketProvider オブジェクトの参照カウントが 0 の場合に解放する必要があります。 プロバイダーは、BindPrinter の呼び出しに渡されたハンドルを閉じないように注意してください。複数のバージョンがサポートされている場合、印刷チケットマネージャーは、異なるバージョンの同じデバイスに対して複数のプロバイダーを作成する場合があります。