WMI_FUNCTION_CONTROL_CALLBACK Rückruffunktion (wmilib.h)

Artikel
02/07/2025

Die DpWmiFunctionControl Routine aktiviert oder deaktiviert die Benachrichtigung über Ereignisse und aktiviert oder deaktiviert die Datensammlung für Datenblöcke, die der Treiber als teuer registriert hat. Diese Routine ist optional.

Syntax

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Parameter

[in] DeviceObject

Zeiger auf die WDM-DEVICE_OBJECT Struktur des Treibers.

[in] Irp

Zeiger auf das IRP.

[in] GuidIndex

Gibt den Datenblock an, indem ein nullbasierter Index in der Liste der GUIDs bereitgestellt wird, die der Treiber in der WMILIB_CONTEXT Struktur an WmiSystemControlübergeben hat.

[in] Function

Gibt an, was aktiviert oder deaktiviert werden soll. WmiEventControl- gibt ein Ereignis an, und WmiDataBlockControl- gibt die Datensammlung für einen Block an, der als teuer registriert wurde (d. r. einen Block, für den der Treiber in Flags der WMIGUIDREGINFO- Struktur WMIREG_FLAG_EXPENSIVE festgelegt wurde, die zum Registrieren des Blocks verwendet wurde).

[in] Enable

Gibt TRUE- an, um das Ereignis oder die Datensammlung zu aktivieren, oder FALSE-, um es zu deaktivieren.

Rückgabewert

DpWmiFunctionControl gibt STATUS_SUCCESS oder einen geeigneten Fehlerstatus zurück, z. B.:

Bemerkungen

WMI ruft die DpWmiFunctionControl Routine eines Treibers auf, nachdem der Treiber WmiSystemControl als Reaktion auf eine der folgenden Anforderungen aufruft:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Wenn ein Treiber eine DpWmiFunctionControl Routine implementiert, muss der Treiber die Adresse der Routine im WmiFunctionControl Member der WMILIB_CONTEXT Struktur platzieren, die an WmiSystemControlübergeben wird. Wenn ein Treiber keine DpWmiFunctionControl- Routine implementiert, muss er WmiFunctionControl- auf NULL-festlegen. Im letzteren Fall gibt WMI STATUS_SUCCESS an den Aufrufer zurück.

Der Treiber ist für die Überprüfung aller Eingabeargumente verantwortlich. Insbesondere muss der Treiber Folgendes ausführen:

Stellen Sie sicher, dass der GuidIndex- Wert zwischen Null und GuidCount-1 liegt, basierend auf dem GuidCount Member der WMILIB_CONTEXT Struktur.
Stellen Sie sicher, dass der Treiber den angegebenen Datenblock zum Entfernen nicht gekennzeichnet hat. Wenn der Treiber kürzlich das WMIREG_FLAG_REMOVE_GUID Flag in einer WMIGUIDREGINFO- Struktur angegeben hat, die in einer WMILIB_CONTEXT-Struktur enthalten ist, ist es möglich, dass eine zusätzliche Anforderung eintreffen kann, bevor die Entfernung erfolgt.

Es ist nicht erforderlich, dass der Treiber überprüft, ob Ereignisse oder Datensammlungen bereits für einen Block aktiviert sind, da WMI eine einzelne Aktivierungsanforderung sendet, wenn der erste Datenverbraucher den Block aktiviert und eine einzelne Deaktivierungsanforderung sendet, wenn der letzte Datenanwender den Block deaktiviert. WMI ruft DpWmiFunctionControl- nicht auf, um einen Block zu aktivieren, ohne einen dazwischen liegenden Aufruf zu deaktivieren.

Nach dem Aktivieren oder Deaktivieren des Ereignisses oder der Datensammlung für den Block ruft der Treiber WmiCompleteRequest- auf, um die Anforderung abzuschließen.

Diese Routine kann seitenfähig sein.

Weitere Informationen zum Implementieren dieser Routine finden Sie unter Aufrufen von WmiSystemControl zum Behandeln von WMI IRPs.