Funzione WdfRegistryQueryValue (wdfregistry.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryQueryValue recupera i dati attualmente assegnati a un valore del Registro di sistema specificato.

Sintassi

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

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 contenente un nome di valore.

[in] ValueLength

Lunghezza, in byte, del buffer a cui punta Valore .

[out, optional] Value

Puntatore a un buffer allocato dal driver che riceve i dati del Registro di sistema. Se questo puntatore è NULL, WdfRegistryQueryValue recupera la lunghezza dei dati ma non i dati.

[out, optional] ValueLengthQueried

Puntatore a una posizione che riceve la lunghezza dei dati del Registro di sistema. Questo puntatore è facoltativo e può essere NULL.

[out, optional] ValueType

Puntatore a una posizione che riceve il tipo di dati del Registro di sistema. Per un elenco di valori del tipo di dati, vedere Il membro Type di KEY_VALUE_BASIC_INFORMATION. Questo puntatore è facoltativo e può essere NULL.

Valore restituito

WdfRegistryQueryValue 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	WdfRegistryQueryValue non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
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_BUFFER_OVERFLOW	Il buffer a cui punta il parametro Value è troppo piccolo e solo i dati parziali sono stati scritti nel buffer.
STATUS_BUFFER_OVERFLOW	Il buffer Valore è 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

L'esempio di codice seguente apre la chiave hardware di un dispositivo e recupera i dati assegnati al valore NumberOfToasters, archiviato sotto la chiave hardware del dispositivo.

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

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)