Funzione RegCreateKeyW (winreg.h)

Articolo
11/20/2024

Crea la chiave del Registro di sistema specificata. Se la chiave esiste già nel Registro di sistema, la funzione la apre.

Nota Questa funzione viene fornita solo per compatibilità con le versioni a 16 bit di Windows. Le applicazioni devono usare la funzione RegCreateKeyEx . Tuttavia, le applicazioni che eserebbero il backup o il ripristino dello stato del sistema, inclusi i file di sistema e gli hives del Registro di sistema, devono usare il servizio copia shadow del volume anziché le funzioni del Registro di sistema.

Sintassi

LSTATUS RegCreateKeyW(
  [in]           HKEY    hKey,
  [in, optional] LPCWSTR lpSubKey,
  [out]          PHKEY   phkResult
);

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 creano chiavi se consentite 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, optional] lpSubKey

Nome di una chiave che questa funzione apre o crea. Questa chiave deve essere una sottochiave della chiave identificata dal parametro hKey.

Per altre informazioni sui nomi delle chiavi, vedere Struttura del Registro di sistema.

Se hKey è una delle chiavi predefinite, lpSubKey potrebbe essere NULL. In tal caso, phkResult riceve lo stesso handle hKey passato alla funzione.

[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.

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

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 .

La funzione regCreateKey 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.

Nota

L'intestazione winreg.h definisce RegCreateKey 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