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
戻り値
IoRegisterDeviceInterface は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 考えられるエラー戻り値は次のとおりです。
| リターン コード | 形容 |
|---|---|
|
パラメーターが無効です。 PhysicalDeviceObject が有効な PDO を指していない場合や、ReferenceString 文字列に無効な文字が含まれていることが考えられます。 |
備考
IoRegisterDeviceInterface
デバイス インターフェイス クラスが以前に登録されていない場合、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) |
関連項目
IoOpenDeviceInterfaceRegistryKey
RtlFreeUnicodeString の