WMI_SET_DATAITEM_CALLBACK Rückruffunktion (wmilib.h)

Artikel
03/01/2024

Die DpWmiSetDataItem-Routine ändert ein einzelnes Datenelement in einem instance eines Datenblocks. Diese Routine ist optional.

Syntax

WMI_SET_DATAITEM_CALLBACK WmiSetDataitemCallback;

NTSTATUS WmiSetDataitemCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] ULONG InstanceIndex,
  [in] ULONG DataItemId,
  [in] ULONG BufferSize,
  [in] 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 der durch GuidIndex angegebene Block über mehrere Instanzen verfügt, ist InstanceIndex ein nullbasierter Wert, der die instance angibt.

[in] DataItemId

Gibt die ID des festzulegenden Datenelements an.

[in] BufferSize

Gibt die Größe des Puffers bei Buffer in Byte an.

[in] Buffer

Zeiger auf einen Puffer, der den neuen Wert für das Datenelement enthält.

Rückgabewert

DpWmiSetDataItem gibt STATUS_SUCCESS oder einen geeigneten Fehlercode wie den folgenden zurück:

Hinweise

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

Implementieren Sie DpWmiSetDataItem nur, wenn Sie sicher sind, dass eine vom System bereitgestellte Benutzermoduskomponente diese Funktion erfordert. Wenn Sie eine DpWmiSetDataItem-Routine implementieren, muss der Treiber die Adresse der Routine im SetWmiDataItem-Member der WMILIB_CONTEXT Struktur platzieren, die an WmiSystemControl übergeben wird. Wenn Sie keine DpWmiSetDataItem-Routine implementieren, muss der Treiber SetWmiDataItem auf NULL festlegen. Im letzteren Fall gibt WMI STATUS_READ_ONLY an den Aufrufer zurück.

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 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 festgelegte Anforderung vor dem Entfernen eingeht.
Stellen Sie sicher, dass sich der InstanceIndex-Wert innerhalb des Bereichs von instance Indizes befindet, die vom Treiber für den Datenblock unterstützt werden.
Stellen Sie sicher, dass der DataItemId-Wert innerhalb des Bereichs der Datenelementbezeichner liegt, die vom Treiber für den Datenblock unterstützt werden.
Stellen Sie sicher, dass Buffer und BufferSize ein Datenelement mit gültiger Größe beschreiben und dass der Inhalt des Puffers für das Datenelement gültig ist.
Stellen Sie sicher, dass es sich bei dem angegebenen Datenelement um ein Datenelement handelt, für das der Treiber vom Aufrufer initiierte Änderungen zulässt. Anders ausgedrückt: Der Treiber darf keine Änderungen an Datenelementen zulassen, die schreibgeschützt sein sollen.

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

Diese Routine kann ausgelagert werden.

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

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Kopfzeile	wmilib.h (wmilib.h einschließen)
IRQL	Wird unter PASSIVE_LEVEL aufgerufen.

Weitere Informationen

IRP_MN_CHANGE_SINGLE_ITEM

WMILIB_CONTEXT

WmiSystemControl

Freigeben über