Funzione ZwCreateKey (wdm.h)

Articolo
08/08/2023

La routine ZwCreateKey crea una nuova chiave del Registro di sistema o ne apre una esistente.

Sintassi

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parametri

[out] KeyHandle

Puntatore a una variabile HANDLE che riceve un handle alla chiave.

[in] DesiredAccess

Specifica un valore ACCESS_MASK che determina l'accesso richiesto all'oggetto. Oltre ai diritti di accesso definiti per tutti i tipi di oggetti (vedere ACCESS_MASK), il chiamante può specificare uno o più dei diritti di accesso seguenti, specifici per le directory degli oggetti:

Flag DesiredAccess	Consente al chiamante di eseguire questa operazione
KEY_QUERY_VALUE	Leggere i valori chiave.
KEY_SET_VALUE	Scrivere valori chiave.
KEY_CREATE_SUB_KEY	Creare sottochiave per la chiave.
KEY_ENUMERATE_SUB_KEYS	Leggere le sottochiave della chiave.
KEY_CREATE_LINK	Creare un collegamento simbolico alla chiave. Questo flag non viene usato dai driver di dispositivo e intermedi.
KEY_NOTIFY	Chiedere di ricevere una notifica quando il nome, il valore o gli attributi della chiave cambiano. Per altre informazioni, vedere ZwNotifyChangeKey.

Il chiamante può anche specificare una delle costanti seguenti, che combina diversi flag ACCESS_MASK.

Costante	È costituito da questi flag di ACCESS_MASK
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS e KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE e KEY_CREATE_SUB_KEY
KEY_EXECUTE	Uguale a KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY e KEY_CREATE_LINK

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che specifica il nome dell'oggetto e altri attributi. Usare InitializeObjectAttributes per inizializzare questa struttura. Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes.

TitleIndex

I driver di dispositivo e intermedi impostano questo parametro su zero.

[in, optional] Class

Puntatore a una stringa Unicode contenente la classe oggetto della chiave. Queste informazioni vengono usate da Configuration Manager.

[in] CreateOptions

Specifica le opzioni da applicare durante la creazione o l'apertura di una chiave, specificata come combinazione compatibile dei flag seguenti.

Flag CreateOptions	Descrizione
REG_OPTION_VOLATILE	La chiave non viene mantenuta quando il sistema viene riavviato.
REG_OPTION_NON_VOLATILE	La chiave viene mantenuta quando il sistema viene riavviato.
REG_OPTION_CREATE_LINK	La chiave appena creata è un collegamento simbolico. Questo flag non viene usato dai driver di dispositivo e intermedi.
REG_OPTION_BACKUP_RESTORE	La chiave deve essere creata o aperta con privilegi speciali che consentono operazioni di backup e ripristino. Questo flag non viene usato dai driver di dispositivo e intermedi.

[out, optional] Disposition

Puntatore a una variabile che riceve un valore che indica se è stata creata una nuova chiave o una variabile esistente aperta.

Valore di eliminazione	Descrizione
REG_CREATED_NEW_KEY	È stata creata una nuova chiave.
REG_OPENED_EXISTING_KEY	È stata aperta una chiave esistente.

Valore restituito

ZwCreateKey restituisce STATUS_SUCCESS in caso di esito positivo o il codice di errore NTSTATUS appropriato in caso di errore.

Commenti

ZwCreateKey fornisce un handle che il chiamante può usare per modificare una chiave del Registro di sistema. Per altre informazioni, vedere Uso del Registro di sistema in un driver.

Una volta che l'handle puntato da KeyHandle non è più in uso, il driver deve chiamare ZwClose per chiuderlo.

Esistono due modi alternativi per specificare il nome del file da creare o aprire con ZwCreateKey:

Come nome percorso completo, fornito nel membro ObjectName dell'oggetto ObjectAttributes. I nomi dei percorsi delle chiavi del Registro di sistema iniziano con \Registry.
Come pathname relativo a un'altra chiave del Registro di sistema, rappresentata dall'handle nel membro RootDirectorydell'oggetto ObjectAttributes di input.

Se la chiave specificata da ObjectAttributes non esiste, la routine tenta di creare la chiave. Per questo tentativo di esito positivo, la nuova chiave deve essere una sottochiave diretta della chiave a cui viene fatto riferimento da RootDirectory e la chiave a cui fa riferimento RootDirectory deve essere stata aperta per l'accesso KEY_CREATE_SUB_KEY.

Se la chiave specificata esiste già, viene aperta e il relativo valore non è interessato in alcun modo.

Gli attributi di sicurezza specificati da ObjectAttributes quando viene creata una chiave determinano se l'oggetto DesiredAccess specificato viene concesso nelle chiamate successive a ZwCreateKey e ZwOpenKey.

Se il chiamante non è in esecuzione in un contesto di thread di sistema, è necessario assicurarsi che gli handle creati siano handle privati. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver. Per altre informazioni, vedere Handle degli oggetti.

Per altre informazioni sull'uso delle chiavi del Registro di sistema, vedere Uso del Registro di sistema in un driver.

Se la chiamata a questa funzione si verifica in modalità utente, è necessario usare il nome "NtCreateKey" anziché "ZwCreateKey".

La routine NtCreateKey nel kernel di Windows non è direttamente accessibile ai driver in modalità kernel.

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen (wdm)