IoSetDeviceInterfaceState 関数 (wdm.h)

  • [アーティクル]

IoSetDeviceInterfaceState ルーチンは、以前に登録されたデバイス インターフェイス クラスのインスタンスを有効または無効にします。

構文

NTSTATUS IoSetDeviceInterfaceState(
  [in] PUNICODE_STRING SymbolicLinkName,
  [in] BOOLEAN         Enable
);

パラメーター

[in] SymbolicLinkName

有効または無効になっているデバイス インターフェイス インスタンスを識別する文字列へのポインター。 この文字列は、 IoRegisterDeviceInterface または IoGetDeviceInterfaces の以前の呼び出しから取得 されました。

[in] Enable

TRUE は 、デバイス インターフェイスが有効になっていることを示します。 FALSE は 、デバイス インターフェイスが無効になっていることを示します。

戻り値

呼び出しが成功した場合、IoSetDeviceInterfaceState はSTATUS_SUCCESSを返します。 このルーチンは、呼び出し元が既に有効になっているデバイス インターフェイスを有効にするように要求した場合に、STATUS_OBJECT_NAME_EXISTSの情報状態を返します。 エラーの可能性がある戻り値については、以下で説明します。

リターン コード 説明
STATUS_OBJECT_NAME_NOT_FOUND
 呼び出し元が、有効になっていないデバイス インターフェイスを無効にしようとしました。

注釈

IoSetDeviceInterfaceState を使用すると、登録済みデバイス インターフェイスのインスタンスをアプリケーションや他のシステム コンポーネントで使用できます。 インターフェイス クラスは、以前に IoRegisterDeviceInterface またはユーザー モードで登録されている必要があります。

アプリケーションやその他のシステム コンポーネントは、有効になっているインターフェイスのみを開くことができます。

関数またはフィルター ドライバーは、通常、IRP_MN_START_DEVICEIRP に応答してデバイスを正常に起動した後、有効に TRUE に設定されたこのルーチンを呼び出します。 このようなドライバーは、IRP_MN_REMOVE_DEVICE IRP またはIRP_MN_SURPRISE_REMOVAL IRP に応答してデバイスを削除するときに、デバイス インターフェイス インスタンスを無効にする必要があります (つまり、IoSetDeviceInterfaceState を呼び出し、有効にするを FALSE に設定します)。 ドライバーがこれらの削除 IRP を処理するときにデバイス インターフェイスを無効にしない場合、PnP マネージャーは、PnP マネージャーがデバイスを削除するときに、PnP マネージャーがインターフェイスを無効にするため、ドライバーは、その後、これを試みないでください。

デバイスが突然削除された場合 (たとえば、突然の削除) が有効なデバイス インターフェイス インスタンスをまだ持っている場合は、デバイスが再アタッチされた場合に問題が発生します。 この問題は、PnP マネージャーが新しく接続されたデバイスを列挙し、既存のデバイス インターフェイス インスタンスと同じレジストリ パスに存在するデバイス インターフェイス インスタンスを有効にすると発生します。

ドライバーが IoSetDeviceInterfaceState を呼び出して 、IRP_MN_SURPRISE_REMOVAL IRP に応答してデバイス インターフェイス インスタンスを無効にする場合、ドライバーは、 IRP_MN_REMOVE_DEVICE IRP に応答して同じデバイス インターフェイス インスタンスを無効にしようとしないことに注意してください。

IoSetDeviceInterfaceState の呼び出しでデバイス インターフェイス インスタンスが正常に公開された場合、システムは PnP 通知に登録されたすべてのコンポーネントにデバイス クラスの変更を通知します。 同様に、このルーチンの呼び出しによって既存のデバイス インターフェイス インスタンスが無効にされた場合、システムは適切な通知を送信します。

PnP マネージャーは、デバイスのすべてのドライバーが開始操作を完了したことを示す 、IRP_MN_START_DEVICE IRP が完了するまで、インターフェイス インスタンスの到着の通知を送信しません。 さらに、PnP マネージャーは、 IRP_MN_START_DEVICE IRP が完了するまで、デバイスの作成要求を失敗します。

IoSetDeviceInterfaceState の呼び出し元は、システム スレッドのコンテキストで 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), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)

こちらもご覧ください

IRP_MN_REMOVE_DEVICE

IRP_MN_START_DEVICE

IRP_MN_SURPRISE_REMOVAL

IoGetDeviceInterfaces

IoRegisterDeviceInterface

IoRegisterPlugPlayNotification