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 に格納する情報について説明します。
| バス型 | 説明 |
|---|---|
| 1394 | アドレスは揮発性であるため、アドレスを指定しません。 既定値は 0xFFFFFFFF です。 |
| Eisa | スロット番号 (0 から F)。 |
| IDE | IDE デバイスの場合、アドレスにはターゲット ID と LUN が含まれます。 IDE チャネルの場合、アドレスは 0 または 1 です (0 = プライマリ チャネル、1 = セカンダリ チャネル)。 |
| ISApnp | アドレスを指定しません。 既定値は 0xFFFFFFFF です。 |
| PC カード (PCMCIA) | ソケット番号 (通常は0x00または0x40)。 |
| PCI | 高い単語のデバイス番号と低い単語の関数番号。 |
| SCSI | ターゲット ID。 |
| USB | ポート番号。 |
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を返します。 エラーの戻り値として考えられるのは、次のとおりです。
| リターン コード | 説明 |
|---|---|
| STATUS_BUFFER_TOO_SMALL | PropertyBuffer のバッファーが小さすぎます。 ResultLength は 、必要なバッファー長を指します。 |
| STATUS_INVALID_PARAMETER_2 | 指定された DeviceProperty は、このルーチンによって処理されるプロパティの 1 つではありません。 |
| STATUS_INVALID_DEVICE_REQUEST | 指定された DeviceObject が有効な PDO ポインターではなかったことを示している可能性があります。 |
注釈
IoGetDeviceProperty は、レジストリからデバイスのセットアップ情報を取得します。 このルーチンを使用して、レジストリに直接アクセスするのではなく、プラットフォーム間の違いとレジストリ構造の変更の可能性からドライバーを絶縁します。
多くの DeviceProperty 要求では、 IoGetDeviceProperty を 2 回以上呼び出して、必要な BufferLength を決定できます。 最初の呼び出しでは、最適な推測値を使用する必要があります。 戻り値の状態がSTATUS_BUFFER_TOO_SMALL場合、ドライバーは現在のバッファーを解放し、 ResultLength で返されるサイズのバッファーを割り当てて、 IoGetDeviceProperty をもう一度呼び出す必要があります。 一部のセットアップ プロパティは動的であるため、必要なサイズが返され、ドライバーがこのルーチンを再度呼び出すまでの間に、データ サイズが変更される可能性があります。 そのため、ドライバーは、戻り状態がSTATUS_BUFFER_TOO_SMALLされないまで実行されるループ内で IoGetDeviceProperty を呼び出す必要があります。
レガシ バスと PnP バス上のデバイスをサポートするファンクション ドライバーでは、 DevicePropertyBusNumber、 DevicePropertyBusTypeGuid、 および DevicePropertyLegacyBusType プロパティを使用して、バスを区別できます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 以降で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |