Unterstützung von WMI-Datenblöcken und -Ereignissen in Ihrem Treiber

Artikel
02/08/2024

[Gilt nur für KMDF]

Frameworkbasierte Treiber unterstützen WMI-Datenblöcke, indem sie Ereignisrückruffunktionen bereitstellen. Treiber unterstützen WMI-Ereignisse, indem sie eine Objektmethode aufrufen, die ein Ereignis an WMI-Clients sendet.

Unterstützung von WMI-Datenblöcken mit Lese-/Schreibzugriff

Wenn die Informationen in einem WMI-Datenblock von WMI-Clients sowohl lesbar als auch schreibbar sind, muss der Treiber eine EvtWmiInstanceQueryInstance-Rückruffunktion bereitstellen, die die Leseanforderungen eines Clients verarbeitet, sowie EvtWmiInstanceSetInstance oder EvtWmiInstanceSetItem-Rückruffunktionen (oder beides), die die Schreibanforderungen eines Clients verarbeiten.

Wenn der Datenblock Methoden enthält, die der Treiber auf Anforderung des Clients ausführt, muss der Treiber auch eine EvtWmiInstanceExecuteMethod-Rückruffunktion bereitstellen.

Wenn ein WMI-Datenblock schreibgeschützt ist (d. h. WMI-Clients können Informationen in den Datenblock schreiben, aber den Datenblock nicht lesen), stellt der Treiber keine EvtWmiInstanceQueryInstance-Rückruffunktion bereit.

Unterstützung von Read-Only WMI-Datenblöcken

Wenn die Informationen in einem WMI-Datenblock nicht von einem WMI-Client geändert werden können, stellt der Treiber keine Rückruffunktionen EvtWmiInstanceSetInstance oder EvtWmiInstanceSetItem bereit. Um Anforderungen für die Informationen des Datenblocks von WMI-Clients zu unterstützen, kann der Treiber eine der folgenden Aktionen ausführen:

Stellen Sie eine EvtWmiInstanceQueryInstance-Rückruffunktion bereit, um vom Treiber bereitgestellte Daten in einen von WMI bereitgestellten Puffer zu kopieren.
Speichern Sie die Informationen des Datenblocks im Kontextbereich des WMI-instance-Objekts, und legen Sie den UseContextForQuery-Member der WDF_WMI_INSTANCE_CONFIG-Struktur des instance auf TRUE fest.

Wenn der Treiber UseContextForQuery auf TRUE festlegt, kopiert das Framework den Kontextbereich des instance Objekts in einen von WMI bereitgestellten Puffer, wenn ein WMI-Client die Informationen des instance anfordert. Es sind keine EvtWmiInstanceXxx-Rückrufe erforderlich, wenn der Treiber nur über eine einzelne WMI-instance verfügt, die schreibgeschützte Daten mit fester Länge aus dem Objektkontextbereich bereitstellt.

Wenn ein schreibgeschützter Datenblock Methoden enthält, die der Treiber auf Anforderung des Clients ausführt, kann der Treiber auch eine EvtWmiInstanceExecuteMethod-Rückruffunktion bereitstellen.

Unterstützung teurer WMI-Datenblöcke

Wenn Ihr Treiber relativ große Mengen dynamischer Daten sammelt, um einen seiner WMI-Datenblöcke zu unterstützen, sollte der Treiber die folgenden Schritte ausführen:

Deklarieren Sie den Datenblock als "teuer", indem Sie das WdfWmiProviderExpensive-Flag im Flags-Member der WDF_WMI_PROVIDER_CONFIG-Struktur des WMI-Anbieterobjekts festlegen.
Stellen Sie eine EvtWmiProviderFunctionControl-Rückruffunktion bereit, die die Datensammlung für den Datenblock aktiviert und deaktiviert, oder rufen Sie WdfWmiProviderIsEnabled auf, um zu bestimmen, ob der Treiber die Datensammlung aktivieren oder deaktivieren soll.

Wenn Ihr Treiber das WdfWmiProviderExpensive-Flag festlegt, ruft das Framework die Rückruffunktion EvtWmiProviderFunctionControl auf, wenn sich ein WMI-Client für den Zugriff auf den Datenblock registriert. Die Rückruffunktion sollte es dem Treiber ermöglichen, Daten zu sammeln. Wenn alle WMI-Clients ihre Registrierungen für den Datenblock entfernen, ruft das Framework die Rückruffunktion EvtWmiProviderFunctionControl erneut auf, damit der Treiber das Sammeln von Daten beenden kann.

Unterstützung von WMI-Ereignissen

Ein Treiber kann WMI-Ereignisse verwenden, um WMI-Clients über außergewöhnliche Bedingungen zu benachrichtigen. (WMI-Ereignisse sollten nicht als Alternative zum Protokollieren von Fehlern verwendet werden.) Wie Datenelemente werden WMI-Ereignisse in WMI-Datenblöcken in Mof-Dateien (Managed Object Format) definiert.

WMI-Clients registrieren sich für die Benachrichtigung über WMI-Ereignisse. Um ein Ereignis an registrierte WMI-Clients zu senden, ruft Ihr Treiber die WdfWmiInstanceFireEvent-Methode auf. Mit dieser Methode kann der Treiber optional ereignisspezifische Daten an die Clients senden.

Wenn der WMI-Datenblock, der das Ereignis definiert, auch WMI-Datenelemente oder Methodenelemente enthält, stellt der Treiber geeignete WMI-Rückruffunktionen bereit. Wenn ein Datenblock ein Ereignis definiert, aber keine Daten oder Methodenelemente enthält, muss Der Treiber das WdfWmiProviderEventOnly-Flag im Flags-Member der WDF_WMI_PROVIDER_CONFIG-Struktur des WMI-Anbieterobjekts festlegen.

Der Treiber sollte WdfWmiInstanceFireEvent nur aufrufen, wenn ein WMI-Client für die Ereignisbenachrichtigung registriert wurde. Der Treiber kann bestimmen, ob er WdfWmiInstanceFireEvent aufrufen soll, indem er entweder eine EvtWmiProviderFunctionControl-Rückruffunktion bereitstellt oder WdfWmiProviderIsEnabled aufruft.

Unterstützung der WMI-Ereignisablaufverfolgung

Ablaufverfolgungsereignisse werden in MOF-Dateien auf die gleiche Weise wie andere WMI-Ereignisse definiert. Wenn Ihr Treiber ein WMI-Anbieterobjekt für ein Ablaufverfolgungsereignis erstellt, muss er das WdfWmiProviderTracing-Flag im Flags-Member der WDF_WMI_PROVIDER_CONFIG-Struktur des Anbieterobjekts festlegen.

Nachdem ein Anbieter instance registriert wurde, kann der Treiber WdfWmiProviderGetTracingHandle aufrufen, um ein Ablaufverfolgungshandle abzurufen. Der Treiber kann das Ablaufverfolgungshandle als Eingabe für die WmiTraceMessage-Routine verwenden.

Weitere Informationen zur Ereignisablaufverfolgung finden Sie unter: