RegCreateKeyEx (Compact 2013)

3/26/2014

This function creates the specified key. If the key already exists in the registry, the function opens it.

Syntax

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

Parameters

• hKey
  [in] Handle to a currently open key or one of the following predefined reserved handle values:

  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

  Windows Embedded Compact does not support the HKEY_CURRENT_CONFIG, HKEY_PERFORMANCE_DATA, or HKEY_DYN_DATA predefined reserved handle values.

  The key opened or created by this function is a subkey of the key identified by this parameter.

• lpSubKey
  [in] Pointer to a null-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified is a subkey of the key identified by hKey. This subkey must not begin with a backslash (\). If the parameter is set to NULL, this function behaves like RegOpenKey and opens the key specified by hKey. In Windows Embedded Compact, the maximum length of a key name is 255 characters, not including the terminating NULL character. You can only nest 16 levels of sub-keys in Windows Embedded Compact.

• Reserved
  [in] Reserved; set to 0 (zero).

• lpClass
  [in] Pointer to a null-terminated string that specifies the class or object type of this key. This parameter is ignored if the key already exists. In Windows Embedded Compact, the maximum length of a class string is 255 characters, not including the terminating NULL character.

• dwOptions
  [in] Registry key options. The following table shows possible values.

  Value	Description
  REG_OPTION_NON_VOLATILE	Default setting. All registry keys are created as non-volatile, and the information stored in memory is preserved when the OS is restarted. The RegSaveKey function saves keys that are non-volatile.
  REG_OPTION_VOLATILE	All registry keys are created as volatile, and 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 OS is shut down. The RegSaveKey function does not save volatile registry keys. This flag is ignored for keys that already exist.

• samDesired
  [in] Ignored. Set to zero.

• lpSecurityAttributes
  [in] Set to NULL. Windows Embedded Compact automatically assigns the key a default security descriptor.

• phkResult
  [out] Pointer to a variable that receives a handle to the opened or created key. When you no longer need the returned handle, call the RegCloseKey function to close it.

• lpdwDisposition
  [out] Pointer to a variable that receives disposition values. The following table shows possible values.

  Value	Description
  REG_CREATED_NEW_KEY	The key did not exist and was created.
  REG_OPENED_EXISTING_KEY	The key existed and was opened, without being changed.

Return Value

ERROR_SUCCESS indicates success. A nonzero error code defined in Winerror.h indicates failure. To get a generic description of the error, call FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag set. The message resource is optional, so FormatMessage it might fail.

Remarks

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

An application can use this function to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it owns the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already has the portion of the registry locked.

Requirements

See Also

Reference

Registry Functions
RegDeleteKey
RegOpenKeyEx
RegSetValueEx