ZwCreateKey

NTSTATUS
    ZwCreateKey(
        OUT PHANDLE  KeyHandle,
        IN ACCESS_MASK  DesiredAccess,
        IN POBJECT_ATTRIBUTES  ObjectAttributes,
        IN ULONG  TitleIndex,
        IN PUNICODE_STRING  Class,                /* optional*/
        IN ULONG  CreateOptions,
        OUT PULONG  Disposition                     /* optional*/
        );

ZwCreateKey opens an existing key or creates a new key in the registry.

Parameters

KeyHandle

Points to a returned handle for a newly created or existing key if this call is successful.

DesiredAccess

Specifies the type of access that the caller requires to the key. The set of system-defined DesiredAccess flags determines the following specific access rights for key objects:

DesiredAccess Flags	Meaning
KEY_QUERY_VALUE	Value entries for the key can be read.
KEY_SET_VALUE	Value entries for the key can be written.
KEY_CREATE_SUB_KEYS	Subkeys for the key can be created.
KEY_ENUMERATE_SUB_KEYS	All subkeys for the key can be read.
KEY_NOTIFY	This flag is irrelevant to device and intermediate drivers, and to other kernel-mode code.
KEY_CREATE_LINK	A symbolic link to the key can be created. This flag is irrelvant to device and intermediate drivers.

Callers of ZwCreateKey can specify one or a compatible combination of the following for any key object:

DesiredAccess to Key Values	Maps to DesiredAccess Flags
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUBKEY
KEY_EXECUTE	KEY_READ. This value is irrelevant to device and intermediate drivers.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUBKEY, KEY_NOTIFY and KEY_CREATE_LINK

The STANDARD_RIGHTS_XXX are predefined system values used to enforce security on system objects.

ObjectAttributes

Points to the initialized object attributes of the key being opened or created. An ObjectName string for the key must be specified. If a RootDirectory handle also is supplied, the given name is relative to the key represented by the handle. Any given name must be within the object name space allocated to the registry, meaning that all names must begin with \Registry. RootHandle, if present, must be a handle to the root directory object, to \Registry, or to a key under \Registry.

TitleIndex

Device and intermediate drivers should set this parameter to zero.

Class

Points to the object class of the key. To the Configuration Manager, this is just a Unicode string.

CreateOptions

Specifies options to be applied when creating a key, as a compatible combination of the following:

Value	Meaning
REG_OPTION_VOLATILE	Key is not to be stored across boots.
REG_OPTION_NON_VOLATILE	Key is preserved when the system is rebooted.
REG_OPTION_CREATE_LINK	The created key is a symbolic link. This value is irrelevant to device and intermediate drivers.
REG_OPTION_BACKUP_RESTORE	Key is being opened or created with special privileges allowing backup/restore operations. This value is irrelevant to device and intermediate drivers.

Disposition

Points to a variable that receives a value indicating whether a new key was created in the \Registry tree or an existing one opened:

Value	Meaning
REG_CREATED_NEW_KEY	A new key object was created.
REG_OPENED_EXISTING_KEY	An existing key object was opened.

Return Value

ZwCreateKey returns STATUS_SUCCESS if the given key was created or opened.

Comments

If the key specified by ObjectAttributes does not exist, an attempt is made to create it. For this attempt to succeed, the new key must be a direct subkey of the key referred to by KeyHandle, and the given KeyHandle must have been opened for KEY_CREATE_SUB_KEY access.

If the specified key already exists, it is opened and its value is not affected in any way.

The security attributes specified by ObjectAttributes when a key is created determine whether the specified DesiredAccess is granted on subsequent calls to ZwCreateKey and ZwOpenKey.

Callers of ZwCreateKey must be running at IRQL PASSIVE_LEVEL.

See Also

InitializeObjectAttributes, ZwClose, ZwDeleteKey, ZwEnumerateKey, ZwEnumerateValueKey, ZwFlushKey, ZwOpenKey, ZwQueryValueKey, ZwSetValueKey