SHRunIndirectRegClientCommand

This function executes the registry command for opening a client.

Declaration

HRESULT
SHRunIndirectRegClientCommand (
    HWND hWnd,
    LPCWSTR pszClientType);

Parameters

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

The pszClient argument provides the address of a null-terminated string that names the client.

Return Value

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

Behaviour

The function executes whatever registry command is found from the key HKEY_LOCAL_MACHINE\Software\Clients\ClientType\default\shell\Open\command, where

• ClientType is the pszClientType argument;
• default is the string data from the default value of HKEY_LOCAL_MACHINE\Software\Clients\ClientType.

This function is implemented as a call to the RunIndirectRegCommand function, with HKEY_LOCAL_MACHINE and Software\Clients\ClientType as the key and subkey respectively, and Open as the verb.

Background

The SHRunIndirectRegClientCommand function deals specifically with opening so-called client applications, in the sense of Microsoft’s page Registering Programs with Client Types in the Shell Programmer’s Guide. The functionality recognises that:

• applications may be seen as having a general type, such as web browser or media player;
• that each type may be present on the computer in multiple examples, most notably as competing products from different manufacturers;
• and that selection from among the competing applications of each type should be eased.

To this end, Microsoft provides that such applications be described in a registry key HKEY_LOCAL_MACHINE\Software\Clients\ClientTypeName\CanonicalName, where

• ClientTypeName represents the general type of application
• and CanonicalName represents a particular application of that type.

Within this key may be many subkeys and values, but what is relevant to SHRunIndirectRegClientCommand is that the command to execute for opening the application is to be the default value from the key HKEY_LOCAL_MACHINE\Software\Clients\ClientTypeName\CanonicalName\shell\open\command.

So far, so good. Microsoft documents this much on the page already cited, and this is enough information so that an application’s manufacturer can know what to set into the registry so that the application can be identified and opened as an example of its type of application. What Microsoft seems not to document is the additional setting that selects one such application to be the default application of its type. This is arranged by setting the CanonicalName as the default value of the key HKEY_LOCAL_MACHINE\Software\Clients\ClientTypeName.

For an example of how all this works, imagine products named “QuickTime Player” and “Windows Media Player” which are both installed as “Media” clients, in the sense that the registry key HKEY_LOCAL_MACHINE\Software\Clients\Media has subkeys for each product. The name of one of the products is set as that key’s default value. That product is then the default media player. To start the default media player, software that knows the SHRunIndirectRegClientCommand function needn’t know which media players are installed, let alone which of them the user has chosen (or ignorantly allowed to remain) as the default: it simply calls the function, passing “Media” as the pszClientType argument. Software that doesn’t know the function can interpret the relevant registry keys and values itself, following the documentation.

Availability

The SHRunIndirectRegClientCommand function is exported from SHLWAPI as ordinal 467 in late builds of version 5.00 and then in all higher versions. However, the function has an earlier history in SHDOCVW, which exports it as ordinal 190 in early builds of version 5.00, discontinues it in later builds of version 5.00, and reinstates it for version 5.50 and higher (as a simple redirection to the SHLWAPI implementation).

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