RegCreateKeyEx Function

The RegCreateKeyEx function creates a new key or opens an existing one in the specified key. If the key is being created, the function supplies default values for a new key.


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

Parameters

Parameter	Description
`hKey`	A handle to an open key in the registry. The calling application does not have access rights to the key. This handle is obtained by calling `RegOpenKeyEx` or `RegCreateKeyEx`. It can also be one of the predefined keys.
`lpSubKey`	The name of the subkey to open or create. This is a relative path. For example, if `hKey` is a handle to `HKEY_USERS`, then `lpSubKey` can be "Software\MyApp".
`Reserved`	This parameter is reserved and must be zero.
`lpClass`	A pointer to a null-terminated string that specifies the class type of this key. This parameter can be NULL.
`dwOptions`	This parameter can be one of the following values: `REG_OPTION_NON_VOLATILE`: The key is stored by the system and is not destroyed when the system is rebooted. This is the default. `REG_OPTION_VOLATILE`: The key is not stored by the system. This type of key is deleted when the system is shut down.
`samDesired`	A mask that specifies the desired access rights to the key. For a list of values, see Registry Key Security and Access Rights.
`lpSecurityAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that specifies the security descriptors for the new key. If `NULL`, the key receives default security descriptors.
`phkResult`	A pointer to a variable that receives a handle to the opened or created registry key. This handle is valid only if the function returns success.
`lpdwDisposition`	A pointer to a variable that receives a value indicating whether the key was created or opened. This parameter can be one of the following values: `REG_CREATED_NEW_KEY`: The key was created. `REG_OPENED_EXISTING_KEY`: The key was opened.

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 descriptive message for the error code.

Remarks

The RegCreateKeyEx function creates a new key if the specified subkey does not exist. If the subkey already exists, the function opens it.

The lpClass parameter is optional. If it is NULL, the class of the key is not set. You can use the RegQueryInfoKey function to retrieve the class of a key.

If dwOptions is set to REG_OPTION_VOLATILE, the key is stored in memory and is not persistent. This is useful for temporary data.

Note

Applications that need to create registry keys should be aware of the security implications. It is recommended to grant the minimum necessary permissions when creating keys.

Requirements

Attribute	Value
Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winreg.h
Library	Advapi32.lib
DLL	Advapi32.dll