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 una stringa con terminazione Null 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 una stringa con terminazione Null 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 il recupero dei dati. È 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, il valore pdwType di input è il tipo del valore predefinito. Per i valori possibili, vedere Tipi di dati del Registro di sistema. Se il flag di 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 saranno superflui.

[in, out] pcbData

Tipo: LPDWORD

Puntatore a un DWORD che, nella voce, contiene le dimensioni del buffer di 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.
Non NULL	ERROR_SUCCESS	Numero esatto di byte scritti in pvData.
Non NULL	ERROR_MORE_DATA	Dimensioni in byte necessarie per contenere gli interi dati. 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 oppure 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

SHRegGetValue offre il controllo del tipo di dati, il controllo della modalità di avvio, l'espansione automatica dei dati REG_EXPAND_SZ e la terminazione null garantita di REG_SZ, REG_EXPAND_SZ e REG_MULTI_SZ dati.

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 la terminazione Null della stringa. Ad esempio, se pvData non è NULL, i dati restituiti in tale buffer vengono terminati con null. Se pcbData non è NULL, la dimensione del buffer a cui punta include i byte necessari per contenere il carattere null di terminazione.

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 della 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

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 leggere nuovamente 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.

Nota

L'intestazione shlwapi.h definisce SHRegGetValue 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP con SP2 [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlwapi.h
Libreria	Shlwapi.lib
DLL	Shlwapi.dll (versione 6.0 o successiva)

Vedi anche

Regqueryvalueex