Funzione OREnumValue
Enumera i valori per la chiave del Registro di sistema aperta specificata in un hive del Registro di sistema offline. La funzione recupera informazioni per un valore sotto la chiave specificata ogni volta che viene chiamata la funzione.
Sintassi
DWORD OREnumValue(
_In_ ORHKEY Handle,
_In_ DWORD dwIndex,
_Out_ PWSTR lpValueName,
_Inout_ PDWORD lpcValueName,
_Out_opt_ PDWORD lpType,
_Out_opt_ PBYTE lpData,
_Inout_opt_ PDWORD lpcbData
);
Parametri
-
Handle [in]
-
Handle per una chiave del Registro di sistema aperta in un hive del Registro di sistema offline.
-
dwIndex [in]
-
Indice del valore da recuperare. Questo parametro deve essere zero per la prima chiamata alla funzione e quindi essere incrementato per le chiamate successive.
Poiché i valori non sono ordinati, qualsiasi nuovo valore avrà un indice arbitrario. Ciò significa che la funzione può restituire valori in qualsiasi ordine.
-
lpValueName [out]
-
Puntatore a un buffer che riceve il nome del valore come stringa con terminazione Null. Questo buffer deve essere abbastanza grande per includere il carattere Null terminante.
Per altre informazioni, vedere Limiti delle dimensioni degli elementi del Registro di sistema.
-
lpcValueName [in, out]
-
Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro lpValueName , in caratteri. Quando la funzione restituisce, la variabile riceve il numero di caratteri archiviati nel buffer, non incluso il carattere Null di terminazione.
-
lpType [out, facoltativo]
-
Puntatore a una variabile che riceve un codice che indica il tipo di dati archiviati nel valore specificato. Per un elenco dei codici di tipo possibili, vedere Tipi di valore del Registro di sistema. Il parametro lpType può essere NULL se il codice di tipo non è obbligatorio.
-
lpData [out, facoltativo]
-
Puntatore a un buffer che riceve i dati per la voce del valore. Questo parametro può essere NULL se i dati non sono necessari.
Se lpData è NULL e lpcbData non è NULL, la funzione archivia le dimensioni dei dati, in byte, nella variabile a cui punta lpcbData. Ciò consente a un'applicazione di determinare il modo migliore per allocare un buffer per i dati.
-
lpcbData [in, out, facoltativo]
-
Puntatore a una variabile che specifica le dimensioni del buffer a cui punta il parametro lpData , in byte. Quando la funzione restituisce, la variabile riceve il numero di byte archiviati nel buffer.
Questo parametro può essere NULL solo se lpData è NULL.
Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, queste dimensioni includono qualsiasi carattere o caratteri null terminanti. Per altre informazioni, vedere la sezione Osservazioni.
Se il buffer specificato da lpData non è sufficiente per contenere i dati, la funzione restituisce ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie nella variabile a cui punta lpcbData. In questo caso, il contenuto di lpData non è definito.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è un codice di errore diverso da zero definito in Winerror.h. È possibile usare la funzione FormatMessage con il flag FORMAT_MESSAGE_FROM_SYSTEM per ottenere una descrizione generica dell'errore.
Se il buffer lpData è troppo piccolo per ricevere il valore, la funzione restituisce ERROR_MORE_DATA.
Commenti
Per enumerare i valori, un'applicazione deve inizialmente chiamare la funzione OREnumValue con il parametro dwIndex impostato su zero. L'applicazione deve quindi aumentare dwIndex e chiamare la funzione OREnumValue fino a quando non sono presenti più valori (fino a quando la funzione restituisce ERROR_NO_MORE_ITEMS).
L'applicazione può anche impostare dwIndex sull'indice dell'ultimo valore nella prima chiamata alla funzione e decrerere l'indice fino a quando non viene enumerato il valore con indice 0. Per recuperare l'indice dell'ultimo valore, usare la funzione ORQueryInfoKey .
Durante l'uso di OREnumValue, un'applicazione non deve chiamare alcuna funzione del Registro di sistema offline che potrebbe modificare la chiave sottoposta a query.
Se i dati hanno il REG_SZ, REG_MULTI_SZ o REG_EXPAND_SZ tipo, la stringa potrebbe non essere stata archiviata con i caratteri null-terminazione appropriati. Pertanto, anche se la funzione restituisce ERROR_SUCCESS, l'applicazione deve assicurarsi che la stringa venga terminata correttamente prima di usarla; in caso contrario, può sovrascrivere un buffer. Si noti che le stringhe REG_MULTI_SZ devono avere due caratteri null-terminazione.
Per determinare le dimensioni massime dei buffer dei nomi e dei dati, usare la funzione ORQueryInfoKey .
Requisiti
| Requisito | Valore |
|---|---|
| Componente ridistribuibile |
Libreria del Registro di sistema offline di Windows versione 1.0 o successiva |
| Intestazione |
|
| DLL |
|
Vedi anche