IRP_MN_QUERY_SINGLE_INSTANCE

Artikel
06/15/2023

Alle Treiber, die WMI unterstützen, müssen diese IRP verarbeiten. Ein Treiber kann WMI-IRPs verarbeiten, indem er WmiSystemControl aufruft oder den IRP selbst verarbeitet, wie unter Behandeln von WMI-Anforderungen beschrieben.

Wenn ein Treiber WmiSystemControl aufruft, um eine IRP_MN_QUERY_SINGLE_INSTANCE-Anforderung zu verarbeiten, ruft WMI wiederum die DpWmiQueryDataBlock-Routine dieses Treibers auf.

Hauptcode

IRP_MJ_SYSTEM_CONTROL

Sendebedingungen

WMI sendet diesen IRP, um eine einzelne instance eines bestimmten Datenblocks abzufragen.

WMI sendet eine IRP_MN_QUERY_SINGLE_INSTANCE vor dem Senden eines IRP_MN_EXECUTE_METHOD. Wenn ein Treiber IRP_MN_EXECUTE_METHOD unterstützt, muss er über einen IRP_MN_QUERY_SINGLE_INSTANCE-Handler für denselben Datenblock verfügen, dessen Methode ausgeführt wird.

WMI sendet diesen IRP unter IRQL = PASSIVE_LEVEL in einem beliebigen Threadkontext.

Eingabeparameter

Parameters.WMI.ProviderId verweist auf das Geräteobjekt des Treibers, das auf die Anforderung reagieren soll. Dieser Zeiger befindet sich am E/A-Stapelspeicherort des Treibers im IRP.

Parameters.WMI.DataPath verweist auf eine GUID, die den abzufragenden Datenblock identifiziert.

Parameters.WMI.BufferSize gibt die maximale Größe des nicht auslagerten Puffers bei Parameters.WMI.Buffer an, der auf eine WNODE_SINGLE_INSTANCE-Struktur verweist, die den instance identifiziert, der abgefragt werden soll.

Ausgabeparameter

Wenn der Treiber WMI IRPs verarbeitet, indem er WmiSystemControl aufruft, füllt WMI eine WNODE_SINGLE_INSTANCE-Struktur mit Daten aus, die von der DpWmiQueryDataBlock-Routine des Treibers bereitgestellt werden.

Andernfalls füllt der Treiber die WNODE_SINGLE_INSTANCE-Struktur unter Parameters.WMI.Buffer wie folgt aus:

Updates WnodeHeader.BufferSize mit der Größe der Ausgabe WNODE_SINGLE_INSTANCE Struktur in Bytes, einschließlich instance Daten. Dieser Wert sollte die Länge des instance Namens enthalten (so gepolstert, dass die instance Daten an einer Vierfachwortgrenze beginnen), auch wenn die abgefragte Klasse statische instance Namen registriert und der Treiberschreiber den Namen beim Warten dieser IRP nicht explizit angibt.
Legt SizeDataBlock auf die Größe der instance Daten in Bytes fest. Wenn statische instance Namen verwendet werden, sollte dieser Wert nicht die Größe des instance Namens enthalten.
Schreibt die instance Daten ab DataBlockOffset in Parameters.WMI.Buffer. Der Treiber darf den Eingabewert von DataBlockOffset nicht ändern.

Wenn der Puffer bei Parameters.WMI.Buffer zu klein ist, um alle Daten zu empfangen, füllt der Treiber die erforderliche Größe in einer WNODE_TOO_SMALL-Struktur unter Parameters.WMI.Buffer aus. Wenn der Puffer kleiner als sizeof(WNODE_TOO_SMALL) ist, schlägt der Treiber die IRP aus und gibt STATUS_BUFFER_TOO_SMALL zurück.

E/A-Statusblock

Wenn der Treiber die IRP durch Aufrufen von WmiSystemControl verarbeitet, legt WMI Irp-IoStatus.Status> und Irp-IoStatus.Information im E/A-status-Block> fest.

Andernfalls legt der Treiber Irp-IoStatus.Status> auf STATUS_SUCCESS oder auf einen entsprechenden Fehler status wie den folgenden fest:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

Bei Erfolg legt ein Treiber Irp-IoStatus.Information> auf den wert fest, der in WnodeHeader.BufferSize eingegeben wurde. Dieser Wert enthält die Länge des statischen instance Namens.

Vorgang

Ein Treiber kann WMI-IRPs verarbeiten, indem er WmiSystemControl aufruft oder den IRP selbst verarbeitet, wie unter Behandeln von WMI-Anforderungen beschrieben.

Wenn ein Treiber WMI IRPs verarbeitet, indem er WmiSystemControl aufruft, ruft WmiSystemControl die DpWmiQueryDataBlock-Routine des Treibers auf.

Wenn ein Treiber eine IRP_MN_QUERY_SINGLE_INSTANCE Anforderung selbst verarbeitet, sollte er dies nur tun, wenn Parameters.WMI.ProviderId auf dasselbe Geräteobjekt wie der Zeiger verweist, den der Treiber in seinem Aufruf von IoWMIRegistrationControl übergeben hat. Andernfalls muss der Treiber die Anforderung an den nächsten niedrigeren Treiber im Gerätestapel weiterleiten.

Vor der Verarbeitung der Anforderung muss der Treiber ermitteln, ob Parameters.WMI.DataPath auf eine vom Treiber unterstützte GUID verweist. Andernfalls muss der Treiber für die IRP fehlschlagen und STATUS_WMI_GUID_NOT_FOUND zurückgeben.

Der Treiber ist für die Überprüfung aller Eingabewerte verantwortlich. Insbesondere muss der Treiber Folgendes tun, wenn er die IRP-Anforderung selbst verarbeitet:

Überprüfen Sie bei statischen Namen, ob sich das InstanceIndex-Element der WNODE_SINGLE_INSTANCE-Struktur innerhalb des Bereichs instance Indizes befindet, die vom Treiber für den Datenblock unterstützt werden.
Stellen Sie bei dynamischen Namen sicher, dass die instance-Namenszeichenfolge einen Datenblock identifiziert, der vom Treiber unterstützt instance.
Vergewissern Sie sich, dass Parameters.WMI.BufferSize einen Puffer angibt, der groß genug ist, um alle vom Treiber zurückgegebenen Daten zu empfangen.

Wenn der Treiber den Datenblock unterstützt, überprüft er die Eingabe WNODE_SINGLE_INSTANCE unter Parameters.WMI.Buffer wie folgt auf den instance Namen:

Wenn WNODE_FLAG_STATIC_INSTANCE_NAMES in WnodeHeader.Flags festgelegt ist, verwendet der Treiber InstanceIndex als Index in der Liste der statischen instance Namen des Treibers für diesen Block. WMI ruft den Index aus den Registrierungsdaten ab, die vom Treiber bei der Registrierung des Blocks bereitgestellt wurden.
Wenn WNODE_FLAG_STATIC_INSTANCE_NAMES in WnodeHeader.Flags eindeutig ist, verwendet der Treiber den Offset unter OffsetInstanceName, um die instance Namenszeichenfolge im Eingabe-WNODE_SINGLE_INSTANCE zu suchen. OffsetInstanceName ist der Offset in Bytes vom Anfang der Struktur bis zu einem USHORT. Dabei handelt es sich um die Länge der instance Namenszeichenfolge in Bytes (nicht Zeichen), einschließlich des beendenden NULL, falls vorhanden, gefolgt von der instance Namenszeichenfolge in Unicode.

Wenn der Treiber die angegebene instance nicht finden kann, muss der IRP fehlschlagen und STATUS_WMI_INSTANCE_NOT_FOUND zurückgeben. Bei einem instance mit einem dynamischen instance Namen gibt diese status an, dass der Treiber die instance nicht unterstützt. WMI kann daher weiterhin andere Datenanbieter abfragen und einen entsprechenden Fehler an den Daten consumer zurückgeben, wenn ein anderer Anbieter die instance findet, die Anforderung aber aus einem anderen Grund nicht verarbeiten kann.

Wenn der Treiber den instance findet und die Anforderung verarbeiten kann, füllt er die WNODE_SINGLE_INSTANCE-Struktur unter Parameters.WMI.Buffer mit Daten für die instance aus.

Wenn der instance gültig ist, der Treiber die Anforderung aber nicht verarbeiten kann, kann er einen entsprechenden Fehler status zurückgeben.