Condividi tramite


Funzione ZwCreateKey (wdm.h)

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:

  1. Come nome percorso completo, fornito nel membro ObjectName dell'oggetto ObjectAttributes. I nomi dei percorsi delle chiavi del Registro di sistema iniziano con \Registry.

  2. 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)

Vedi anche

ACCESS_MASK

InitializeObjectAttributes

Uso di nt e zw versioni delle routine di Servizi di sistema nativo

ZwClose

ZwDeleteKey

ZwEnumerateKey

ZwEnumerateValueKey

ZwFlushKey

ZwNotifyChangeKey

ZwOpenKey

ZwQueryValueKey

ZwSetValueKey