Funzione SHRegGetUSValueA (shlwapi.h)

Articolo
11/20/2024

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 rispetto 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, l'input pdwType è 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 punta pvData. Quando SHRegGetUSValue restituisce, pcbData contiene le dimensioni dei dati copiati in pvData.

[in] fIgnoreHKCU

Tipo: bool

Variabile che specifica la chiave da esaminare. 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 punta pvDefaultData.

Valore restituito

Tipo: LSTATUS

Restituisce ERROR_SUCCESS in caso di 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.

Osservazioni

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 per i dati non predefiniti e non esiste alcun modo per 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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	Finestre
intestazione	shlwapi.h
libreria	Shlwapi.lib
dll	Shlwapi.dll (versione 4.71 o successiva)

Condividi tramite