IoGetDeviceProperty 関数 (wdm.h)

IoGetDeviceProperty ルーチンは、構成情報とその PDO の名前などのデバイスに関する情報を取得します。

構文

NTSTATUS IoGetDeviceProperty(
  [in]            PDEVICE_OBJECT           DeviceObject,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

パラメーター

[in] DeviceObject

クエリ対象のデバイスの物理デバイス オブジェクト (PDO) へのポインター。

[in] DeviceProperty

要求されるデバイス プロパティを指定します。 次の DEVICE_REGISTRY_PROPERTY 列挙値のいずれかである必要があります。

DevicePropertyAddress

バス上のデバイスのアドレスを要求します。 PropertyBuffer は ULONG を指します。

このアドレスの解釈はバス固有です。 このルーチンの呼び出し元は、もう一度ルーチンを呼び出して DevicePropertyBusTypeGuid または 場合によっては DevicePropertyLegacyBusType を要求して、アドレスを解釈できるようにする必要があります。 0xFFFFFFFF のアドレス値は、基になるバス ドライバーがデバイスのバス アドレスを指定しなかったことを示します。

次の一覧では、特定のバス ドライバーが子デバイスの PropertyBuffer に格納する情報について説明します。

DevicePropertyBootConfiguration

ファームウェアによってデバイスに割り当てられたハードウェア リソースを未加工の形式で要求します。 PropertyBuffer は、CM_RESOURCE_LIST構造体を指します。

DevicePropertyBootConfigurationTranslated

ファームウェアによってデバイスに割り当てられたハードウェア リソース (変換形式)。 PropertyBuffer は、CM_RESOURCE_LIST構造体を指します。

DevicePropertyBusNumber

デバイスが接続されているバスのレガシ バス番号を要求します。 PropertyBuffer は ULONG を指します。

DevicePropertyBusTypeGuid

デバイスが接続されているバスの GUID を要求します。 システム定義のバスの種類 GUID は、Wdmguid.h ヘッダー ファイルに一覧表示されます。 PropertyBuffer は GUID を指します。これは、バイナリ形式の GUID を含む 16 バイトの構造体です。

DevicePropertyClassGuid

デバイスのセットアップ クラスの GUID を要求します。 PropertyBuffer は 、WCHAR の NULL で終わる配列を指します。 このルーチンは、次のように文字列形式で GUID を返します。各 "c" は 16 進数の文字を表します: {cccccccc-cccc-cccc-cccccccccc}

DevicePropertyClassName

デバイスのセットアップ クラスの名前をテキスト形式で要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyCompatibleIDs

デバイスによって報告された 互換性のある ID を 要求します。 PropertyBuffer は 、REG_MULTI_SZ値を指します。

DevicePropertyDeviceDescription

デバイスを記述する文字列 ("Microsoft PS/2 ポート マウス" など) を要求します。通常は製造元によって定義されます。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyDriverKeyName

ドライバー固有のレジストリ キーの名前を要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyEnumeratorName

"PCI" や "root" など、デバイスの列挙子の名前を要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyFriendlyName

2 つの類似デバイス (通常はクラス インストーラーによって定義される) を区別するために使用できる文字列を要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyHardwareID

デバイスを識別するデバイスによって提供される ハードウェア ID を要求します。 PropertyBuffer は 、REG_MULTI_SZ値を指します。

DevicePropertyInstallState

デバイスのインストール状態を要求します。 インストール状態は、 DEVICE_INSTALL_STATE 列挙値として返されます。

DevicePropertyLegacyBusType

PCIBus や PCMCIABus などのバスの種類を要求します。 PropertyBuffer は、INTERFACE_TYPE列挙値を指します。

DevicePropertyLocationInformation

バス上のデバイスの場所に関する情報を要求します。この情報の解釈はバス固有です。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyManufacturer

デバイスの製造元を識別する文字列を要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyPhysicalDeviceObjectName

このデバイスの PDO の名前を要求します。 PropertyBuffer は 、NULL で終わる WCHAR 文字列を指します。

DevicePropertyRemovalPolicy

デバイスの現在の削除ポリシーを要求します。 オペレーティング システムでは、この値をヒントとして使用して、デバイスが通常どのように削除されるかを判断します。 PropertyBuffer パラメーターは、DEVICE_REMOVAL_POLICY列挙値を指します。

DevicePropertyUINumber

ユーザー インターフェイスに表示できるデバイスに関連付けられている番号を要求します。 PropertyBuffer は ULONG 値を指します。

通常、この番号は、ボード上のスロットの横に印刷される番号や、ユーザーが物理デバイスを見つけやすくするその他の番号など、ユーザーが認識するスロット番号です。 デバイスが UI 番号規則のないバス上にある場合、またはデバイスのバス ドライバーが UI 番号を特定できない場合、この値は0xFFFFFFFF。

[in] BufferLength

呼び出し元から指定された PropertyBuffer のサイズをバイト単位で指定します。

[out, optional] PropertyBuffer

プロパティ情報を受け取る呼び出し元が指定したバッファーへのポインター。 バッファーはページング可能メモリから割り当て可能です。 バッファーの種類は、 DeviceProperty によって決まります (上記を参照)。

[out] ResultLength

PropertyBuffer で返されるプロパティ情報のサイズを受け取る ULONG へのポインター。 IoGetDeviceProperty が STATUS_BUFFER_TOO_SMALLを返す場合は、このパラメーターを必要なバッファー長に設定します。

戻り値

呼び出しが成功した場合、IoGetDeviceProperty はSTATUS_SUCCESSを返します。 エラーの戻り値として考えられるのは、次のとおりです。

注釈

IoGetDeviceProperty は、レジストリからデバイスのセットアップ情報を取得します。 このルーチンを使用して、レジストリに直接アクセスするのではなく、プラットフォーム間の違いとレジストリ構造の変更の可能性からドライバーを絶縁します。

多くの DeviceProperty 要求では、 IoGetDeviceProperty を 2 回以上呼び出して、必要な BufferLength を決定できます。 最初の呼び出しでは、最適な推測値を使用する必要があります。 戻り値の状態がSTATUS_BUFFER_TOO_SMALL場合、ドライバーは現在のバッファーを解放し、 ResultLength で返されるサイズのバッファーを割り当てて、 IoGetDeviceProperty をもう一度呼び出す必要があります。 一部のセットアップ プロパティは動的であるため、必要なサイズが返され、ドライバーがこのルーチンを再度呼び出すまでの間に、データ サイズが変更される可能性があります。 そのため、ドライバーは、戻り状態がSTATUS_BUFFER_TOO_SMALLされないまで実行されるループ内で IoGetDeviceProperty を呼び出す必要があります。

レガシ バスと PnP バス上のデバイスをサポートするファンクション ドライバーでは、 DevicePropertyBusNumber、 DevicePropertyBusTypeGuid、 および DevicePropertyLegacyBusType プロパティを使用して、バスを区別できます。

要件

こちらもご覧ください

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST