Funzione RegOpenKeyExA (winreg.h)

Articolo
03/13/2024

Apre la chiave del Registro di sistema specificata. Si noti che i nomi delle chiavi non fanno distinzione tra maiuscole e minuscole.

Per eseguire operazioni del Registro di sistema transazioni su una chiave, chiamare la funzione RegOpenKeyTransacted .

Sintassi

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

Parametri

[in] hKey

Handle per una chiave del Registro di sistema aperta. Questo handle viene restituito dalla funzione RegCreateKeyEx o RegOpenKeyEx oppure può essere una delle chiavi predefinite seguenti:

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIG HKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

Nome della sottochiave del Registro di sistema da aprire.

I nomi delle chiavi non fanno distinzione tra maiuscole e minuscole.

Se il parametro lpSubKey è NULL o un puntatore a una stringa vuota e se hKey è una chiave predefinita, il sistema aggiorna la chiave predefinita e phkResult riceve lo stesso handle hKey passato alla funzione. In caso contrario, phkResult riceve un nuovo handle per la chiave aperta.

Per altre informazioni, vedere Limiti delle dimensioni degli elementi del Registro di sistema.

[in] ulOptions

Specifica l'opzione da applicare all'apertura della chiave. Impostare questo parametro su zero o su quanto segue:

Valore	Significato
REG_OPTION_OPEN_LINK	La chiave è un collegamento simbolico. I collegamenti simbolici del Registro di sistema devono essere usati solo quando è assolutamente necessario.

[in] samDesired

Maschera che specifica i diritti di accesso desiderati per la chiave da aprire. La funzione ha esito negativo se il descrittore di sicurezza della chiave non consente l'accesso richiesto per il processo chiamante. Per altre informazioni, vedere Sicurezza e diritti di accesso delle chiavi del Registro di sistema.

[out] phkResult

Puntatore a una variabile che riceve un handle per la chiave aperta. Se la chiave non è una delle chiavi predefinite del Registro di sistema, chiamare la funzione RegCloseKey al termine dell'uso dell'handle.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene 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.

Nota

Nelle versioni legacy di Windows, questa API viene esposta anche da kernel32.dll.

Commenti

A differenza della funzione RegCreateKeyEx , la funzione RegOpenKeyEx non crea la chiave specificata se la chiave non esiste nel Registro di sistema.

Alcune operazioni del Registro di sistema eseguono controlli di accesso rispetto al descrittore di sicurezza della chiave, non alla maschera di accesso specificata quando è stato ottenuto l'handle per la chiave. Ad esempio, anche se una chiave viene aperta con un samDesired di KEY_READ, può essere usata per creare chiavi del Registro di sistema se il descrittore di sicurezza della chiave è consentito. Al contrario, la funzione RegSetValueEx richiede in particolare che la chiave venga aperta con il diritto di accesso KEY_SET_VALUE.

Se il servizio o l'applicazione rappresenta utenti diversi, non usare questa funzione con HKEY_CURRENT_USER. Chiamare invece la funzione RegOpenCurrentUser .

Si noti che le operazioni che accedono a determinate chiavi del Registro di sistema vengono reindirizzate. Per altre informazioni, vedere Virtualizzazione del Registro di sistema e dati delle applicazioni a 32 bit e a 64 bit nel Registro di sistema.

Esempio

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

Per visualizzare questo esempio nel contesto, vedere Eliminazione di una chiave con sottochiavi.

Nota

L'intestazione winreg.h definisce RegOpenKeyEx 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 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winreg.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll