WmiSystemControl-Funktion (wmilib.h)

Artikel
02/27/2024

Die WmiSystemControl-Routine ist eine Dispatchroutine für Treiber, die WMI-Bibliotheksunterstützungsroutinen zum Verarbeiten von WMI-IRPs verwenden.

Syntax

NTSTATUS WmiSystemControl(
  [in]      PWMILIB_CONTEXT         WmiLibInfo,
  [in]      PDEVICE_OBJECT          DeviceObject,
  [in, out] PIRP                    Irp,
  [out]     PSYSCTL_IRP_DISPOSITION IrpDisposition
);

Parameter

[in] WmiLibInfo

Ein Zeiger auf eine WMILIB_CONTEXT-Struktur , die Registrierungsinformationen für die Daten- und Ereignisblöcke eines Treibers enthält und Einstiegspunkte für die WMI-Bibliotheksrückrufroutinen des Treibers definiert.

[in] DeviceObject

Ein Zeiger auf die DEVICE_OBJECT des Treibers.

[in, out] Irp

Ein Zeiger auf den IRP.

[out] IrpDisposition

Ein Zeiger auf einen Enumerationswert vom Typ SYSCTL_IRP_DISPOSITION , der angibt, wie die IRP behandelt wurde. WmiSystemControl legt diesen Wert immer fest, auch wenn es einen nicht erfolgreichen NTSTATUS-Code zurückgibt.

SYSCTL_IRP_DISPOSITION ist eine Enumeration in Wmilib.h und enthält die folgenden Werte:

IrpProcessed

Das IRP wurde verarbeitet und möglicherweise abgeschlossen. Wenn die von WmiSystemControl aufgerufene DpWmi-Xxx-Routinedes Treibers das IRP nicht abgeschlossen hat, muss der Treiber WmiCompleteRequest aufrufen, um das IRP nach der Rückgabe von WmiSystemControl abzuschließen.

IrpNotCompleted

Die IRP wurde verarbeitet, aber nicht abgeschlossen, weil WMI einen Fehler erkannt und das IRP mit einem entsprechenden Fehlercode eingerichtet hat oder eine IRP_MN_REGINFO - oder IRP_MN_REGINFO_EX-Anforderung verarbeitet hat. Der Treiber muss die IRP durch Aufrufen von IoCompleteRequest abschließen.

IrpNotWmi

Das IRP ist keine WMI-Anforderung (d. h. WMI erkennt den Nebencode des IRP nicht). Wenn der Treiber IRP_MJ_SYSTEM_CONTROL Anforderungen mit diesem IRP_MN_XXX verarbeitet, sollte er die IRP verarbeiten. Andernfalls sollte der Treiber den IRP an den nächstniedreren Treiber weiterleiten. Wenn der Treiber der untersten Ebene ist, muss er die IRP abschließen.

IrpForward

Das IRP ist auf ein anderes Geräteobjekt ausgerichtet (d. h. der Geräteobjektzeiger auf Parameters.WMI.ProviderId im IRP stimmt nicht mit dem Zeiger überein, der vom Treiber in seinem Aufruf von IoWMIRegistrationControl übergeben wurde). Der Treiber muss den IRP an den nächsten niedrigeren Treiber weiterleiten. Wenn der Treiber der untersten Ebene ist, muss er die IRP abschließen.

Rückgabewert

WmiSystemControl gibt STATUS_SUCCESS oder einen der folgenden Fehlercodes zurück:

Hinweise

Wenn ein Treiber eine IRP_MJ_SYSTEM_CONTROL-Anforderung mit einem WMI-IRP-Nebencode empfängt, ruft er WmiSystemControl mit einem Zeiger auf die WMILIB_CONTEXT-Struktur des Treibers, einem Zeiger auf sein Geräteobjekt und einem Zeiger auf das IRP auf. Die WMILIB_CONTEXT-Struktur enthält Registrierungsinformationen für die Daten- und Ereignisblöcke des Treibers und definiert Einstiegspunkte für die Rückrufroutinen der WMI-Bibliothek.

WmiSystemControl bestätigt, dass der IRP eine WMI-Anforderung ist, und bestimmt, ob der in der Anforderung angegebene Block für den Treiber gültig ist. Wenn dies der Fall ist, wird das IRP verarbeitet, indem der entsprechende DpWmiXxx-Einstiegspunkt in der WMILIB_CONTEXT-Struktur des Treibers aufgerufen wird. WMI wird bei IRQL PASSIVE_LEVEL ausgeführt, wenn die DpWmiXxx-Routine des Treibers aufgerufen wird.

Ein Treiber muss bei IRQL PASSIVE_LEVEL ausgeführt werden, wenn er eine IRP_MJ_SYSTEM_CONTROL-Anforderung an den nächstniedrigen Treiber weiterleitet.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 2000 und höheren Versionen von Windows.
Zielplattform	Universell
Header	wmilib.h (wmilib.h einschließen)
Bibliothek	Wmilib.lib
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	WmiComplete(wdm)