WdfIoTargetQueryTargetProperty 関数 (wdfiotarget.h)

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

[KMDF にのみ適用]

WdfIoTargetQueryTargetProperty メソッドは、指定された I/O ターゲットの指定したデバイスプロパティを取得します。

構文

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

パラメーター

[in] IoTarget

WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出し、または特殊化された I/O ターゲットが提供するメソッドから取得されたローカルまたはリモートの I/O ターゲットオブジェクトへのハンドル。

[in] DeviceProperty

取得するデバイスプロパティを識別するDEVICE_REGISTRY_PROPERTY型指定の値。

[in] BufferLength

PropertyBuffer が指すバッファーのサイズ (バイト単位)。

[out, optional] PropertyBuffer

要求されたデバイスプロパティ情報を受け取る呼び出し元によって割り当てられたバッファーへのポインター。 BufferLength が 0 の場合、このポインターは NULL にすることができます。

[out] ResultLength

戻り値として、PropertyBuffer が指すバッファーに格納されている WdfIoTargetQueryTargetProperty の情報のサイズをバイト単位で格納する場所へのポインター。 WdfIoTargetQueryTargetProperty がSTATUS_BUFFER_TOO_SMALLを返す場合、この場所は必要なバッファーサイズを受け取ります。

戻り値

操作が成功した場合、WdfIoTargetQueryTargetProperty はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_BUFFER_TOO_SMALL	PropertyBuffer パラメーターが指すバッファーが小さすぎて、要求された情報を受信できませんでした。
STATUS_INVALID_PARAMETER_2	DeviceProperty パラメーターが指定した値が無効です。
STATUS_INVALID_DEVICE_REQUEST	デバイスのドライバーは、デバイスのプロパティをまだ報告していません。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

ドライバーは、デバイスプロパティデータを受信する前に、通常 、WdfIoTargetQueryTargetProperty メソッドを呼び出して、必要なバッファーサイズを取得します。一部のプロパティでは、データサイズは、必要なサイズが返されたときと、ドライバーが WdfIoTargetQueryTargetProperty を再度呼び出すときの間で変更される可能性があります。したがって、ドライバーは、戻り値の状態がSTATUS_BUFFER_TOO_SMALLされるまで実行されるループ内で WdfIoTargetQueryTargetProperty を呼び出す必要があります。

WdfIoTargetQueryTargetProperty を呼び出す代わりに、ドライバーは WdfIoTargetAllocAndQueryTargetProperty を呼び出すことができます。これにより、バッファーが割り当てられ、プロパティ情報がバッファーに格納されます。

WdfIoTargetQueryTargetProperty の詳細については、「一般的な I/O ターゲットに関する情報の取得」を参照してください。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

例

次のコード例では、デバイスの DevicePropertyUINumber プロパティを取得します。この例では、UI 番号の長さがわかっているため、WdfIoTargetAllocAndQueryTargetProperty ではなく WdfIoTargetQueryTargetProperty を呼び出します。

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)