WMI_QUERY_REGINFO_CALLBACK Rückruffunktion (wmilib.h)

Die DpWmiQueryReginfo Routine enthält Informationen zu den Datenblöcken und Ereignisblöcken, 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. Alle in RegFlags- festgelegten Kennzeichnungen werden auf alle Blöcke angewendet. Ein Treiber kann RegFlags- für einen bestimmten Block durch Festlegen Flags in der WMIGUIDREGINFO Struktur des Blocks ergänzen. Ein Treiber kann z. B. WMIREG_FLAG_EXPENSIVE in RegFlags-löschen, aber in Flags festlegen, einen bestimmten Block so teuer zu registrieren, dass er gesammelt werden kann.

Der Treiber legt eine der folgenden Flags in RegFlagsfest:

WMIREG_FLAG_INSTANCE_BASENAME

Fordert WMI an, statische Instanznamen aus einem Basisnamen zu generieren, der vom Treiber im InstanceName-angegeben wird. WMI generiert Instanznamen durch Anfügen eines Zählers an den Basisnamen.

WMIREG_FLAG_INSTANCE_PDO

Fordert WMI an, statische Instanznamen aus der Geräteinstanz-ID für die PDO zu generieren. Wenn der Treiber dieses Kennzeichen festlegt, muss er auch Pdo- auf den PDO festlegen, der an die AddDevice Routine des Treibers übergeben wird. WMI generiert Instanznamen aus dem Geräteinstanzpfad des PDO. Die Verwendung des Geräteinstanzpfads als Basis für statische Instanzennamen ist effizient, da solche Namen garantiert eindeutig sind. WMI stellt automatisch einen "anzeige"-Namen für die Instanz als Element in einem Datenblock zur Auswahl, der von Datenkunden abgefragt werden kann.

Ein Treiber kann auch eine oder mehrere der folgenden Flags in RegFlags-festlegen, aber in der Regel würden sie in Flags der WMIGUIDREGINFO Struktur eines Blocks festgelegt:

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 Kennzeichen deaktiviert ist, können die Blöcke auch abgefragt oder festgelegt werden.

WMIREG_FLAG_EXPENSIVE

Fordert WMI an, eine IRP_MN_ENABLE_COLLECTION Anforderung zu senden, wenn ein Datenanwender zum ersten Mal einen Datenblock öffnet, und eine IRP_MN_DISABLE_COLLECTION Anforderung, wenn der letzte Datenverbraucher 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 Datenanwender sie explizit durch Öffnen des Blocks anfordert.

WMIREG_FLAG_REMOVE_GUID

Fordert WMI an, 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 mit Parameters.WMI.DataPath auf WMIUPDATE festgelegt).

[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 klar 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äre Bilddatei des Treibers angefügt ist. In der Regel wäre diese Zeichenfolge ein statischer Wert, der vom Treiber definiert wird. WMI erstellt eine Kopie dieser Zeichenfolge, nachdem der Treiber von dieser Routine zurückgegeben wurde. Diese Zeichenfolge kann vom Treiber dynamisch zugeordnet werden. Im Falle einer zugewiesenen Zeichenfolge ist der Treiber dafür verantwortlich, die Zeichenfolge freizulegen, die nach WmiSystemControl- zurückgegeben werden soll. Wenn der Treiber keine MOF-Ressource angefügt hat, kann er MofResourceName unverändert lassen.

[out] Pdo

Ein Zeiger auf das physische Geräteobjekt (PDO), das an die AddDevice-Routine des Treibers übergeben wird. Wenn WMIREG_FLAG_INSTANCE_PDO festgelegt ist, verwendet WMI den Geräteinstanzpfad dieses PDO als Basis, aus der statische Instanznamen generiert werden. Wenn WMIREG_FLAG_INSTANCE_PDO klar ist, ignoriert WMI Pdo-.

Rückgabewert

DpWmiQueryReginfo gibt immer STATUS_SUCCESS zurück.

Bemerkungen

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 an WmiSystemControlübergeben wird.

WMI sendet das IRP nach einem Treiberaufruf IoWMIRegistrationControl- mit WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER oder WMIREG_ACTION_UPDATE. 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 deregistert die Blöcke in der Regel als Reaktion auf eine IRP_MN_REMOVE_DEVICE-Anforderung.

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 an WmiSystemControl-übergeben wird. Nach dem anfänglichen Aufruf, der den Registrierungspfad des Treibers und den MOF-Ressourcennamen festlegt, kann die DpWmiQueryReginfo- Routine Flags ändern, die allen Blöcken eines Treibers gemeinsam sind, eine andere Basisnamenzeichenfolge bereitstellen, die zum Generieren von Instanznamen verwendet wird, oder die Basis für Instanzennamen von einer Zeichenfolge in den Geräteinstanzpfad der PDO ändern.

Der Treiber darf keine STATUS_PENDING zurückgeben oder die Anforderung blockieren. Der Treiber darf die Anforderung nicht abschließen, indem WmiCompleteRequest- aus der DpWmiQueryReginfo-Routine oder durch Aufrufen IoCompleteRequest- nach Rückgabe von WmiSystem Control aufgerufen wird.

Diese Routine kann seitenfähig sein.

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

Anforderungen

Siehe auch

IRP_MN_REGINFO_EX

IoWMIRegistrationControl-

WMIGUIDREGINFO

WMILIB_CONTEXT

WmiSystemControl-