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 以降で使用できます。
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

こちらもご覧ください

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString