Funzione SHRegGetValueA (shlwapi.h)

[SHRegGetValue può essere modificato o non disponibile nelle versioni successive del sistema operativo o del prodotto. Usare RegGetValue al suo posto.]

Recupera un valore del Registro di sistema.

Sintassi

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Parametri

[in] hkey

Tipo: HKEY

Handle per la chiave attualmente aperta o uno dei valori predefiniti seguenti.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Tipo: LPCTSTR

Puntatore a un nullstringa con terminazione che specifica il percorso relativo da hkey alla sottochiave da cui recuperare il valore. Questo parametro può essere NULL o una stringa vuota, nel qual caso i dati vengono recuperati dal percorso hkey.

[in] pszValue

Tipo: LPCTSTR

Puntatore a un nullstringa con terminazione contenente il nome del valore. Questo parametro può essere null o una stringa vuota, nel qual caso i dati vengono recuperati dal valore predefinito.

[in] srrfFlags

Tipo: SRRF

Uno o più flag SRRF che limitano i dati da recuperare. È necessario specificare almeno un valore di restrizione del tipo (SRRF_RT).

[in, out] pdwType

Tipo: LPDWORD

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 il flag SRRF_NOEXPAND non è impostato, i tipi di REG_EXPAND_SZ vengono espansi automaticamente e restituiti come REG_SZ. Se le informazioni sul tipo non sono necessarie, questo parametro può essere NULL.

[out] pvData

Tipo: LPVOID

Puntatore a un buffer che riceve i dati del valore. Questo parametro può essere null se i dati non sono necessari. Ad esempio, se si esegue il test solo per l'esistenza di un valore, i dati di valore specifici sarebbero superflui.

[in, out] pcbData

Tipo: LPDWORD

Puntatore a un DWORD che, in ingresso, contiene le dimensioni del buffer dei dati di destinazione pvData, in byte. Questo valore può essere NULL solo se pvData è null. All'uscita, pcbData punta a uno di questi valori.

pvData	Valore restituito	pcbData
NULL	ERROR_SUCCESS	Dimensioni in byte sufficienti per contenere i dati del Registro di sistema. Si noti che non è garantito che sia la dimensione precisa, ma solo una dimensione sufficiente.
NULL non	ERROR_SUCCESS	Numero esatto di byte scritti in pvData.
NULL non	ERROR_MORE_DATA	Dimensioni in byte necessarie per contenere l'intero dato. Si noti che non è garantito che sia la dimensione precisa, ma solo una dimensione sufficiente.

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

SHRegGetValue fornisce il controllo dei tipi di dati, il controllo della modalità di avvio, l'espansione automatica dei dati di REG_EXPAND_SZ e null-terminazione di dati REG_SZ, REG_EXPAND_SZ e REG_MULTI_SZ.

La chiave identificata da hkey deve essere stata aperta con KEY_QUERY_VALUE accesso alla sicurezza. Se pszSubKey non è NULL o una stringa vuota, tale chiave deve essere aperta anche con KEY_QUERY_VALUE accesso di sicurezza nel contesto chiamante corrente.

Se il tipo di dati è REG_SZ, REG_EXPAND_SZ o REG_MULTI_SZ, tutti i dati restituiti includono o prendono in considerazione l'della stringa null-terminazione. Ad esempio, se pvData non è null, i dati restituiti nel buffer vengono null-terminate. Se pcbData non è null, le dimensioni del buffer a cui punta includono i byte necessari per contenere il carattere di terminazione null.

A meno che il flag di SRRF_NOEXPAND non sia impostato, i dati stringa di tipo REG_EXPAND_SZ vengono espansi automaticamente prima di essere restituiti. Il tipo di stringa espansa viene segnalato in pdwType come REG_SZ, il parametro pcbData punta al numero di byte scritti per la stringa espansa e il buffer a cui punta pvData contiene la versione espansa della stringa.

Note sulle prestazioni di

Se pszSubKey non è NULL o una stringa vuota, tale chiave viene aperta e chiusa da questa funzione ogni volta che si accede. Se l'applicazione deve recuperare una serie di valori dalla stessa sottochiave, si noteranno prestazioni migliori aprendo la chiave usando RegOpenKeyEx prima di chiamare SHRegGetValue. Usare la chiave restituita nel parametro phkResult di RegOpenKeyEx come parametro hkey in questa funzione, con pszSubKey impostato su NULL.

Il potenziale per una chiamata aggiuntiva al Registro di sistema per leggere o rileggere i dati esiste quando il tipo di dati è REG_EXPAND_SZ e il flag SRRF_NOEXPAND non è stato impostato. Le condizioni seguenti generano tale chiamata aggiuntiva.

• pvData è NULL, pcbData non è NULL. Anche se i dati non vengono recuperati, il Registro di sistema deve essere letto per ottenere la stringa e tale stringa espansa per determinare le dimensioni necessarie del buffer di dati.
• pvData non è NULL, ma è troppo piccolo per contenere i dati. I dati vengono rilette per ottenere la stringa completa, la stringa viene espansa e viene determinata la dimensione totale richiesta.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP con SP2 [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	shlwapi.h
libreria	Shlwapi.lib
dll	Shlwapi.dll (versione 6.0 o successiva)

Vedere anche

RegQueryValueEx