WMI_QUERY_REGINFO_CALLBACK Rückruffunktion (wmilib.h)

Artikel
08/08/2023

Die DpWmiQueryReginfo-Routine stellt Informationen zu den Daten- und Ereignisblöcken bereit, die von einem Treiber registriert werden sollen. Diese Routine ist erforderlich.

Syntax

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Parameter

[in] DeviceObject

Ein Zeiger auf die WDM-DEVICE_OBJECT-Struktur des Treibers.

[out] RegFlags

Dieser Parameter gibt allgemeine Merkmale aller registrierten Blöcke an. Jedes in RegFlags festgelegte Flag wird auf alle Blöcke angewendet. Ein Treiber kann RegFlags für einen bestimmten Block durch Festlegen von Flags in der WMIGUIDREGINFO-Struktur des Blocks ergänzen. Beispielsweise kann ein Treiber WMIREG_FLAG_EXPENSIVE in RegFlags löschen, ihn aber in Flags festlegen, um einen bestimmten Block als teuer zu erfassen.

Der Treiber legt eines der folgenden Flags in RegFlags fest:

WMIREG_FLAG_INSTANCE_BASENAME

Fordert WMI an, statische instance Namen aus einem Basisnamen zu generieren, der vom Treiber unter InstanceName bereitgestellt wird. WMI generiert instance Namen, indem ein Zähler an den Basisnamen angefügt wird.

WMIREG_FLAG_INSTANCE_PDO

Fordert WMI an, statische instance Namen aus dem Gerät instance-ID für das PDO zu generieren. Wenn der Treiber dieses Flag festlegt, muss er auch Pdo auf die PDO festlegen, die an die AddDevice-Routine des Treibers übergeben wird. WMI generiert instance Namen vom Gerät instance Pfad der PDO. Die Verwendung des Geräte-instance-Pfads als Basis für statische instance Namen ist effizient, da solche Namen garantiert eindeutig sind. WMI stellt automatisch einen "Anzeigenamen" für die instance als Element in einem Datenblock bereit, der von Datenconsumern abgefragt werden kann.

Ein Treiber kann auch eines oder mehrere der folgenden Flags in RegFlags festlegen, diese jedoch in der Regel in Flags der WMIGUIDREGINFO-Struktur eines Blocks festlegen:

WMIREG_FLAG_EVENT_ONLY_GUID

Die Blöcke können nur als Ereignisse aktiviert oder deaktiviert werden und können nicht abgefragt oder festgelegt werden. Wenn dieses Flag eindeutig ist, können die Blöcke auch abgefragt oder festgelegt werden.

WMIREG_FLAG_EXPENSIVE

Fordert WMI auf, eine IRP_MN_ENABLE_COLLECTION Anforderung zu senden, wenn ein Datenconsumer zum ersten Mal einen Datenblock und eine IRP_MN_DISABLE_COLLECTION-Anforderung öffnet, wenn der letzte Datenconsumer den Datenblock schließt. Dies wird empfohlen, wenn sich das Sammeln solcher Daten auf die Leistung auswirkt, da ein Treiber die Daten erst sammeln muss, wenn ein Datenconsumer sie explizit anfordert, indem er den Block öffnet.

WMIREG_FLAG_REMOVE_GUID

Fordert WMI auf, die Unterstützung für die Blöcke zu entfernen. Dieses Flag ist nur als Reaktion auf eine Anforderung zum Aktualisieren von Registrierungsinformationen gültig (IRP_MN_REGINFO oder IRP_MN_REGINFO_EX , wobei Parameters.WMI.DataPath auf WMIUPDATE festgelegt ist).

[out] InstanceName

Ein Zeiger auf eine einzelne gezählte Unicode-Zeichenfolge, die als Basisname für alle Instanzen aller Blöcke dient, die vom Treiber registriert werden sollen. WMI gibt die Zeichenfolge mit ExFreePool frei. Wenn WMIREG_FLAG_INSTANCE_BASENAME eindeutig ist, wird InstanceName ignoriert.

[out] RegistryPath

Ein Zeiger auf einen Zeiger auf eine gezählte Unicode-Zeichenfolge, die den Registrierungspfad angibt, der an die DriverEntry-Routine des Treibers übergeben wird.

[out] MofResourceName

Ein Zeiger auf eine einzelne gezählte Unicode-Zeichenfolge, die den Namen der MOF-Ressource angibt, die an die Binärbilddatei des Treibers angefügt ist. In der Regel handelt es sich bei dieser Zeichenfolge um eine statische Zeichenfolge, die vom Treiber definiert wird. WMI macht eine Kopie dieser Zeichenfolge, nachdem der Treiber aus dieser Routine zurückgibt. Diese Zeichenfolge kann vom Treiber dynamisch zugeordnet werden. Im Fall einer zugeordneten Zeichenfolge ist der Treiber für das Freigeben der Zeichenfolge verantwortlich, was nach der Rückgabe von WmiSystemControl erfolgen sollte. Wenn dem Treiber keine MOF-Ressource angefügt ist, kann MofResourceName unverändert bleiben.

[out] Pdo

Ein Zeiger auf das objekt des physischen Geräts (PDO), das an die AddDevice-Routine des Treibers übergeben wird. Wenn WMIREG_FLAG_INSTANCE_PDO festgelegt ist, verwendet WMI das Gerät instance Pfad dieses PDO als Basis, aus der statische instance Namen generiert werden. Wenn WMIREG_FLAG_INSTANCE_PDO eindeutig ist, ignoriert WMI Pdo.

Rückgabewert

DpWmiQueryReginfo gibt immer STATUS_SUCCESS zurück.

Hinweise

WMI ruft die DpWmiQueryReginfo-Routine eines Treibers auf, nachdem der Treiber WmiSystemControl als Reaktion auf eine IRP_MN_REGINFO - oder IRP_MN_REGINFO_EX-Anforderung aufgerufen hat. Der Treiber muss die Adresse seiner DpWmiQueryReginfo-Routine in der WMILIB_CONTEXT-Struktur platzieren, die er an WmiSystemControl übergibt.

WMI sendet das IRP, nachdem ein Treiber IoWMIRegistrationControl mit WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER oder WMIREG_ACTION_UPDATE aufgerufen hat. WMI behandelt die Unterschiede zwischen IRP_MN_REGINFO und IRP_MN_REGINFO_EX im Namen des Treibers transparent.

WMI sendet keine IRP_MN_REGINFO - oder IRP_MN_REGINFO_EX anforderung, nachdem ein Treiber IoWMIRegistrationControl mit WMIREG_ACTION_DEREGISTER aufgerufen hat, da WMI keine weiteren Informationen vom Treiber benötigt. Ein Treiber hebt die Registrierung seiner Blöcke in der Regel als Reaktion auf eine IRP_MN_REMOVE_DEVICE-Anforderung auf.

Der Treiber stellt neue oder aktualisierte Registrierungsinformationen zu einzelnen Blöcken bereit oder gibt Blöcke an, die entfernt werden sollen, in der WMILIB_CONTEXT Struktur, die er an WmiSystemControl übergibt. Nach dem ersten Aufruf, der den Registrierungspfad des Treibers und den MOF-Ressourcennamen festlegt, kann die DpWmiQueryReginfo-Routine eines Treibers die flags ändern, die allen Treiberblöcken gemeinsam sind, eine andere Basisnamenzeichenfolge bereitstellen, die zum Generieren von instance Namen verwendet wird, oder die Grundlage für instance Namen von einer Zeichenfolge in das Gerät instance Pfad der PDO ändern.

Der Treiber darf die Anforderung nicht STATUS_PENDING zurückgeben oder blockieren. Der Treiber darf die Anforderung nicht abschließen, indem er WmiCompleteRequest aus seiner DpWmiQueryReginfo-Routine aufruft oder IoCompleteRequest aufruft , nachdem WmiSystemControl zurückgegeben wurde.

Diese Routine kann ausgelagert werden.

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