Funzione WdfRegistryQueryUnicodeString (wdfregistry.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryQueryUnicodeString recupera i dati stringa attualmente assegnati a un valore stringa del Registro di sistema specificato e copia la stringa in una struttura UNICODE_STRING specificata.

Sintassi

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

Parametri

[in] Key

Handle per un oggetto chiave del Registro di sistema che rappresenta una chiave del Registro di sistema aperta.

[in] ValueName

Puntatore a una struttura UNICODE_STRING che contiene un nome per il valore del Registro di sistema.

[out, optional] ValueByteLength

Puntatore a una posizione che riceve il numero di byte contenuti nella stringa Unicode a cui punta Valore , incluso il byte NULL terminante. Questo puntatore è facoltativo e può essere NULL

[in, out] Value

Puntatore a una struttura UNICODE_STRING che riceve la stringa di dati per la chiave specificata da Key . Se questo parametro è NULL e ValueByteLength non è NULL, WdfRegistryQueryUnicodeString restituisce solo le dimensioni della stringa.

Valore restituito

WdfRegistryQueryUnicodeString restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryUnicodeString non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente per completare l'operazione.
STATUS_ACCESS_DENIED	Il driver non ha aperto la chiave del Registro di sistema con KEY_QUERY_VALUE, KEY_READ o accesso KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Tipo di dati del valore del Registro di sistema specificato dal parametro ValueName non REG_SZ.
STATUS_BUFFER_OVERFLOW	Buffer che il parametro Value punta a era troppo piccolo e solo i dati parziali sono stati scritti nel buffer.
STATUS_BUFFER_OVERFLOW	Buffer a cui punta il parametro Value troppo piccolo e non sono stati scritti dati nel buffer.
STATUS_OBJECT_NAME_NOT_FOUND	Il valore del Registro di sistema non è stato disponibile.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Per altre informazioni sugli oggetti chiave del Registro di sistema, vedere Uso del Registro di sistema in Framework-Based Driver.

Esempio

Nell'esempio di codice seguente, proveniente dal driver di esempio seriale , viene recuperata la stringa Unicode che rappresenta i dati stringa assegnati al valore PortName sotto la chiave hardware di un dispositivo.

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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfregistry.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)