Funzione SHRegQueryUSValueA (shlwapi.h)

Articolo
03/02/2024

Recupera il tipo e i dati per un nome specificato associato a una sottochiave del Registro di sistema aperta in un sottoalbero specifico dell'utente (HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE).

Sintassi

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out]           DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in, optional]      DWORD  dwDefaultDataSize
);

Parametri

[in] hUSKey

Tipo: HUSKEY

Handle per una sottochiave del Registro di sistema aperta o uno dei valori predefiniti seguenti. La sottochiave deve essere stata aperta con il diritto di accesso KEY_SET_VALUE. Per altre informazioni, vedere Sicurezza delle chiavi del Registro di sistema e diritti di accesso.

Questo handle può essere ottenuto tramite la funzione SHRegOpenUSKey .

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

Tipo: LPCTSTR

Puntatore alla stringa con terminazione null contenente il nome del valore da eseguire una query.

[in, out, optional] pdwType

Tipo: LPDWORD*

Puntatore alla variabile che imposta o riceve il tipo di valore della chiave. Per altre informazioni, vedere Tipi di dati del Registro di sistema. Questo parametro può essere NULL.

[out, optional] pvData

Tipo: LPVOID*

Puntatore al buffer che riceve i dati del valore. Questo parametro può essere NULL se i dati non sono necessari.

[in, out] pcbData

Tipo: LPDWORD*

Puntatore alla variabile che specifica le dimensioni, in byte, del buffer a cui punta il parametro pvData . Quando la funzione restituisce, questa variabile contiene le dimensioni dei dati copiati in pvData.

[in] fIgnoreHKCU

Tipo: BOOL

Variabile che specifica la chiave da cercare. Se impostato su TRUE, SHRegQueryUSValue ignora HKEY_CURRENT_USER e restituisce il valore dalla chiave in HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Tipo: LPVOID*

Puntatore ai dati predefiniti.

[in, optional] dwDefaultDataSize

Tipo: DWORD

Lunghezza, in byte, dei dati predefiniti.

Valore restituito

Tipo: LSTATUS

Restituisce ERROR_SUCCESS se ha esito positivo o un codice di errore diverso da zero definito in Winerror.h in caso contrario. È possibile usare la funzione FormatMessage con il flag FORMAT_MESSAGE_FROM_SYSTEM per recuperare una descrizione generica dell'errore.

Commenti

Quando fIgnoreHKCU è impostato su TRUE, SHRegQueryUSValue restituisce il valore dalla chiave in HKEY_LOCAL_MACHINE. Se impostato su FALSE, SHRegQueryUSValue tenta prima di tutto di restituire il valore dalla chiave in HKEY_CURRENT_USER. Tuttavia, se la chiave non viene trovata in HKEY_CURRENT_USER, il valore restituisce dalla chiave in HKEY_LOCAL_MACHINE. Se non è presente alcuna chiave o se si verifica un errore e dwDefaultDataSize è diverso da zero, i dati predefiniti vengono copiati in pvData e ERROR_SUCCESS restituisce. ERROR_SUCCESS restituisce sia per i dati predefiniti che non predefiniti e non è possibile distinguere il valore copiato in pvData. Per evitare l'uso dei dati predefiniti, impostare pvDefaultData su NULL e dwDefaultDataSize su zero.

Se è necessario leggere un singolo valore, SHRegGetUSValue aprirà la chiave e restituirà il valore. Per usare SHRegQueryUSValue, è prima necessario aprire la chiave con SHRegOpenUSKey. Tuttavia, una volta aperta la chiave, è possibile usare SHRegQueryUSValue quante volte necessario. Se è necessario recuperare più di un valore dalla stessa chiave, l'uso di più chiamate a SHRegQueryUSValue è in genere più efficiente di SHRegGetUSValue, poiché la chiave viene aperta una sola volta.

Nota

L'intestazione shlwapi.h definisce SHRegQueryUSValue come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional, Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlwapi.h
Libreria	Shlwapi.lib
DLL	Shlwapi.dll (versione 4.71 o successiva)

Condividi tramite