WdfRegistryQueryUnicodeString-Funktion (wdfregistry.h)

Artikel
02/27/2024

[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 für ein 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 einen Speicherort, der die Anzahl der Bytes empfängt, die in der Unicode-Zeichenfolge enthalten sind, auf die Value verweist, einschließlich des beendenden NULL-Bytes . Dieser Zeiger ist optional und kann NULL sein.

[in, out] Value

Ein Zeiger auf eine UNICODE_STRING-Struktur, die die Datenzeichenfolge für den schlüsselgibt, den Key angibt. Wenn dieser Parameter NULL ist und ValueByteLength nicht NULL 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	Ein ungültiger Parameter wurde angegeben.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen.
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 ValueName-Parameter angegeben hat, wurde nicht REG_SZ.
STATUS_BUFFER_OVERFLOW	Der Puffer, auf den der Value-Parameter verweist, war zu klein, und nur teilweise Daten 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-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, 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	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)