IoRegisterDeviceInterface 関数 (wdm.h)

  • [アーティクル]

IoRegisterDeviceInterface ルーチンは、デバイス インターフェイス クラスを登録します (登録されていない場合)。

構文

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

パラメーター

[in] PhysicalDeviceObject

デバイスの PDO へのポインター。

[in] InterfaceClassGuid

登録されている機能 (デバイス インターフェイス クラス) を識別するクラス GUID へのポインター。

[in, optional] ReferenceString

必要に応じて、UNICODE_STRINGをポイントします。 文字列には、パス区切り文字 ("/" または "\") を含めてはなりません。 通常、関数ドライバーは、このパラメーター NULL を指定します。 フィルター ドライバーでは、NULL指定する必要があります。

参照文字列は、デバイス インターフェイス インスタンスをオンデマンドで作成されたソフトウェア デバイスのプレースホルダーとして使用するバス ドライバーである swenumなど、いくつかのバス ドライバーでのみ使用されます。 インターフェイスのインスタンスが開かれると、I/O マネージャーはインスタンスの参照文字列をドライバーに渡します。 文字列は、インターフェイス インスタンスの名前の一部になります (追加されたパス コンポーネントとして)。 その後、ドライバーは参照文字列を使用して、1 つのデバイスに対して同じクラスの 2 つのインターフェイス インスタンスを区別できます。

Microsoft Windows 98/Me システムでは、ReferenceString の値をMAX_PATH文字以下にすることができます。 Windows 2000 以降のバージョンの Windows には、長さの制限はありません。

[out] SymbolicLinkName

呼び出し元によって割り当てられた Unicode 文字列構造体へのポインター。 このルーチンが成功すると、Unicode 文字列が初期化され、カーネル モード パスを含む文字列バッファーが、指定したデバイス インターフェイス クラスのインスタンスのシンボリック リンクに割り当てられます。

呼び出し元は、SymbolicLinkName を不透明として扱う必要があり、逆アセンブルしないでください。

呼び出し元は、必要なくなったときに、RtlFreeUnicodeString を使用 SymbolicLinkName を解放する必要があります。

戻り値

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

リターン コード 形容
STATUS_INVALID_DEVICE_REQUEST
 パラメーターが無効です。 PhysicalDeviceObject が有効な PDO を指していない場合や、ReferenceString 文字列に無効な文字が含まれていることが考えられます。

備考

IoRegisterDeviceInterface 、デバイス インターフェイス クラスが登録されていない場合は登録し、インターフェイス クラスの新しいインスタンスを作成します。 ドライバーは、特定のデバイスに対してこのルーチンを複数回呼び出して、複数のインターフェイス クラスを登録し、クラスのインスタンスを作成できます。 通常、関数またはフィルター ドライバーは、AddDevice ルーチンにデバイス インターフェイスを登録します。 たとえば、フォールト トレラント ボリューム ドライバーでは、フォールト トレラント ボリューム インターフェイスのインスタンスと、特定のボリュームのボリューム インターフェイスのインスタンスを登録できます。

デバイス インターフェイス クラスが以前に登録されていない場合、I/O マネージャーは、そのキーの下にインスタンス固有の永続ストレージと共にレジストリ キーを作成します。 ドライバーは、IoOpenDeviceInterfaceRegistryKeyを使用して、この永続的な記憶域にアクセスできます。

ドライバーは、インターフェイス インスタンスを 1 回登録し、IoSetDeviceInterfaceState を呼び出して、インターフェイスを有効または無効にします。

登録済みインターフェイスは、オペレーティング システムの再起動後も保持されます。 指定したインターフェイスが既に登録されている場合、I/O マネージャーは、その名前 SymbolicLinkName で渡し、情報の成功状態STATUS_OBJECT_NAME_EXISTSを返します。

ほとんどのドライバーは、デバイス インターフェイス インスタンスに対して NULL 参照文字列を使用します。 ドライバーが非NULL 参照文字列を使用する場合は、独自の名前空間とセキュリティの管理など、追加の作業を行う必要があります。 デバイス インターフェイスを公開するフィルター ドライバーは、デバイス スタック内の他のドライバーとの競合を回避するために、NULLReferenceString を使用する必要があります。

このルーチンの呼び出し元は、不要になったときにデバイス インターフェイスの登録を削除する必要はありません。 必要に応じて、デバイス インターフェイスの登録をユーザー モードから削除できます。

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

必要条件

要件 価値
サポートされる最小クライアント Windows 2000 以降で使用できます。
ターゲット プラットフォーム の 万国
ヘッダー wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
ライブラリ NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 を する HwStorPortProhibitedDDDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

関連項目

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString の