WMI_QUERY_DATABLOCK_CALLBACK Rückruffunktion (wmilib.h)

Artikel
02/07/2025

Die DpWmiQueryDataBlock Routine gibt entweder eine einzelne Instanz oder alle Instanzen eines Datenblocks zurück. Diese Routine ist erforderlich.

Syntax

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

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] InstanceIndex

Wenn DpWmiQueryDataBlock- als Antwort auf eine IRP_MN_QUERY_SINGLE_INSTANCE Anforderung aufgerufen wird, gibt InstanceIndex-einen nullbasierten Index an, der die Instanz des angegebenen Datenblocks angibt, der abgefragt werden soll. Wenn DpWmiQueryDataBlock- als Reaktion auf eine IRP_MN_QUERY_ALL_DATA Anforderung aufgerufen wird, ist InstanceIndex-Null.

[in] InstanceCount

Wenn DpWmiQueryDataBlock- als Reaktion auf eine IRP_MN_QUERY_SINGLE_INSTANCE Anforderung aufgerufen wird, ist InstanceCount-1. Wenn DpWmiQueryDataBlock- als Reaktion auf eine IRP_MN_QUERY_ALL_DATA Anforderung aufgerufen wird, ist InstanceCount die Anzahl der zurückzugebenden Instanzen.

[in, out] InstanceLengthArray

Zeiger auf ein vom Aufrufer bereitgestelltes, InstanceCountArray von ULONG-Elementen. Der Treiber füllt jedes Arrayelement aus, um die Länge jeder zurückgegebenen Instanz anzugeben. Wenn BufferAvail null ist, InstanceLengthArray-NULL-ist.

[in] BufferAvail

Gibt die maximale Anzahl von Bytes an, die zum Empfangen von Daten im Puffer bei Bufferverfügbar sind. Wenn dieser Wert null ist, fordert der Aufrufer an, dass der Treiber die erforderliche Puffergröße in seinem Aufruf an WmiCompleteRequestangibt. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[out] Buffer

Zeigen Sie auf den Puffer, um Instanzdaten zu empfangen. Wenn der Puffer groß genug ist, um alle Daten zu empfangen, schreibt der Treiber die Instanzdaten in den Puffer, wobei jede Instanz an einer Grenze von 8 Byte ausgerichtet ist. Wenn der Puffer zu klein ist, um alle Daten zu empfangen, ruft der Treiber WmiCompleteRequest- auf, wobei BufferUsed auf die erforderliche Größe festgelegt ist.

Rückgabewert

DpWmiQueryDataBlock- gibt STATUS_SUCCESS oder einen Fehlerstatus zurück, z. B. folgendes:

Wenn der Treiber die Anforderung nicht sofort abschließen kann, kann er STATUS_PENDING zurückgeben.

Bemerkungen

WMI ruft die DpWmiQueryDataBlock Routine eines Treibers auf, nachdem der Treiber WmiSystemControl als Reaktion auf eine IRP_MN_QUERY_SINGLE_INSTANCE- oder IRP_MN_QUERY_ALL_DATA-Anforderung aufruft. Der Treiber muss die Adresse des DpWmiQueryDataBlock- Routine in der WMILIB_CONTEXT Struktur platzieren, die an WmiSystemControlübergeben wird.

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 Abfrage vor dem Entfernen eintreffen kann.
Stellen Sie sicher, dass die InstanceIndex-- und InstanceCount- Werte zusammen eine Reihe von Datenblockinstanzen angeben, die sich innerhalb des bereichs befinden, der vom Treiber für den Datenblock unterstützt wird. Wenn InstanceIndex- ungleich Null ist, muss InstanceCount- 1 sein. Wenn InstanceIndex- 0 ist, darf InstanceCount- nicht größer sein als die Anzahl der unterstützten Instanzen.
Stellen Sie sicher, dass der durch Buffer beschriebene Puffer und BufferAvail- groß genug ist, um alle angeforderten Instanzen des Datenblocks zu enthalten. Jede Instanz muss mit einer Grenze von 8 Byte beginnen, und es kann zwischen Datenelementen innerhalb jeder Instanz zusätzliche Abstände geben.

Nach dem Schreiben von Instanzdaten in den Puffer ruft der Treiber WmiCompleteRequest- auf, um die Anforderung abzuschließen. Wenn der durch Buffer und BufferAvail- beschriebene Puffer null ist oder zu klein ist, um alle angeforderten Daten zu empfangen, muss der Aufruf von WmiCompleteRequest- STATUS_BUFFER_TOO_SMALL für den Parameter Status und die erforderliche Puffergröße für den parameter BufferUsed angeben.

Diese Routine kann seitenfähig sein.

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