IRP_MN_CHANGE_SINGLE_ITEM

Artikel
06/15/2023

Alle Treiber, die WMI unterstützen, müssen diese IRP verarbeiten. Ein Treiber kann WMI-IRPs verarbeiten, indem er WmiSystemControl aufruft oder den IRP selbst verarbeitet, wie unter Behandeln von WMI-Anforderungen beschrieben.

Wenn ein Treiber WmiSystemControl aufruft, um eine IRP_MN_CHANGE_SINGLE_ITEM Anforderung zu verarbeiten, ruft WMI wiederum die DpWmiSetDataItem-Routine dieses Treibers auf.

Hauptcode

IRP_MJ_SYSTEM_CONTROL

Sendebedingungen

WMI sendet diesen IRP, um ein einzelnes Datenelement in einer einzelnen instance eines Datenblocks zu ändern.

WMI sendet diesen IRP unter IRQL = PASSIVE_LEVEL in einem beliebigen Threadkontext.

Eingabeparameter

Parameters.WMI.ProviderId verweist auf das Geräteobjekt des Treibers, das auf die Anforderung reagieren soll. Dieser Zeiger befindet sich am E/A-Stapelspeicherort des Treibers im IRP.

Parameters.WMI.DataPath verweist auf eine GUID, die den festzulegenden Datenblock identifiziert.

Parameters.WMI.BufferSize gibt die Größe des nicht auslagerten Puffers unter Parameters.WMI.Buffer an.

Parameters.WMI.Buffer verweist auf eine WNODE_SINGLE_ITEM Struktur, die die instance des Datenblocks, die ID des festzulegenden Elements und einen neuen Datenwert identifiziert.

Ausgabeparameter

Keine.

E/A-Statusblock

Wenn der Treiber die IRP durch Aufrufen von WmiSystemControl verarbeitet, legt WMI Irp-IoStatus.Status> und Irp-IoStatus.Information im E/A-status-Block> fest.

Andernfalls legt der Treiber Irp-IoStatus.Status> auf STATUS_SUCCESS oder auf einen entsprechenden Fehler status wie den folgenden fest:

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

Bei Erfolg legt ein Treiber Irp-IoStatus.Information> auf Null fest.

Vorgang

Wenn ein Treiber WMI IRPs verarbeitet, indem er WmiSystemControl aufruft, ruft diese Routine die DpWmiSetDataItem-Routine des Treibers auf oder gibt STATUS_WMI_READ_ONLY zurück, wenn der Treiber die Routine nicht definiert.

Wenn ein Treiber IRP_MN_CHANGE_SINGLE_ITEM Anforderungen selbst verarbeitet, sollte er dies nur tun, wenn Parameters.WMI.ProviderId auf dasselbe Geräteobjekt wie der Zeiger verweist, den der Treiber an IoWMIRegistrationControl übergeben hat. Andernfalls muss der Treiber die Anforderung an den nächstniedrigen Treiber weiterleiten.

Implementieren Sie keine Unterstützung für IRP_MN_CHANGE_SINGLE_ITEM , es sei denn, Sie sind sicher, dass eine vom System bereitgestellte Benutzermoduskomponente diese Funktion erfordert.

Vor der Verarbeitung einer Anforderung muss der Treiber ermitteln, ob Parameters.WMI.DataPath auf eine vom Treiber unterstützte GUID verweist. Wenn dies nicht der Fall ist, muss der Treiber das IRP nicht ausführen und STATUS_WMI_GUID_NOT_FOUND zurückgeben.

Wenn der Treiber den Datenblock unterstützt, muss er die Eingabe WNODE_SINGLE_ITEM Struktur überprüfen, auf die Parameters.WMI.Buffer für den instance Namen verweist, wie folgt:

Wenn WNODE_FLAG_STATIC_INSTANCE_NAMES in WnodeHeader.Flags festgelegt ist, verwendet der Treiber InstanceIndex als Index in der Liste der statischen instance Namen des Treibers für diesen Block. WMI ruft den Index aus den Registrierungsdaten ab, die vom Treiber bei der Registrierung des Blocks bereitgestellt wurden.
Wenn WNODE_FLAG_STATIC_INSTANCE_NAMES in WnodeHeader.Flags eindeutig ist, verwendet der Treiber den Offset bei OffsetInstanceName, um die instance Namenszeichenfolge in der Eingabestruktur WNODE_SINGLE_ITEM zu suchen. OffsetInstanceName ist der Offset in Bytes vom Anfang der Struktur auf eine USHORT-Größe der instance Namenszeichenfolge in Bytes (nicht Zeichen). Diese Länge schließt den NULL-Abschlussator ein, falls vorhanden, gefolgt von der instance Namenszeichenfolge in Unicode.

Der Treiber ist für die Überprüfung aller Eingabewerte verantwortlich. Insbesondere muss der Treiber Folgendes tun, wenn er die IRP-Anforderung selbst verarbeitet:

Überprüfen Sie bei statischen Namen, ob sich das InstanceIndex-Element der WNODE_SINGLE_ITEM-Struktur innerhalb des Bereichs instance Indizes befindet, die vom Treiber für den Datenblock unterstützt werden.
Stellen Sie bei dynamischen Namen sicher, dass die instance-Namenszeichenfolge einen Datenblock identifiziert, der vom Treiber unterstützt instance.
Stellen Sie sicher, dass sich das ItemId-Element der WNODE_SINGLE_ITEM-Struktur innerhalb des Bereichs der Elementbezeichner befindet, die vom Treiber für den Datenblock unterstützt werden.
Stellen Sie sicher, dass die DataBlockOffset- und SizeDataItem-Member der WNODE_SINGLE_ITEM-Struktur einen Datenblock mit gültiger Größe beschreiben und dass der Inhalt des Puffers für das Datenelement gültig ist.
Vergewissern Sie sich, dass es sich bei dem angegebenen Datenelement um eines handelt, für das der Treiber vom Aufrufer initiierte Änderungen zulässt. Anders ausgedrückt: Der Treiber sollte keine Änderungen an Datenelementen zulassen, die schreibgeschützt sein sollen.

Gehen Sie nicht davon aus, dass der Threadkontext dem der initiierenden Anwendung im Benutzermodus entspricht. Möglicherweise hat ihn ein Treiber auf höherer Ebene geändert.

Wenn der Treiber die angegebene instance nicht finden kann, muss der IRP fehlschlagen und STATUS_WMI_INSTANCE_NOT_FOUND zurückgeben. Bei einem instance mit einem dynamischen instance Namen gibt diese status an, dass der Treiber die instance nicht unterstützt. WMI kann daher weiterhin andere Datenanbieter abfragen und einen entsprechenden Fehler an den Daten consumer zurückgeben, wenn ein anderer Anbieter die instance findet, die Anforderung aber aus einem anderen Grund nicht verarbeiten kann.

Wenn der Treiber den instance findet und die Anforderung verarbeiten kann, legt er das Datenelement im instance auf den Wert im WNODE_SINGLE_ITEM fest. Wenn das Datenelement schreibgeschützt ist, lässt der Treiber das Element unverändert, schlägt den IRP fehl und gibt STATUS_WMI_READ_ONLY zurück.

Wenn der instance gültig ist, der Treiber die Anforderung aber nicht verarbeiten kann, kann er einen entsprechenden Fehler status zurückgeben.