RegCreateKeyEx Function

Syntax

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

Parameters

• hKey: A handle to an open key. The calling process must have access to the key specified by the hKey parameter.
• lpSubKey: Pointer to a null-terminated string that specifies the name of the key to be created or opened. This key is a subkey of the key identified by hKey.
• Reserved: This parameter is reserved and must be zero.
• lpClass: Pointer to a null-terminated string that specifies the class type of the key. This string can be null.
• dwOptions: Specifies the key options. This parameter can be zero or the following value:
  • REG_OPTION_NON_VOLATILE: The key is stored permanently on the disk. This is the default.
  • REG_OPTION_VOLATILE: The key is not stored on the disk. This key and its subkeys are deleted when the last reference to it is removed.
• samDesired: A mask that specifies the desired access rights to the key.
• lpSecurityAttributes: Pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes of the new key.
• phkResult: Pointer to a variable that receives a handle to the newly opened or created key.
• lpdwDisposition: Pointer to a variable that receives a value indicating whether the subkey was created or opened. This parameter can be one of the following values:
  • REG_CREATED_NEW_KEY: The subkey was created.
  • REG_OPENED_EXISTING_KEY: The subkey already existed and was opened.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero return 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

The RegCreateKeyEx function creates a new key or opens an existing key. If the key is created, its default value is set to an empty string. If the key already exists, the function opens it and retrieves its information. If the key does not exist, it is created with the specified security attributes and options.

If lpClass is NULL, the key will have no class. If lpSecurityAttributes is NULL, the key will have a default security descriptor.

The access rights specified by samDesired are checked against the security descriptor of the key. If the calling process does not have the requested access rights, the function fails and returns ERROR_ACCESS_DENIED.

It is important to close the handle returned in phkResult when it is no longer needed by calling RegCloseKey.

Requirements

See Also

• RegCloseKey
• RegOpenKeyEx
• RegCreateKey
• RegDeleteKey