WMI_EXECUTE_METHOD_CALLBACK Rückruffunktion (wmilib.h)

Artikel
03/01/2024

Die DpWmiExecuteMethod-Routine führt eine Methode aus, die einem Datenblock zugeordnet ist. Diese Routine ist optional.

Syntax

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Parameter

[in] DeviceObject

Zeiger auf die WDM-DEVICE_OBJECT-Struktur des Treibers.

[in] Irp

Zeiger auf den IRP.

[in] GuidIndex

Gibt den Datenblock an, indem er einen nullbasierten Index in die Liste der GUIDs eingibt, die der Treiber in der WMILIB_CONTEXT Struktur bereitgestellt hat, die er an WmiSystemControl übergeben hat.

[in] InstanceIndex

Wenn der durch GuidIndex angegebene Block über mehrere Instanzen verfügt, gibt InstanceIndex einen nullbasierten Indexwert an, der den instance identifiziert.

[in] MethodId

Gibt die ID der auszuführenden Methode an. Der Treiber definiert die Methoden-ID als Element in einem Datenblock.

[in] InBufferSize

Gibt die Größe der Eingabedaten in Bytes an. Wenn keine Eingabedaten vorhanden sind, ist InBufferSize 0.

[in] OutBufferSize

Gibt die Anzahl von Bytes an, die im Puffer für Ausgabedaten verfügbar sind.

[in, out] Buffer

Zeiger auf einen Puffer, der (falls vorhanden) Eingabedaten enthält und Ausgabedaten empfängt, falls vorhanden, für die -Methode. Wenn der Puffer zu klein ist, um alle Ausgabedaten zu empfangen, gibt der Treiber STATUS_BUFFER_TOO_SMALL zurück und ruft WmiCompleteRequest mit der erforderlichen Größe auf.

Rückgabewert

DpWmiExecuteMethod gibt STATUS_SUCCESS oder einen entsprechenden Fehlercode wie den folgenden zurück:

Hinweise

WMI ruft die DpWmiExecuteMethod-Routine eines Treibers auf, nachdem der Treiber WmiSystemControl als Reaktion auf eine IRP_MN_EXECUTE_METHOD-Anforderung aufgerufen hat.

Wenn ein Treiber eine DpWmiExecuteMethod-Routine implementiert, muss der Treiber die Adresse der Routine im ExecuteWmiMethod-Member der WMILIB_CONTEXT Struktur platzieren, die er an WmiSystemControl übergibt. Wenn ein Treiber keine DpWmiExecuteMethod-Routine implementiert, muss ExecuteWmiMethod auf NULL festgelegt werden. Im letzteren Fall gibt WMI als Antwort auf eine IRP_MN_EXECUTE_METHOD Anforderung STATUS_INVALID_DEVICE_REQUEST an den Aufrufer zurück.

Der Treiber ist für die Validierung aller Eingabeargumente verantwortlich. Insbesondere muss der Treiber Folgendes tun:

Überprüfen Sie, ob der GuidIndex-Wert zwischen null und GuidCount-1 liegt, basierend auf dem GuidCount-Member der WMILIB_CONTEXT-Struktur .
Vergewissern Sie sich, dass der Treiber den angegebenen Datenblock nicht für die Entfernung 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 zusätzliche Anforderung eingeht, bevor die Entfernung erfolgt.
Vergewissern Sie sich, dass sich der InstanceIndex-Wert innerhalb des Bereichs instance Indizes befindet, die vom Treiber für den Datenblock unterstützt werden.
Vergewissern Sie sich, dass der von MethodId angegebene Methodenbezeichner ein gültiger Bezeichner für den angegebenen Datenblock ist und der Aufrufer die Methode ausführen darf.
Vergewissern Sie sich, dass Puffer und InBufferSize einen Puffer beschreiben, der groß genug ist, um die Eingabeparameter der angegebenen Methode zu enthalten, und überprüfen Sie, ob die Eingabeparameter gültig sind.
Stellen Sie sicher, dass Buffer und OutBufferSize einen Puffer beschreiben, der groß genug ist, um die Ausgabedaten der angegebenen Methode zu empfangen, einschließlich Auffüllung bei Bedarf.

Gehen Sie nicht davon aus, dass der Threadkontext dem der initiierenden Anwendung im Benutzermodus entspricht. Möglicherweise hat ihn ein Treiber auf höherer Ebene geändert.

Wenn die angegebene Methode einen Vorgang ausführt, der Datenverlust verursacht, z. B. das Abrufen und Zurücksetzen des Inhalts einer Reihe von Indikatoren, sollte der Treiber die Ausgabepuffergröße überprüfen, bevor er den Vorgang ausführt. Auf diese Weise kann der Treiber STATUS_BUFFER_TOO_SMALL zurückgeben und dem Aufrufer erlauben, die Anforderung mit einem größeren Puffer erneut zu übermitteln, ohne die Indikatoren vorzeitig zurückzusetzen.

Nach dem Ausführen der Methode und dem Schreiben von Ausgabedaten in den Puffer ruft der Treiber WmiCompleteRequest auf, um die Anforderung abzuschließen.

Diese Routine kann ausgelagert werden.

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