IPrintOemUI::D eviceCapabilities メソッド (prcomoem.h)

  • [アーティクル]

IPrintOemUI::DeviceCapabilitiesメソッドを使用すると、ユーザー インターフェイス プラグインでカスタマイズされたデバイス機能を指定できます。

構文

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

パラメーター

poemuiobj

OEMUIOBJ 構造体への呼び出し元指定ポインター。

hPrinter

プリンター デバイスへの呼び出し元指定ハンドル。

pDeviceName

デバイス名を表す文字列への呼び出し元指定ポインター。

wCapability

メソッドが返す必要がある情報の種類を示す呼び出し元から指定されたフラグ。 フラグの一覧については、 DrvDeviceCapabilities 関数の説明を参照してください。

pOutput

要求された情報を受け取るバッファーへの呼び出し元指定ポインター。 返される情報の種類は、 wCapability で指定されたフラグによって異なります。

pPublicDM

検証済みの DEVMODEW 構造体への呼び出し元指定ポインター。

pOEMDM

ユーザー インターフェイス プラグインのプライベート DEVMODEW 構造体メンバーへの呼び出し元指定ポインター。

dwOld

プリンター ドライバーの DrvDeviceCapabilities 関数または別のユーザー インターフェイス プラグインから呼び出し元から指定された戻り値。 詳細については、「解説」を参照してください。

dwResult

wCapability で指定されたフラグに依存する戻り値。 詳細については、 DrvDeviceCapabilities 関数の説明と、次の「解説」セクションを参照してください。

戻り値

メソッドは、次のいずれかの値を返す必要があります。

リターン コード 説明
S_OK
 操作が成功しました。
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 プラグインは、 pOutput パラメーターが指すバッファーを独自の目的で使用することを意図しています。 この戻り値は prcomoem.h で定義されています。 この戻り値を使用するタイミングの詳細については、次の「解説」セクションを参照してください。
E_FAIL
 操作が失敗しました。
E_NOTIMPL
 このメソッドは実装されていません。

注釈

ユーザー インターフェイス プラグインの IPrintOemUI::DeviceCapabilities メソッドは、ユーザー モード プリンター インターフェイス DLL によってエクスポートされる DrvDeviceCapabilities 関数と同じ種類の操作を実行します。 メソッドは、プリンターによって提供される機能を指定します。

このメソッドを IPrintOemUI::DeviceCapabilities 使用すると、機能に対する Unidrv のサポートを受け入れるか、プリンター ドライバーが提供しない機能を追加できます。 ドライバーは、DrvDeviceCapabilities 関数内から を呼び出IPrintOemUI::DeviceCapabilitiesします。

メソッドが機能の IPrintOemUI::DeviceCapabilities カスタマイズされたサポートを示している場合 (受信したDC_FIELDS フラグに応じて適切なビットを設定することによって)、カスタマイズされたコードは機能を完全にサポートする必要があります。 完全なサポートには、通常、 メソッドの呼び出しに応じて機能に関する情報を IPrintOemUI::DeviceCapabilities 返すことと、機能を実装するための適切なユーザー モードまたはカーネル モード コードの提供が含まれます。

メソッドが複数のユーザー インターフェイス プラグインによってエクスポートされる場合 IPrintOemUI::DeviceCapabilities 、インストール用にプラグインが指定された順序でメソッドが呼び出されます。 プラグインの IPrintOemUI::DeviceCapabilities メソッドが呼び出されるたびに、 その dwOld 入力値は、以前に呼び出されたプラグインの IPrintOemUI::DeviceCapabilities メソッドからの戻り値になります。 最初に呼び出されたプラグインの 場合、dwOld にはプリンター ドライバーの DrvDeviceCapabilities 関数からの戻り値が含まれています。 同様に、 pOutput が指すバッファーには、入力時に、以前に呼び出 IPrintOemUI::DeviceCapabilities されたメソッドまたは DrvDeviceCapabilities 関数によってそこに配置されたコンテンツが含まれます。

複数のユーザー インターフェイス プラグインが相互に連携して動作するには、各 IPrintOemUI::DeviceCapabilities メソッドが次の規則に従う必要があります。

  • ユーザー インターフェイス プラグインが指定された機能をサポートしていない場合、そのIPrintOemUI::DeviceCapabilitiesメソッドは dwResult の dwOld パラメーターの内容を返すだけです。
  • ユーザー インターフェイス プラグインで機能がサポートされている場合、その IPrintOemUI::DeviceCapabilities メソッドは dwOld と pOutput が指すバッファーの内容を無視する必要があります。 指定した機能をサポートしていることを示す適切な戻り値とバッファーの内容を提供する必要があります。 メソッドがエラーを検出した場合は、 dwResult でGDI_ERRORを返す必要があります。
  • ユーザー インターフェイス プラグインで pOutput が指すバッファーで受信した機能情報を変更する場合、その IPrintOemUI::DeviceCapabilities メソッドはバッファーの内容を変更し、 dwResult で適切な戻り値を返す必要があります。 たとえば、 wCapability がDC_FIELDSの場合、メソッドは dwOld に設定されているビットで設定する必要があるビットを OR し、 dwResult で OR 演算の結果を返す必要があります。
  • dwOld の受信した内容がGDI_ERROR場合でも、上記の規則に従う必要があります。
ドライバーの DrvDeviceCapabilities 関数が DC_FIELDS フラグを設定して呼び出されると、関数はすべての IPrintOemUI::DeviceCapabilities メソッドを呼び出し、DC_FIELDSも指定し、すべてのセット ビットの和集合を呼び出し元に返します。

S_DEVCAP_OUTPUT_FULL_REPLACEMENT戻り値は Windows Vista では新しく、Unidrv と Pscript5 の両方のユーザー インターフェイス プラグインに適用されます。プラグインは、 pOutput パラメーターが指すバッファーに配置される内容を完全に制御する必要がある場合にのみ、S_DEVCAP_OUTPUT_FULL_REPLACEMENT戻り値を使用する必要があります。 プラグインがS_DEVCAP_OUTPUT_FULL_REPLACEMENTを返すとき、Unidrv も Pscript5 コア ドライバーも pOutput バッファーにデータを配置しません。 DEVMODEW 構造体 (pPublicDM パラメーターと pOEMDM パラメーターが指す) の設定が、GPD または PPD ファイルで指定されたデータとは異なるデバイス機能データを報告する必要があることをユーザー インターフェイス プラグインに示す場合、プラグインは、この値を返す必要がある場合があります。 たとえば、写真の印刷を指定する DEVMODEW 構造体では、GPD または PPD ファイルで指定されているものとは異なる用紙の種類のセットが必要な場合があります。 このような状況では、 pOutput パラメーターと dwOld パラメーターの値に関係なく、プラグインは S_DEVCAP_OUTPUT_FULL_REPLACEMENTを返し、 dwResult パラメーターをレポートする用紙の種類の数に設定する必要があります。 pOutput が NULL でない場合、プラグインは pOutput が指すバッファーにも目的の用紙の種類のセットを入力し、dwResult をプラグインが報告する用紙の種類の数に設定する必要があります。

複数のユーザー インターフェイス プラグインが同時にアクティブで、そのうちの 1 つがS_DEVCAP_OUTPUT_FULL_REPLACEMENTを返す場合、Unidrv または Pscript5 コア ドライバーはこの戻り値を解釈して、プラグインが完全な置換出力データを提供することを意味します。 その結果、コア ドライバーは、プラグインを呼び出す前に pOutput バッファーにデータを配置しません。(コア ドライバーは、インストールに指定された順序と同じ順序でプラグインを呼び出します。

コア ドライバーが pOutput バッファーに配置する値を置き換える必要がない場合、プラグインはS_OKを返す必要があります。 Unidrv および Pscript5 コア ドライバーは、 pOutput バッファーを使用するデバイス機能に対してのみ、S_DEVCAP_OUTPUT_FULL_REPLACEMENT戻り値を認識します。つまり、 wCapability パラメーターが次のいずれかのフラグに設定されている場合です。

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

ユーザー インターフェイス プラグインの作成とインストールの詳細については、「 Microsoft のプリンター ドライバーのカスタマイズ」を参照してください。

要件

要件 値
対象プラットフォーム デスクトップ
Header prcomoem.h (Prcomoem.h を含む)

こちらもご覧ください

DrvDeviceCapabilities

IPrintOemUI