| LONG RegCreateKeyEx(hkey, lpszSubKey, dwReservced, lpszClass, fdwOptions, samDesired, lpSecurityAttributes, phkResult, lpdwDisposition) | |||||
| HKEY hkey; | /* handle of an open key | */ | |||
| LPTSTR lpszSubKey; | /* address of subkey name | */ | |||
| DWORD dwReserved; | /* must be zero | */ | |||
| LPTSTR lpszClass; | /* address of class string | */ | |||
| DWORD fdwOptions; | /* special options flag | */ | |||
| REGSAM samDesired; | /* desired security access | */ | |||
| LPSECURITY_ATTRIBUTES lpSecurityAttributes; | /* key security | */ | |||
| PHKEY phkResult; | /* buffer for opened handle | */ | |||
| LPDWORD lpdwDisposition; | /* buffer for disposition | */ | |||
The RegCreateKeyEx function creates the specified key. If the key already exists in the registration database, the function opens it.
hkey
Identifies a currently open key or any of the following predefined reserved handle values:
HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS
The key opened or created by the RegCreateKeyEx function is a subkey of the key identified by the hkey parameter.
lpszSubKey
Points to a null-terminated string specifying the subkey to open or create. lpszSubKey is always relative to the key specified by hkey. This value must not be NULL.
dwReserved
Reserved; must be zero.
lpszClass
Points to a null-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists.
fdwOptions
Specifies special options for the key. Currently, this parameter can have one of the following values:
| Value | Meaning |
| REG_OPTION_VOLATILE | ||
| This key is volatile, and should not be preserved across a system reboot. | ||
| REG_OPTION_NON_VOLATILE | ||
| This key is nonvolatile, and should be preserved across a system reboot. | ||
By default, keys are not volatile. This option is ignored if the key already exists.
samDesired
Specifies a security access mask that specifies the desired security access for the new key. This parameter may be some combination of the following values:
| Value | Meaning |
| KEY_ALL_ACCESS | ||
| Combines query value, enumerate subkey, notify, create subkey and set value access. | ||
| KEY_CREATE_SUB_KEY | ||
| Permission to create subkeys. | ||
| KEY_ENUMERATE_SUB_KEYS | ||
| Permission to enumerate subkeys. | ||
| KEY_EXECUTE | ||
| Read access. | ||
| KEY_NOTIFY | ||
| Change notification will occur. | ||
| KEY_QUERY_VALUE | ||
| Permission to query subkey data. | ||
| KEY_READ | ||
| Combines query value, enumerate subkey, and notify access. | ||
| KEY_SET_VALUE | ||
| Permission to set subkey data. | ||
| KEY_WRITE | ||
| Combines set value and create subkey access. | ||
lpSecurityAttributes
Points to a SECURITY_ATTRIBUTES data structure that specifies the the security attributes for the new key. The SECURITY_ATTRIBUTES data structure has the following form:
typedef struct _SECURITY_ATTRIBUTES { /* sa */
DWORD nLength;
LPVOID lpSecurityDescriptor;
BOOL bInheritHandle;
} SECURITY_ATTRIBUTES;
This parameter can be NULL if the new key has no security. If the operating system does not support security, this parameter is ignored.
phkResult
Points to a variable that receives the handle of the key that is opened or created.
lpdwDisposition
Points to a variable that receives one of the following disposition values:
| Value | Meaning |
| REG_CREATED_NEW_KEY | ||
| The key did not exist and was created. | ||
| REG_OPENED_EXISTING_KEY | ||
| The key existed, and was simply opened without being changed. | ||
The return value is ERROR_SUCCESS if the function is successful. Otherwise, it is an error value.
The key created by this function has no values. An application can use the RegSetValue or RegSetValueEx function to set key values.
The key specified by hkey must have been opened with KEY_CREATE_SUB_KEY access. Use the RegCreateKeyEx or RegOpenKeyEx function to open the key.
RegCreateKeyEx is atomic; an application can use it to cooperatively lock a portion of the registry. When the locking process creates a new key, it receives REG_CREATED_NEW_KEY, indicating that it “owns” the lock. Another process attempting to create the same key receives REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.
The RegCreateKeyEx function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).
RegCreateKey, RegOpenKey, RegOpenKeyEx