WMI_FUNCTION_CONTROL_CALLBACK Rückruffunktion (wmilib.h)

Artikel
03/01/2024

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 die IRP.

[in] GuidIndex

Gibt den Datenblock an, indem ein nullbasierter Index in der Liste der GUIDs angegeben wird, die der Treiber in der WMILIB_CONTEXT Struktur bereitgestellt hat, die er 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 zu sammeln registriert wurde (d. h. einen Block, für den der Treiber WMIREG_FLAG_EXPENSIVE in Flags der WMIGUIDREGINFO-Struktur , die zum Registrieren des Blocks verwendet wird).

[in] Enable

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

Rückgabewert

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

Hinweise

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

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-Element der WMILIB_CONTEXT Struktur platzieren, die er an WmiSystemControl übergibt. 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 Validierung aller Eingabeargumente verantwortlich. Insbesondere muss der Treiber die folgenden Schritte ausführen:

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

Es ist nicht erforderlich, dass der Treiber überprüft, ob Ereignisse oder Die Datensammlung bereits für einen Block aktiviert sind, da WMI eine einzelne Aktivierungsanforderung sendet, wenn der erste Datenconsumer den Block aktiviert, und eine einzelne Disable-Anforderung sendet, wenn der letzte Datenconsumer den Block deaktiviert. WMI ruft DpWmiFunctionControl nicht auf, um einen Block zu aktivieren, ohne dass er durch einen dazwischen liegenden Aufruf deaktiviert wird.

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

Diese Routine kann ausgelagert werden.

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