WdfRegistryQueryValue-Funktion (wdfregistry.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRegistryQueryValue--Methode ruft die Daten ab, die derzeit einem angegebenen Registrierungswert zugewiesen sind.

Syntax

NTSTATUS WdfRegistryQueryValue(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [in]            ULONG            ValueLength,
  [out, optional] PVOID            Value,
  [out, optional] PULONG           ValueLengthQueried,
  [out, optional] PULONG           ValueType
);

Parameter

[in] Key

Ein Handle zu einem Registrierungsschlüsselobjekt, das einen geöffneten Registrierungsschlüssel darstellt.

[in] ValueName

Ein Zeiger auf eine UNICODE_STRING Struktur, die einen Wertnamen enthält.

[in] ValueLength

Die Länge des Puffers in Bytes, auf den Wert verweist.

[out, optional] Value

Ein Zeiger auf einen vom Treiber zugewiesenen Puffer, der die Daten des Registrierungswerts empfängt. Wenn dieser Zeiger NULL-ist, ruft WdfRegistryQueryValue die Datenlänge, aber nicht die Daten ab.

[out, optional] ValueLengthQueried

Ein Zeiger auf einen Speicherort, der die Datenlänge des Registrierungswerts empfängt. Dieser Zeiger ist optional und kann NULL-sein.

[out, optional] ValueType

Ein Zeiger auf einen Speicherort, der den Datentyp des Registrierungswerts empfängt. Eine Liste der Datentypwerte finden Sie unter Type Member von KEY_VALUE_BASIC_INFORMATION. Dieser Zeiger ist optional und kann NULL-sein.

Rückgabewert

WdfRegistryQueryValue gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryValue wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_ACCESS_DENIED	Der Treiber hat den Registrierungsschlüssel nicht mit KEY_QUERY_VALUE, KEY_READ oder KEY_ALL_ACCESS Zugriff geöffnet.
STATUS_BUFFER_OVERFLOW	Der Puffer, auf den der Value Parameter verweist, ist zu klein, und nur Teildaten wurden in den Puffer geschrieben.
STATUS_BUFFER_OVERFLOW	Der Wert Puffer ist zu klein, und es wurden keine Daten in den Puffer geschrieben.
STATUS_OBJECT_NAME_NOT_FOUND	Der Registrierungswert war nicht verfügbar.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Weitere Informationen zu Registrierungsschlüsselobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Drivers.

Beispiele

Im folgenden Codebeispiel wird der Hardwareschlüssel eines Geräts geöffnet und die Daten abgerufen, die dem NumberOfToasters Wert zugeordnet sind, der unter dem Hardwareschlüssel des Geräts gespeichert wird.

WCHAR  comPort[FM_COM_PORT_STRING_LENGTH];
ULONG  length;
NTSTATUS  status;
ULONG  length, valueType, value;
DECLARE_CONST_UNICODE_STRING(valueName, L"NumberOfToasters");
WDFKEY  hKey;

status = WdfDeviceOpenRegistryKey(
                                  Device,
                                  PLUGPLAY_REGKEY_DEVICE,
                                  KEY_QUERY_VALUE,
                                  NULL, 
                                  &hKey
                                  );
if (!NT_SUCCESS (status)) {
    goto Error;
}
status = WdfRegistryQueryValue(
                               hKey,
                               &valueName,
                               sizeof(ULONG),
                               &value,
                               &length,
                               &valueType
                               );

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfregistry.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)