WdfRegistryQueryValue-Funktion (wdfregistry.h)

Artikel
02/29/2024

[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 für ein 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, auf den Value verweist, in Bytes.

[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 ab, aber nicht die Daten.

[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 im Typmember 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 nicht unter IRQL = PASSIVE_LEVEL aufgerufen.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde angegeben.
STATUS_ACCESS_DENIED	Der Treiber hat den Registrierungsschlüssel nicht mit KEY_QUERY_VALUE, KEY_READ oder KEY_ALL_ACCESS Geöffnet.
STATUS_BUFFER_OVERFLOW	Der Puffer, auf den der Value-Parameter verweist, ist zu klein, und es wurden nur Teildaten in den Puffer geschrieben.
STATUS_BUFFER_OVERFLOW	Der Wertpuffer 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-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

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

Beispiele

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

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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfregistry.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)