WMI_QUERY_DATABLOCK_CALLBACK Rückruffunktion (wmilib.h)

Artikel
02/27/2024

Die DpWmiQueryDataBlock-Routine gibt entweder einen einzelnen instance 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 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] InstanceIndex

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

[in] InstanceCount

Wenn DpWmiQueryDataBlock als Antwort auf eine IRP_MN_QUERY_SINGLE_INSTANCE-Anforderung aufgerufen wird, ist InstanceCount 1. Wenn DpWmiQueryDataBlock als Antwort 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 Array mit ULONG-Elementen im InstanceCount-Format. Der Treiber füllt jedes Arrayelement aus, um die Länge der zurückgegebenen instance anzugeben. Wenn BufferAvail null ist, ist InstanceLengthArrayNULL.

[in] BufferAvail

Gibt die maximale Anzahl von Bytes an, die zum Empfangen von Daten im Puffer unter Buffer verfügbar sind. Wenn dieser Wert 0 ist, fordert der Aufrufer an, dass der Treiber die erforderliche Puffergröße in seinem Aufruf von WmiCompleteRequest angibt. Weitere Informationen finden Sie im Abschnitt Hinweise.

[out] Buffer

Zeiger auf den Puffer, der instance Daten empfangen soll. Wenn der Puffer groß genug ist, um alle Daten zu empfangen, schreibt der Treiber die instance Daten in den Puffer, wobei jedes instance an einer 8-Byte-Grenze 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 Fehler status wie den folgenden zurück:

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

Hinweise

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 aufgerufen hat. Der Treiber muss die Adresse seiner DpWmiQueryDataBlock-Routine in der WMILIB_CONTEXT-Struktur platzieren, die er an WmiSystemControl übergibt.

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 vor kurzem 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 eingeht.
Stellen Sie sicher, dass die Werte InstanceIndex und InstanceCount zusammen eine Anzahl von Datenblockinstanzen angeben, die innerhalb des Bereichs liegen, der vom Treiber für den Datenblock unterstützt wird. Wenn InstanceIndex ungleich null ist, muss InstanceCount 1 sein. Wenn InstanceIndex den Wert 0 aufweist, darf InstanceCount nicht größer als die Anzahl der unterstützten Instanzen sein.
Stellen Sie sicher, dass der unter Buffer und BufferAvail beschriebene Puffer groß genug ist, um alle angeforderten Instanzen des Datenblocks aufzunehmen. Jede instance muss mit einer 8-Byte-Grenze beginnen, und zwischen den Datenelementen innerhalb der einzelnen instance kann eine zusätzliche Auffüllung vorhanden sein.

Nachdem instance Daten in den Puffer geschrieben wurden, ruft der Treiber WmiCompleteRequest auf, um die Anforderung abzuschließen. Wenn der unter 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 BufferUsed-Parameter angeben.

Diese Routine kann ausgelagert werden.

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