RegDBCreateKeyEx
InstallShield 2020 » InstallScript Language Reference
Project:For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.
The RegDBCreateKeyEx function creates a key in the registry. You can also associate a class object with the newly created key (advanced users only). The newly created key does not have a value associated with it.
When logging is enabled, the InstallScript engine logs each key in the path that is passed through szKey to RegDBCreateKeyEx. For example, you might pass the following for szKey:
"Software" ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME
In this case, the InstallScript engine logs several keys:
| • | Software |
| • | The value of the IFX_COMPANY_NAME variable |
| • | The value of the IFX_PRODUCT_NAME variable |
The log flags a key as “created” if it did not already exist. In the aforementioned example, the Software key already exists on all target systems (HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER). The Software key is logged, but its “created” flag would be false, indicating that the key should not be removed during uninstallation. Any keys that are created and logged (because they did not already exist at the time the installation was running) are removed during uninstallation.
When a key is uninstalled, all of its subkeys are also uninstalled. Therefore, if you use RegDBCreateKeyEx to create a key or keys under a key that is already logged for uninstallation, the keys that you create will be uninstalled when the higher-level key is uninstalled. This behavior occurs regardless of whether logging is enabled when the installation creates your keys and regardless of the order in which the installation creates the keys. Therefore, in the aforementioned example, if logging is also enabled for a second installation that likewise uses RegDBCreateKeyEx to create a key for a different product under the IFX_COMPANY_NAME key that the first installation created, and the then end user uninstalls the first product, the entire IFX_COMPANY_NAME key, with both of the product subkeys, are removed. This may make the second product behave unexpectedly.
If you want to be able to share registry keys among multiple installations, it is recommended that you use the Registry view to configure the registry entries, instead of using the RegDBCreateKeyEx function. In the Registry view of an InstallScript project, you can mark a registry keys as shared (by right-clicking the key and then clicking Shared among several applications). During the uninstallation, the InstallScript engine removes a shared key only if no other logged installations that share the key still exist on the machine.
To view all of the registry keys that were logged during an installation and find out how each of their “created” flags were set, use the InstallShield Cabinet and Log File Viewer.
For more information about logging, see InstallScript Functions that Are Logged for Uninstallation.
Note:This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.
Syntax
RegDBCreateKeyEx ( szKey, szClass );
Parameters
|
Parameter |
Description |
|
szKey |
Specify the name of the key to create. Separate different levels in the subkey with a double backslash (\\). If the root key is HKEY_CLASSES_ROOT, you do not need to specify the HKEY_CLASSES_ROOT in this parameter. Unless you specify otherwise, the InstallScript engine creates the key as a subkey of HKEY_CLASSES_ROOT. To specify a different root key, you can call RegDBSetDefaultRoot before calling RegDBCreateKeyEx. |
|
szClass |
Specify the class name to associate with this key. |
Return Values
|
Return Value |
Description |
|
0 |
Indicates that the function successfully created the subkey. |
|
< 0 |
Indicates that the function was unable to create the subkey. You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling FormatMessage. |
Additional Information
RegDBCreateKeyEx is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.
Note:Windows does not allow the creation of a key directly under HKEY_LOCAL_MACHINE or HKEY_USERS.
By default, any text that is surrounded by angle brackets—for example, "<my registry entry text>"—in this function’s string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS constant.
See Also