SHRegGetCLSIDKey

This function opens or creates the registry key for a CLSID, or optionally a subkey.

Declaration

HRESULT 
SHRegGetCLSIDKey (
    const CLSID *pclsid, 
    LPCTSTR lpSubKey, 
    BOOL bPerUser, 
    BOOL bCreate, 
    REGSAM samDesired, 
    HKEY *phKey);

The function exists in ANSI and Unicode forms.

Parameters

The pclsid argument is the address of the CLSID for the object whose registration is to be worked with.

The lpSubKey argument is the address of a null-terminated string that names a subkey. This argument may be NULL to indicate that the CLSID key itself is wanted, not a subkey.

The bPerUser argument is non-zero to select the CLSID key from within the current user’s Explorer key. Otherwise, the CLSID key is in HKEY_CLASSES_ROOT.

The bCreate argument is non-zero to permit the function to create the key or subkey if it does not exist already.

The samDesired argument specifies access rights that are desired to the key or subkey.

The phKey argument provides the address of a variable that is to receive a handle to the opened key or subkey.

Return Value

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

Behaviour

CLSID keys are well known even to many users for their multiplicity as subkeys under the CLSID key in HKEY_CLASSES_ROOT. Less well-known, even to programmers, is that the shell sometimes looks instead under the CLSID key in the current user’s Explorer key. The point to this is apparently to provide for per-user settings independently of the merged view that HKEY_CLASSES_ROOT presents of machine and user settings.

The choice of CLSID key for this function depends on the bPerUser argument. Whether the function is to work with this key or a named subkey depends on the lpSubKey argument. The following table shows the registry path for the selected key:

bPerUser not zero	lpSubKey not NULL	Registry Path
no	no	HKEY_CLASSES_ROOT\CLSID\{clsid}
no	yes	HKEY_CLASSES_ROOT\CLSID\{clsid}\subkey
yes	no	HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\{clsid}
yes	yes	HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\{clsid}\subkey

If the function cannot compose this path in a temporary buffer of 300 bytes, it fails. Otherwise, the function opens or creates the registry key on this path, asking for the specified access rights.

Availability

The SHRegGetCLSIDKey function is exported from SHLWAPI as ordinals 343 and 344 (for ANSI and Unicode forms respectively) in version 5.00 and higher. The ANSI form is retired in the SHLWAPI version 6.00 from Windows Vista, and higher, such that it fails trivially.

Though this function dates from as long ago as 1999, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).