Creates the specified registry key and associates it with a transaction. If the key already exists, the function opens it. Note that key names are not case sensitive.

Applications that back up or restore system state including system files and registry hives should use the Volume Shadow Copy Service instead of the registry functions.

Syntax

LONG WINAPI RegCreateKeyTransacted(
  __in        HKEY hKey,
  __in        LPCTSTR lpSubKey,
  __reserved  DWORD Reserved,
  __in_opt    LPTSTR lpClass,
  __in        DWORD dwOptions,
  __in        REGSAM samDesired,
  __in_opt    const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  __out       PHKEY phkResult,
  __out_opt   LPDWORD lpdwDisposition,
  __in        HANDLE hTransaction,
  __reserved  PVOID pExtendedParemeter
);

Parameters

hKey [in]

A handle to an open registry key. The calling process must have KEY_CREATE_SUB_KEY access to the key. For more information, see Registry Key Security and Access Rights.

This handle is returned by the RegCreateKeyTransacted or RegOpenKeyTransacted function, or it can be one of the following predefined keys:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

lpSubKey [in]

The name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter; it can be up to 32 levels deep in the registry tree. For more information on key names, see Structure of the Registry.

This parameter cannot be NULL.

Reserved

This parameter is reserved and must be zero.

lpClass [in, optional]

The user-defined class of this key. This parameter may be ignored. This parameter can be NULL.

dwOptions [in]

This parameter can be one of the following values.

Value	Meaning
REG_OPTION_BACKUP_RESTORE 0x00000004L	If this flag is set, the function ignores the samDesired parameter and attempts to open the key with the access required to backup or restore the key. If the calling thread has the SE_BACKUP_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_READ access rights. If the calling thread has the SE_RESTORE_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_WRITE access rights. If both privileges are enabled, the key has the combined access rights for both privileges. For more information, see Running with Special Privileges.
REG_OPTION_NON_VOLATILE 0x00000000L	This key is not volatile; this is the default. The information is stored in a file and is preserved when the system is restarted. The RegSaveKey function saves keys that are not volatile.
REG_OPTION_VOLATILE 0x00000001L	All keys created by the function are volatile. The information is stored in memory and is not preserved when the corresponding registry hive is unloaded. For HKEY_LOCAL_MACHINE, this occurs when the system is shut down. For registry keys loaded by the RegLoadKey function, this occurs when the corresponding RegUnLoadKey is performed. The RegSaveKey function does not save volatile keys. This flag is ignored for keys that already exist.

 

samDesired [in]

A mask that specifies the access rights for the key. For more information, see Registry Key Security and Access Rights.

lpSecurityAttributes [in, optional]

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key. If lpSecurityAttributes is NULL, the key gets a default security descriptor. The ACLs in a default security descriptor for a key are inherited from its direct parent key.

phkResult [out]

A pointer to a variable that receives a handle to the opened or created key. If the key is not one of the predefined registry keys, call the RegCloseKey function after you have finished using the handle.

lpdwDisposition [out, optional]

A pointer to a variable that receives one of the following disposition values.

Value	Meaning
REG_CREATED_NEW_KEY 0x00000001L	The key did not exist and was created.
REG_OPENED_EXISTING_KEY 0x00000002L	The key existed and was simply opened without being changed.

 

If lpdwDisposition is NULL, no disposition information is returned.

hTransaction [in]

A handle to an active transaction. This handle is returned by the CreateTransaction function.

pExtendedParemeter

This parameter is reserved and must be NULL.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

When a key is created using this function, subsequent operations on the key are transacted. If a non-transacted operation is performed on the key before the transaction is committed, the transaction is rolled back. After a transaction is committed or rolled back, you must re-open the key using RegCreateKeyTransacted or RegOpenKeyTransacted with an active transaction handle to make additional operations transacted. For more information about transactions, see Kernel Transaction Manager.

Note that subsequent operations on subkeys of this key are not automatically transacted. Therefore, RegDeleteKeyEx does not perform a transacted delete operation. Instead, use the RegDeleteKeyTransacted function to perform a transacted delete operation.

The key that the RegCreateKeyTransacted function creates has no values. An application can use the RegSetValueEx function to set key values.

An application cannot create a key that is a direct child of HKEY_USERS or HKEY_LOCAL_MACHINE. An application can create subkeys in lower levels of the HKEY_USERS or HKEY_LOCAL_MACHINE trees.

Requirements

See Also

RegCloseKey

RegDeleteKeyTransacted

Registry Functions

Registry Overview

RegOpenKeyTransacted

RegSaveKey

SECURITY_ATTRIBUTES

Send comments about this topic to Microsoft

Build date: 11/19/2009