WdfRegistryQueryUnicodeString-Funktion (wdfregistry.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRegistryQueryUnicodeString--Methode ruft die Zeichenfolgendaten ab, die derzeit einem angegebenen Registrierungszeichenfolgenwert zugewiesen sind, und kopiert die Zeichenfolge in eine angegebene UNICODE_STRING Struktur.

Syntax

NTSTATUS WdfRegistryQueryUnicodeString(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [out, optional] PUSHORT          ValueByteLength,
  [in, out]       PUNICODE_STRING  Value
);

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 Namen für den Registrierungswert enthält.

[out, optional] ValueByteLength

Ein Zeiger auf eine Position, die die Anzahl der Bytes empfängt, die in der Unicode-Zeichenfolge enthalten sind, auf die Value verweist, einschließlich des endenden NULL- Byte. Dieser Zeiger ist optional und kann NULL-

[in, out] Value

Ein Zeiger auf eine UNICODE_STRING Struktur, die die Datenzeichenfolge für den Schlüssel empfängt, der Key- angibt. Wenn dieser Parameter NULL- ist und ValueByteLength- nichtNULL-ist, gibt WdfRegistryQueryUnicodeString nur die Größe der Zeichenfolge zurück.

Rückgabewert

WdfRegistryQueryUnicodeString 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	WdfRegistryQueryUnicodeString wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_INSUFFICIENT_RESOURCES	Zum Abschließen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.
STATUS_ACCESS_DENIED	Der Treiber hat den Registrierungsschlüssel nicht mit KEY_QUERY_VALUE, KEY_READ oder KEY_ALL_ACCESS Zugriff geöffnet.
STATUS_OBJECT_TYPE_MISMATCH	Der Datentyp des Registrierungswerts, den der angegebene parameter ValueName wurde nicht REG_SZ.
STATUS_BUFFER_OVERFLOW	Der Puffer, auf den der Value Parameter verweist, war zu klein, und nur Teildaten wurden in den Puffer geschrieben.
STATUS_BUFFER_OVERFLOW	Der Puffer, auf den der Value Parameter verweist, war 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, das aus dem Serial Beispieltreiber stammt, wird die Unicode-Zeichenfolge abgerufen, die die Zeichenfolgendaten darstellt, die dem PortName-wert unter dem Hardwareschlüssel eines Geräts zugewiesen sind.

NTSTATUS
SerialReadSymName(
    IN WDFDEVICE Device,
    __out PWCHAR RegName,
    IN OUT PUSHORT LengthOfRegName // In characters
    )
{
    NTSTATUS status;
    WDFKEY hKey;
    UNICODE_STRING value;
    UNICODE_STRING valueName;
    USHORT requiredLength;

    value.Buffer = RegName;
    value.MaximumLength = *LengthOfRegName;
    value.Length = 0;

    status = WdfDeviceOpenRegistryKey(
                                      Device,
                                      PLUGPLAY_REGKEY_DEVICE,
                                      STANDARD_RIGHTS_ALL,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &hKey
                                      );

    if (NT_SUCCESS (status)) {
        RtlInitUnicodeString(
                             &valueName,
                             L"PortName"
                             );
        status = WdfRegistryQueryUnicodeString (
                                      hKey,
                                      &valueName,
                                      &requiredLength,
                                      &value
                                      );
        WdfRegistryClose(hKey);
    }
    return status;
}

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)