Funzione ZwCreateKey (wdm.h)

Articolo
12/21/2024

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 per la 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 di DesiredAccess	Consente al chiamante di eseguire questa operazione
KEY_QUERY_VALUE	Leggere i valori di chiave.
KEY_SET_VALUE	Scrivere valori di chiave.
KEY_CREATE_SUB_KEY	Creare sottochiavi per la chiave.
KEY_ENUMERATE_SUB_KEYS	Leggere le sottochiavi della chiave.
KEY_CREATE_LINK	Creare un collegamento simbolico alla chiave. Questo flag non viene usato dai driver intermedi e del dispositivo.
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 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 intermedi e del dispositivo impostano questo parametro su zero.

[in, optional] Class

Puntatore a una stringa Unicode che contiene 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, specificate come combinazione compatibile dei flag seguenti.

flag CreateOptions	Descrizione
REG_OPTION_VOLATILE	La chiave non viene mantenuta al riavvio del sistema.
REG_OPTION_NON_VOLATILE	La chiave viene mantenuta al riavvio del sistema.
REG_OPTION_CREATE_LINK	La chiave appena creata è un collegamento simbolico. Questo flag non viene usato dai driver intermedi e del dispositivo.
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 intermedi e del dispositivo.

[out, optional] Disposition

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

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

Osservazioni

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.

Quando l'handle a cui punta 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 percorso completo, fornito nel membro ObjectName dell'input 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 rootDirectory membro dell'input ObjectAttributes.

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 fa riferimento RootDirectorye la chiave a cui rootDirectory fa riferimento deve essere stata aperta per KEY_CREATE_SUB_KEY accesso.

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

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

Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve 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 di 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 viene eseguita 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 da driver in modalità kernel, le NtXxx e ZwXxx versioni 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 Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

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	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)