RegOverridePredefKey

The RegOverridePredefKey function maps a predefined registry key to the specified registry key.

LONG RegOverridePredefKey(
  HKEY hKey,     // predefined handle to key
  HKEY hNewHKey  // new handle to key
);

Parameters

hKey

[in] Handle to one of the following predefined reserved registry key handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
HKEY_PERFORMANCE_DATA

hNewHKey

[in] Handle to a key that is predefined or currently open. RegOverridePredefKey remaps hKey to refer to the hNewHKey key. This redirection applies only to the process that calls RegOverridePredefKey.

If hNewHKey is NULL, the function restores the default mapping of the predefined key.

Return Values

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

The RegOverridePredefKey function is intended for software installation programs. It allows them to remap a predefined key, load a DLL component that will be installed on the system, call an entry point in the DLL, and examine the changes to the registry that the component attempted to make. The installation program can then write those changes to the locations intended by the DLL, or make changes to the data before writing it.

For example, consider an installation program that installs an ActiveX control as part of an application installation. The installation program needs to call the control's DllRegisterServer entry point to enable the control to register itself. Before this call, the installation program can call RegOverridePredefKey to remap HKEY_CLASSES_ROOT to a temporary key such as HKEY_CURRENT_USER\TemporaryInstall\DllRegistration. It then calls DllRegisterServer, which causes the ActiveX control to write its registry entries to the temporary key. The installation program then calls RegOverridePredefKey again to restore the original mapping of HKEY_CLASSES_ROOT. The installation program can modify the keys written to the temporary key, if necessary, before copying them to the original HKEY_CLASSES_ROOT.

After the call to RegOverridePredefKey, you can safely call RegCloseKey to close the hNewHKey handle. The system maintains its own reference to hNewHKey.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winreg.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Registry Overview, Registry Functions, DllRegisterServer