Condividi tramite


Funzione RegCreateKeyTransactedA (winreg.h)

Crea la chiave del Registro di sistema specificata e la associa a una transazione. Se la chiave esiste già, la funzione lo apre. Si noti che i nomi delle chiavi non sono distinzione tra maiuscole e minuscole.

Le applicazioni che esegue 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 RegCreateKeyTransactedA(
  [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,
  [in]            HANDLE                      hTransaction,
                  PVOID                       pExtendedParemeter
);

Parametri

[in] hKey

Handle per una chiave del Registro di sistema aperta. Il processo di chiamata 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 con il descrittore di sicurezza della chiave del Registro di sistema, non la 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 RegCreateKeyTransacted o RegOpenKeyTransacted 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 alla chiave specificata da hKey.

Questo parametro non può essere NULL.

Reserved

Questo parametro è riservato e deve essere zero.

[in, optional] lpClass

Classe definita dall'utente di questa chiave. Questo parametro può essere ignorato. Questo parametro può essere NULL.

[in] dwOptions

Questo parametro può avere 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 ripristinare la chiave. Se il thread chiamante ha il privilegio 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 SE_RESTORE_NAME abilitato, la chiave viene aperta con i diritti di accesso ACCESS_SYSTEM_SECURITY e KEY_WRITE. Se entrambi i privilegi sono abilitati, la chiave ha i diritti di accesso combinati per entrambi i privilegi. Per altre informazioni, vedere Esecuzione con privilegi speciali.
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 che non sono 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, si verifica quando il sistema viene arrestato. Per le chiavi del Registro di sistema caricate dalla funzione RegLoadKey , si verifica quando viene eseguito regUnLoadKey corrispondente. La funzione RegSaveKey non salva chiavi volatili. Questo flag viene ignorato per le chiavi già esistenti.

[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 SECURITY_ATTRIBUTES che determina se l'handle restituito può essere ereditato dai processi figlio. Se lpSecurityAttributes è NULL, l'handle non può essere ereditato.

Il membro lpSecurityDescriptor 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 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 completato l'uso dell'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 esiste ed è stata creata.
REG_OPENED_EXISTING_KEY
0x00000002L
La chiave esiste ed è stata semplicemente aperta senza essere modificata.
 

Se lpdwDisposition è NULL, non vengono restituite informazioni sull'eliminazione.

[in] hTransaction

Handle per una transazione attiva. Questo handle viene restituito dalla funzione CreateTransaction .

pExtendedParemeter

Questo parametro è riservato e deve essere NULL.

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.

Commenti

Quando viene creata una chiave usando questa funzione, le operazioni successive sulla chiave vengono transazionate. Se viene eseguita un'operazione non transazionale sulla chiave prima del commit della transazione, la transazione viene eseguito il rollback. Dopo il commit o il rollback di una transazione, è necessario riaprire la chiave usando RegCreateKeyTransacted o RegOpenKeyTransacted con un handle di transazione attivo per eseguire operazioni aggiuntive transazioni. Per altre informazioni sulle transazioni, vedere Kernel Transaction Manager.

Si noti che le operazioni successive sulle sottochiavi di questa chiave non vengono transazionate automaticamente. Di conseguenza , RegDeleteKeyEx non esegue un'operazione di eliminazione transazionata. Usare invece la funzione RegDeleteKeyTransacted per eseguire un'operazione di eliminazione transazionata.

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

La funzione RegCreateKeyTransacted crea tutte le chiavi mancanti nel percorso specificato. Un'applicazione può sfruttare questo comportamento per creare diverse chiavi contemporaneamente. Ad esempio, un'applicazione può creare una sottochiave a quattro livelli profondi contemporaneamente alle tre sottochiave precedenti specificando una stringa del modulo seguente per il parametro lpSubKey :

subkey1\subkey2\subkey3\subkey4

Si noti che questo comportamento comporta la creazione di chiavi indesiderate se una chiave esistente nel percorso viene ortografiata in modo errato.

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

Nota

L'intestazione winreg.h definisce RegCreateKeyTransacted come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

   
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione winreg.h (include Windows.h)
Libreria Advapi32.lib
DLL Advapi32.dll

Vedi anche

Regclosekey

RegDeleteKeyTransacted

RegOpenKeyTransacted

Regsavekey

Funzioni del Registro di sistema

Panoramica del Registro di sistema

SECURITY_ATTRIBUTES