1 out of 1 rated this helpful - Rate this topic

RegLoadAppKey function

Applies to: desktop apps only

Loads the specified registry hive.

Syntax

Copy

LONG WINAPI RegLoadAppKey(
  __in        LPCTSTR lpFile,
  __out       PHKEY phkResult,
  __in        REGSAM samDesired,
  __in        DWORD dwOptions,
  __reserved  DWORD Reserved
);

Parameters

lpFile [in]

The name of the file that has the registry data. This hive must have been created with the RegSaveKey function.

phkResult [out]

The handle to the root of the loaded hive.

The only way to access keys in the hive is through this handle. The registry will prevent an application from accessing keys in this hive using an absolute path to the key.

samDesired [in]

A mask that specifies the access rights for the key. For more information, see Registry Key Security and Access Rights.

dwOptions [in]

If this parameter is REG_PROCESS_APPKEY, the hive cannot be loaded by another process while is it loaded by the calling process. Otherwise, multiple processes can load the hive at the same time.

Reserved

This parameter is reserved.

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 generic description of the error.

Remarks

Unlike RegLoadKey, RegLoadAppKey does not load the hive under HKEY_LOCAL_MACHINE or HKEY_USERS. Instead, the hive is loaded under a special root that cannot be enumerated. As a result, there is no way to enumerate hives currently loaded by RegLoadAppKey. All operations on hives loaded by RegLoadAppKey have to be performed relative to the handle returned in phkResult.

If two processes are required to perform operations on the same hive, each process must call RegLoadAppKey to retrieve a handle. During the RegLoadAppKey operation, the registry will verify if the file has already been loaded. If it has been loaded, the registry will return a handle to the previously loaded hive rather than re-loading the hive.

All keys inside the hive must have the same security descriptor, otherwise the function will fail. This security descriptor must grant the caller the access specified by the samDesired parameter or the function will fail. You cannot use the RegSetKeySecurity function on any key inside the hive.

Each process can load only one hive at a time.

The hive is automatically unloaded when all handles to the keys inside the hive are closed.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or later. For more information, see Using the Windows Headers.

Requirements