Funzione RegCreateKeyExA (winreg.h)

Articolo
11/20/2024

Crea la chiave del Registro di sistema specificata. Se la chiave esiste già, la funzione la apre. 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 regCreateKeyTransacted .

Le applicazioni che esegue il backup o il ripristino dello stato del sistema, inclusi i file di sistema e gli hive del Registro di sistema, devono usare il servizio copia shadow del volume anziché le funzioni del Registro di sistema.

Sintassi

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       lpClass,
  [in]            DWORD                       dwOptions,
  [in]            REGSAM                      samDesired,
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]           PHKEY                       phkResult,
  [out, optional] LPDWORD                     lpdwDisposition
);

Parametri

[in] hKey

Handle per una chiave del Registro di sistema aperta. Il processo chiamante deve avere KEY_CREATE_SUB_KEY accesso alla chiave. Per altre informazioni, vedere sicurezza delle chiavi del Registro di sistema e diritti di accesso.

L'accesso per la creazione della chiave viene controllato rispetto al descrittore di sicurezza della chiave del Registro di sistema, non alla maschera di accesso specificata quando è stato ottenuto l'handle. Pertanto, anche se hKey è stato aperto con un samDesired di KEY_READ, può essere usato nelle operazioni che modificano il Registro di sistema, se consentito dal descrittore di sicurezza.

Questo handle viene restituito dalla funzione RegCreateKeyEx o RegOpenKeyEx oppure può essere una delle chiavi predefinite seguenti :

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in] lpSubKey

Nome di una sottochiave aperta o creata da questa funzione. La sottochiave specificata deve essere una sottochiave della chiave identificata dal parametro hKey ; può essere fino a 32 livelli profondi nell'albero del Registro di sistema. Per altre informazioni sui nomi delle chiavi, vedere Struttura del Registro di sistema.

Se lpSubKey è un puntatore a una stringa vuota, phkResult riceve un nuovo handle per la chiave specificata da hKey.

Questo parametro non può essere NULL.

Reserved

Questo parametro è riservato e deve essere zero.

[in, optional] lpClass

Tipo di classe definito dall'utente di questa chiave. Questo parametro può essere ignorato. Questo parametro può essere NULL.

[in] dwOptions

Questo parametro può essere uno dei valori seguenti.

Valore	Significato
REG_OPTION_BACKUP_RESTORE 0x00000004L	Se questo flag è impostato, la funzione ignora il parametro samDesired e tenta di aprire la chiave con l'accesso necessario per eseguire il backup o il ripristino della chiave. Se il thread chiamante ha il privilegio di SE_BACKUP_NAME abilitato, la chiave viene aperta con i diritti di accesso ACCESS_SYSTEM_SECURITY e KEY_READ. Se il thread chiamante ha il privilegio di SE_RESTORE_NAME abilitato, a partire da Windows Vista, la chiave viene aperta con i diritti di accesso ACCESS_SYSTEM_SECURITY, DELETE e KEY_WRITE. Se entrambi i privilegi sono abilitati, la chiave dispone dei diritti di accesso combinati per entrambi i privilegi. Per altre informazioni, vedere esecuzione con privilegi speciali.
REG_OPTION_CREATE_LINK 0x00000002L	Nota i collegamenti simbolici del Registro di sistema devono essere usati solo per la compatibilità delle applicazioni quando assolutamente necessario. Questa chiave è un collegamento simbolico. Il percorso di destinazione viene assegnato al valore L"SymbolicLinkValue" della chiave. Il percorso di destinazione deve essere un percorso assoluto del Registro di sistema.
REG_OPTION_NON_VOLATILE 0x00000000L	Questa chiave non è volatile; si tratta dell'impostazione predefinita. Le informazioni vengono archiviate in un file e vengono mantenute al riavvio del sistema. La funzione RegSaveKey salva le chiavi non volatili.
REG_OPTION_VOLATILE 0x00000001L	Tutte le chiavi create dalla funzione sono volatili. Le informazioni vengono archiviate in memoria e non vengono mantenute quando viene scaricato l'hive del Registro di sistema corrispondente. Per HKEY_LOCAL_MACHINE, questo si verifica solo quando il sistema avvia un arresto completo. Per le chiavi del Registro di sistema caricate dalla funzione RegLoadKey , questo si verifica quando viene eseguita la RegUnLoadKey corrispondente . La funzione regSaveKey non salva le chiavi volatili. Questo flag viene ignorato per le chiavi già esistenti. Nota In caso di arresto selezionato dall'utente, un arresto di avvio rapido è il comportamento predefinito per il sistema.

[in] samDesired

Maschera che specifica i diritti di accesso per la chiave da creare. Per altre informazioni, vedere sicurezza delle chiavi del Registro di sistema e diritti di accesso.

[in, optional] lpSecurityAttributes

Puntatore a una struttura di SECURITY_ATTRIBUTES che determina se l'handle restituito può essere ereditato dai processi figlio. Se lpSecurityAttributes è NULL, l'handle non può essere ereditato.

Il lpSecurityDescriptor membro della struttura specifica un descrittore di sicurezza per la nuova chiave. Se lpSecurityAttributes è NULL, la chiave ottiene un descrittore di sicurezza predefinito. Gli ACL in un descrittore di sicurezza predefinito per una chiave vengono ereditati dalla relativa chiave padre diretta.

[out] phkResult

Puntatore a una variabile che riceve un handle per la chiave aperta o creata. Se la chiave non è una delle chiavi predefinite del Registro di sistema, chiamare la funzione regCloseKey dopo aver terminato di usare l'handle.

[out, optional] lpdwDisposition

Puntatore a una variabile che riceve uno dei valori di eliminazione seguenti.

Valore	Significato
REG_CREATED_NEW_KEY 0x00000001L	La chiave non esisteva ed è stata creata.
REG_OPENED_EXISTING_KEY 0x00000002L	La chiave esisteva ed è stata semplicemente aperta senza essere modificata.

Se lpdwDisposition è NULL, non viene restituita alcuna informazione sull'eliminazione.

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.

Osservazioni

La chiave creata dalla funzione regCreateKeyEx non ha valori. Un'applicazione può usare la funzione RegSetValueEx per impostare i valori chiave.

La funzione RegCreateKeyEx crea tutte le chiavi mancanti nel percorso specificato. Un'applicazione può sfruttare questo comportamento per creare più chiavi contemporaneamente. Ad esempio, un'applicazione può creare quattro livelli di sottochiave contemporaneamente alle tre sottochiavi precedenti specificando una stringa del formato seguente per il parametro lpSubKey:

sottochiave1\subkey2\subkey3\subkey4

Si noti che questo comportamento comporterà la creazione di chiavi indesiderate se una chiave esistente nel percorso viene digitata in modo non corretto.

Un'applicazione non può creare una chiave figlio diretta di HKEY_USERS o HKEY_LOCAL_MACHINE. Un'applicazione può creare sottochiavi in livelli inferiori dei HKEY_USERS o HKEY_LOCAL_MACHINE alberi.

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 Registry Virtualization e dati dell'applicazione a 32 bit e a 64 bit nel Registro di sistema.

Nota

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

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winreg.h (include Windows.h)
libreria	Advapi32.lib
dll	Advapi32.dll