Funzione SHRegGetUSValueA (shlwapi.h)

Articolo
03/15/2023

Recupera un valore da una sottochiave del Registro di sistema in un sottoalbero specifico dell'utente (HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE).

Sintassi

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

Parametri

[in] pszSubKey

Tipo: LPCTSTR

Puntatore a una stringa con terminazione null con il nome della sottochiave relativa a HKEY_LOCAL_MACHINE e HKEY_CURRENT_USER. Ad esempio: "Software\MyCompany\MyProduct".

[in, optional] pszValue

Tipo: LPCTSTR

Puntatore a una stringa con terminazione null con il nome del valore. Questo valore può essere NULL.

[in, out, optional] pdwType

Tipo: DWORD*

Puntatore a un DWORD che riceve il tipo di dati archiviati nel valore recuperato. Quando si usano valori predefiniti, il valore pdwType di input è il tipo del valore predefinito. Per i valori possibili, vedere Tipi di dati del Registro di sistema. Se le informazioni sul tipo non sono necessarie, questo parametro può essere NULL.

[out, optional] pvData

Tipo: void*

Puntatore a un buffer che riceve i dati del valore.

[in, out, optional] pcbData

Tipo: DWORD*

Puntatore a una variabile che specifica le dimensioni, in byte, del buffer a cui fa riferimento pvData. Quando SHRegGetUSValue restituisce, pcbData contiene le dimensioni dei dati copiati in pvData.

[in] fIgnoreHKCU

Tipo: BOOL

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

[in, optional] pvDefaultData

Tipo: void*

Puntatore a un buffer che riceve i dati predefiniti del valore.

[in] dwDefaultDataSize

Tipo: DWORD

Lunghezza, in byte, del buffer a cui fa riferimento pvDefaultData.

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, SHRegGetUSValue restituisce il valore dalla chiave in HKEY_LOCAL_MACHINE. Se impostato su FALSE, SHRegGetUSValue 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 viene restituito dalla chiave in HKEY_LOCAL_MACHINE. Se non è presente alcuna chiave o se si è verificato 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.

Questa funzione apre la chiave ogni volta che viene usata. Se il codice prevede di ottenere una serie di valori dalla stessa chiave, è più efficiente aprire la chiave una volta con SHRegOpenUSKey e quindi usare SHRegQueryUSValue per recuperare i dati.

Nota

L'intestazione shlwapi.h definisce SHRegGetUSValue 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