RunRegCommand

This function executes the registry command found from the default value of an arbitrary registry key.

Declaration

HRESULT
RunRegCommand (
    HWND hWnd,
    HKEY hKey,
    LPCWSTR pszSubKey);

Parameters

The hWnd argument provides the window handle to use for message boxes while trying to execute the command.

The hKey argument provides a handle to an open registry key.

The pszSubKey argument provides the address of a null-terminated string that names a subkey in which to find the registry command.

Return Value

The function returns zero for success, else an error code.

Behaviour

At its simplest, the registry command is just the string data for the default value from the registry key key\subkey, where

• key is the open registry key represented by the hKey argument;
• subkey is the subkey named by the pszSubKey argument.

Command Reference

However, it is allowed that this string data is not the command itself but is instead a reference to some other registry value that supplies the command. This case applies if the string data has the form root:path\value, where

• root is HKCR, HKCU or HKLM, all case-insensitive;
• path contains but does not begin with any number of backslashes, and contains no colons;
• and the optional value has no backslashes or colons.

The registry command is then the string data for value in the key represented by path in the branch denoted by root. If value is empty, meaning that the reference has a trailing backslash, then the command is the string data for the default value in this key. The three valid prefixes that identify the root represent HKEY_CLASSES_ROOT, HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE respectively.

Execution

If a command is not found, whether directly or by reference, the function fails, with E_FAIL as the error code.

The function intreprets the registry command as a pathname, possibly in quotes, to an executable file, followed by command-line arguments. Execution is through ShellExecuteEx, in a normal window. If running on an NT version greater than 5.00 or on NT version 5.00 in a build later than 2195, execution of the command contributes to the executable’s usage count.

Availability

The RunRegCommand function is exported from SHLWAPI as ordinal 469 in late builds of version 5.00 and then in all higher versions.

Though this function dates from as long ago as 2000, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.