IoGetDeviceInterfaces 関数 (wdm.h)

  • [アーティクル]

IoGetDeviceInterfaces ルーチンは、特定のデバイス インターフェイス クラス (HID インターフェイスをサポートするシステム上のすべてのデバイスなど) のデバイス インターフェイス インスタンスの一覧を返します。

構文

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

パラメーター

[in] InterfaceClassGuid

デバイス インターフェイス クラスを指定するクラス GUID へのポインター。 クラスの GUID は、デバイス固有のヘッダー ファイルに含める必要があります。

[in, optional] PhysicalDeviceObject

PDO によって表されるデバイスのデバイス インターフェイス インスタンスのみに検索を絞り込むオプションの PDO へのポインター。

[in] Flags

デバイス インターフェイスの検索を変更するフラグを指定します。 現在定義されているフラグは 1 つだけで、次の表で説明します。

フラグ 説明
DEVICE_INTERFACE_INCLUDE_NONACTIVE 有効なインターフェイス インスタンスに加えて、無効なデバイス インターフェイス インスタンスを返します。
 

特定のインターフェイス クラスをサポートするデバイスを検索する場合、呼び出し元は有効なインターフェイス インスタンスを必要とするため、DEVICE_INTERFACE_INCLUDE_NONACTIVE フラグを設定しません。

ドライバーは通常、ドライバーが有効にする必要がある無効なインターフェイス インスタンスを見つけるために、DEVICE_INTERFACE_INCLUDE_NONACTIVE フラグを設定します。 たとえば、デバイスのクラス インストーラーは、デバイスの 1 つ以上のインターフェイス インスタンスを登録する INF ファイルによって指示されている可能性があります。 インターフェイス インスタンスは登録されますが、ドライバーによって有効になるまでは使用できません ( IoSetDeviceInterfaceState を使用)。 返されるインターフェイス インスタンスの一覧を特定のデバイスによって公開されるインターフェイス インスタンスのみに絞り込むには、ドライバーで PhysicalDeviceObject を指定できます。

[out] SymbolicLinkList

ルーチンが成功した場合、Unicode 文字列のリストを含むバッファーのベース アドレスを書き込むワイド文字ポインターへのポインター。 これらの文字列は、検索条件に一致するデバイス インターフェイス インスタンスを識別するシンボリック リンク名です。 リスト内の各 Unicode 文字列は null で終わる。リスト全体の末尾は、追加の null 文字でマークされます。 ルーチンは、ページ システム メモリからこれらの文字列のバッファーを割り当てます。 呼び出し元は、不要になったときに ( ExFreePool ルーチンを呼び出すことによって) バッファーを解放する役割を担います。

検索条件に一致するデバイス インターフェイス インスタンスがない場合、このルーチンは STATUS_SUCCESSを返し、文字列には 1 つの NULL 文字が含まれます。

戻り値

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

リターン コード 説明
STATUS_INVALID_DEVICE_REQUEST
 PhysicalDeviceObject が有効な PDO ポインターではなかったことを示している可能性があります。

注釈

IoGetDeviceInterfaces は、 検索条件に一致するデバイス インターフェイス インスタンスの一覧を返します。 通常、カーネル モード コンポーネントは、このルーチンを呼び出して、特定のデバイス インターフェイス クラスのすべての有効なデバイス インターフェイス インスタンスの一覧を取得します。 このようなコンポーネントは、 IoGetDeviceObjectPointer ルーチンまたは ZwCreateFile ルーチンを呼び出すことによって、インターフェイスのファイル オブジェクトやデバイス オブジェクトへのポインターを取得できます。 IoGetDeviceObjectPointer によって返されるデバイス オブジェクト ポインターは、デバイスのデバイス スタックの最上位を指し、IoCallDriver ルーチンの呼び出しで使用できます。

要求されたデバイス インターフェイス クラスの既定のインターフェイスがある場合は、 最初に SymbolicLinkList に一覧表示されます。 既定のインターフェイスはユーザー モードで設定できますが、カーネル モードでは設定できません。

シンボリック リンク名の形式は不透明です。呼び出し元はシンボリック リンク名の解析を試みてはいけません。

デバイス インターフェイス インスタンスのシンボリック リンクは、システム ブート間で使用できます。

特定のクラスの追加のデバイス インターフェイス インスタンスがシステムで有効になったときに通知されるようにするには、 IoRegisterPlugPlayNotification ルーチンを呼び出して、デバイス クラスの変更の通知に登録します。

IoGetDeviceInterfaces の呼び出し元は、システム スレッドのコンテキストで IRQL = PASSIVE_LEVELで実行されている必要があります。

要件

要件 値
サポートされている最小のクライアント Windows 2000 以降で使用できます。
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)

こちらもご覧ください

ExFreePool

IoCallDriver

IoGetDeviceObjectPointer

IoRegisterDeviceInterface

IoRegisterPlugPlayNotification

IoSetDeviceInterfaceState

ZwCreateFile