IoSetDeviceInterfaceState-Funktion (wdm.h)

Artikel
08/08/2023

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

Syntax

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

Parameter

[in] SymbolicLinkName

Zeiger auf eine Zeichenfolge, die die Geräteschnittstelle instance identifiziert, die aktiviert oder deaktiviert wird. Diese Zeichenfolge wurde aus einem vorherigen Aufruf von IoRegisterDeviceInterface oder IoGetDeviceInterfaces abgerufen.

[in] Enable

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

Rückgabewert

IoSetDeviceInterfaceState gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Diese Routine gibt eine informationsfähige status von STATUS_OBJECT_NAME_EXISTS zurück, wenn der Aufrufer aufgefordert hat, eine bereits aktivierte Geräteschnittstelle zu aktivieren. Mögliche Fehlerrückgabewerte werden im Folgenden beschrieben.

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

Hinweise

IoSetDeviceInterfaceState ermöglicht eine instance einer registrierten Geräteschnittstelle zur Verwendung durch Anwendungen und andere Systemkomponenten. Die Schnittstellenklasse muss zuvor bei IoRegisterDeviceInterface oder im 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 auf , wobei Enable auf TRUE festgelegt ist, nachdem ein Gerät als Reaktion auf eine IRP_MN_START_DEVICE IRP erfolgreich gestartet wurde. Ein solcher Treiber sollte die Geräteschnittstelle instance deaktivieren (d. h. IoSetDeviceInterfaceState aufrufen und Enable auf FALSE festlegen), wenn das Gerät als Reaktion auf eine IRP_MN_REMOVE_DEVICE IRP oder eine IRP_MN_SURPRISE_REMOVAL IRP entfernt wird. Wenn ein Treiber beim Verarbeiten dieser Entfernungs-IRPs keine Geräteschnittstelle deaktiviert, sollte der Treiber dies später nicht versuchen, 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 überraschende Entfernung), aber immer noch über eine gültige Geräteschnittstelle instance 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äteschnittstelle instance aktiviert, die im gleichen Registrierungspfad wie die vorhandene Geräteschnittstelle instance vorhanden ist.

Wenn der Treiber IoSetDeviceInterfaceState aufruft, um als Reaktion auf eine IRP_MN_SURPRISE_REMOVAL IRP eine Geräteschnittstelle instance zu deaktivieren, darf der Treiber nicht versuchen, dieselbe Geräteschnittstelle instance als Reaktion auf eine IRP_MN_REMOVE_DEVICE IRP zu deaktivieren.

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

Der PnP-Manager sendet erst nach Abschluss des IRP_MN_START_DEVICE IRP eine Benachrichtigung über die Schnittstelle instance, 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 die 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
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)