RegOpenKeyEx function

Retrieves a handle to an open key in the registry. To open a key for which you do not have a security descriptor, use the RegOpenKey function.

Syntax


LONG RegOpenKeyEx(
  HKEY   hKey,
  LPCTSTR lpSubKey,
  DWORD  ulOptions,
  REGSAM samDesired,
  PHKEY  phkResult
);

Parameters

hKey: [in] A handle to an open key. The key must have been opened with the KEY_ENUMERATE_SUB_KEYS access right. For a list of valid values, see Registry Key Handles.

If this is a handle obtained from RegConnectRegistry, it must be an instance handle for the remote machine.

If this parameter is 0, the function attempts to open a handle to the predefined root key HKEY_CLASSES_ROOT.
lpSubKey: [in, optional] The name of the registry subkey to be opened. See Registry Element Sizes for more information.

This parameter can be NULL. If lpSubKey is NULL, the function opens the key identified by hKey.
ulOptions: [in] This parameter is reserved for future use and must be zero.
samDesired: [in] A mask that specifies the desired access rights to the key. For a list of values, see Registry Key Security and Access Rights.

The most commonly used values are:
- KEY_ALL_ACCESS
- KEY_READ
- KEY_WRITE
phkResult: [out] A pointer to a variable that receives the handle to the opened key.

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 retrieve a system-defined message that corresponds to the error code.

Return code	Description
ERROR_FILE_NOT_FOUND	The specified key does not exist.
ERROR_ACCESS_DENIED	The user does not have the required access rights to open the key.
ERROR_BAD_PATHNAME	The specified path is invalid.

Remarks

To open the root key, specify NULL for lpSubKey and use the handle obtained from RegConnectRegistry, or use one of the predefined HKEY constants (such as HKEY_CLASSES_ROOT).

The caller does not require the KEY_QUERY_VALUE access right to call RegOpenKeyEx. RegOpenKeyEx can be called with KEY_READ, KEY_WRITE, or KEY_ALL_ACCESS.

The caller must call RegCloseKey to close the key handle when it is no longer needed.

If lpSubKey is NULL, the function opens the key identified by hKey.

Requirements

Minimum supported client: Windows XP Professional [desktop apps only]

Minimum supported server: Windows Server 2003 R2 [desktop apps only]

Header: winreg.h (include Windows.h)

Library: Advapi32.lib

DLL: Advapi32.dll