RegCreateKeyEx

RegCreateKeyEx creates the specified registry key. If the key already exists in the registry, the function opens it. See RegCreateKey for a basic version of this function.

Syntax

LONG RTAPI RegCreateKey(
    HKEY           hKey,
    LPCTSTR        lpSubKey,
    DWORD          Reserved,
    LPTSTR         lpClass,
    DWORD          dwOptions,
    REGSAM         samDesired,
    LPSECURITY_ATTRIBUTES  lpSecurityAttributes,
    PHKEY          phkResult,
    LPDWORD        lpdwDisposition 
  );

Parameters

hKey

A handle to an open registry key. The calling process must have KEY_CREATE_SUB_KEY access to the key. This handle is returned by the RegCreateKey, RegCreateKeyEx, RegOpenKey or RegOpenKeyEx function, or it can be one of the following predefined keys:

HKEY_LOCAL_MACHINE

HKEY_USERS

lpSubKey

The name of a key that this function opens or creates. This key must be a subkey of the key identified by the hKey parameter. Key names are not case sensitive. If this parameter is NULL or a pointer to an empty string, the function returns the handle to the predefined hKey parameter.

Reserved

Reserved parameter that must be set to zero.

lpClass

User-defined class type. This parameter is optional and can be NULL. This parameter may be ignored.

dwOptions

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.
REG_OPTION_CREATE_LINK 0x00000002L	This key is a symbolic link.
REG_OPTION_NON_VOLATILE 0x00000000L	This key is not volatile; this is the default.
REG_OPTION_VOLATILE 0x00000001L	All keys created by the function are volatile.

samDesired

Access mask that specifies the desired access rights for the key which can be one or more of following rights

Value	Meaning
KEY_QUERY_VALUE	Read key values.
KEY_SET_VALUE	Write key values.
KEY_CREATE_SUB_KEY	Create subkeys for the key.
KEY_ENUMERATE_SUB_KEYS	Read the key's subkeys.
KEY_CREATE_LINK	Create a symbolic link to the key. This flag is not used by device and intermediate drivers.
KEY_READ	Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY values.
KEY_WRITE	Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights.
KEY_EXECUTE	Equivalent to KEY_READ.
KEY_ALL_ACCESS	Combines the STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, and KEY_CREATE_LINK access rights.

lpSecurityAttributes

This parameter is ignored by RTX64.

phkResult

A pointer to a variable that receives a handle to the opened or created key.

lpdwDisposition

An optional 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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails the return value is a nonzero error code.

Remarks

The function 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 HKEY_USERS or HKEY_LOCAL_MACHINE trees.

An application should call RegCloseKey when the handle is no longer in or upon application exit.

An application can use the RegCreateKeyEx function to create one level deep at once.

RegCreateKeyEx will fail to create or open a registry key if the parameter hkey is not one of the following two standard pre-defined registry hive keys: HKEY_LOCAL_MACHINE or HKEY_USERS

Requirements

Minimum Supported Version	RTX64 2013
Header	windows.h
Library	Rtx_Rtss.lib