IoSetDeviceInterfaceState-Funktion (wdm.h)

Artikel
02/07/2025

Die IoSetDeviceInterfaceState Routine aktiviert oder deaktiviert eine Instanz einer zuvor registrierten Geräteschnittstellenklasse.

Syntax

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

Parameter

[in] SymbolicLinkName

Zeigen Sie auf eine Zeichenfolge, die die Geräteschnittstelleninstanz identifiziert, die aktiviert oder deaktiviert wird. Diese Zeichenfolge wurde aus einem vorherigen Aufruf von IoRegisterDeviceInterface oder IoGetDeviceInterfacesabgerufen.

[in] Enable

TRUE gibt an, dass die Geräteschnittstelle aktiviert ist. FALSE gibt an, dass die Geräteschnittstelle deaktiviert ist.

Rückgabewert

IoSetDeviceInterfaceState gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Diese Routine gibt einen Informationsstatus von STATUS_OBJECT_NAME_EXISTS zurück, wenn der Aufrufer angefordert hat, eine bereits aktivierte Geräteschnittstelle zu aktivieren. Mögliche Fehlerrücklaufwerte werden wie folgt beschrieben.

Rückgabecode	Beschreibung
STATUS_OBJECT_NAME_NOT_FOUND	Der Aufrufer hat versucht, eine nicht aktivierte Geräteschnittstelle zu deaktivieren.

Bemerkungen

IoSetDeviceInterfaceState ermöglicht eine Instanz einer registrierten Geräteschnittstelle für die Verwendung durch Anwendungen und andere Systemkomponenten. Die Schnittstellenklasse muss zuvor bei IoRegisterDeviceInterface oder aus dem Benutzermodus registriert worden sein.

Anwendungen und andere Systemkomponenten können nur schnittstellen öffnen, die aktiviert sind.

Eine Funktion oder ein Filtertreiber ruft diese Routine in der Regel mit Enable set to TRUE after it successfully starts a device in response to an IRP_MN_START_DEVICE IRP. Ein solcher Treiber sollte die Geräteschnittstelleninstanz deaktivieren (d. h. IoSetDeviceInterfaceState aufrufen und Aktivieren von auf FALSE) festlegen, wenn es das Gerät als Reaktion auf ein IRP_MN_REMOVE_DEVICE IRP oder ein IRP_MN_SURPRISE_REMOVAL IRP entfernt. Wenn ein Treiber beim Verarbeiten dieser Entfernungs-IRPs keine Geräteschnittstelle deaktiviert, sollte der Treiber später nicht versuchen, dies zu tun, da der PnP-Manager die Schnittstelle deaktiviert, wenn der PnP-Manager das Gerät entfernt.

Wenn ein Gerät plötzlich entfernt wird (z. B. durch eine Überraschungsentfernung), aber dennoch über eine gültige Geräteschnittstelleninstanz verfügt, tritt ein Problem auf, wenn das Gerät erneut angefügt wird. Dieses Problem tritt auf, wenn der PnP-Manager das neu angefügte Gerät aufzählt und eine Geräteschnittstelleninstanz aktiviert, die im selben Registrierungspfad wie die vorhandene Geräteschnittstelleninstanz vorhanden ist.

Beachten Sie: Wenn der Treiber IoSetDeviceInterfaceState aufruft, um eine Geräteschnittstelleninstanz als Reaktion auf eine IRP_MN_SURPRISE_REMOVAL IRP zu deaktivieren, darf der Treiber nicht versuchen, die gleiche Geräteschnittstelleninstanz als Reaktion auf eine IRP_MN_REMOVE_DEVICE IRP zu deaktivieren.

Wenn ein Aufruf von IoSetDeviceInterfaceState erfolgreich eine Geräteschnittstelleninstanz verfügbar macht, benachrichtigt das System alle Komponenten, die für die PnP-Benachrichtigung einer Geräteklassenänderung registriert sind. Wenn ein Aufruf dieser Routine eine vorhandene Geräteschnittstelleninstanz deaktiviert, sendet das System entsprechende Benachrichtigungen.

Der PnP-Manager sendet erst Benachrichtigungen über Die Ankunft von Schnittstelleninstanzen, bis die IRP_MN_START_DEVICE IRP abgeschlossen ist, was angibt, dass alle Treiber für das Gerät ihre Startvorgänge abgeschlossen haben. Darüber hinaus schlägt der PnP-Manager fehler beim Erstellen von Anforderungen für das Gerät, bis der IRP_MN_START_DEVICE IRP abgeschlossen ist.

Aufrufer von IoSetDeviceInterfaceState- müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Ab Windows 2000 verfügbar.
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)