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