Funzione SHRegQueryUSValueA (shlwapi.h)

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 al nullstringa con terminazione contenente il nome del valore su cui 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 termina, questa variabile contiene le dimensioni dei dati copiati in pvData.

[in] fIgnoreHKCU

Tipo: bool

Variabile che specifica la chiave da esaminare. 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 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, SHRegQueryUSValue restituisce il valore della 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 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.

Se è sufficiente 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ù valori dalla stessa chiave, l'uso di più chiamate a SHRegQueryUSValue è in genere più efficiente di SHRegGetUSValue, perché la chiave viene aperta una sola volta.

Fabbisogno