| Home | Table of Contents | Please view with Internet Explorer (version 5.00 or higher) and enable scripting. For reasons, see Browsing This Web Site. |
This function opens or creates a subkey of a shell key.
HKEY
SHGetShellKey (
enum _SHELLKEY nShellKey,
LPCWSTR pszSubKey,
BOOL bCreate);
The nShellKey argument selects the shell key by a combination of bit flags in the SHELLKEY enumeration.
The pszSubKey argument provides the address of a null-terminated string that names the subkey, or is NULL to open the shell key itself.
The bCreate argument is non-zero to permit the function to create the subkey, or FALSE if the function may only open the subkey.
The function returns a handle to the opened subkey, if successful. It returns NULL for failure, in which case an error code is meant to be retrievable through GetLastError.
The function interprets the nShellKey argument through the three levels of bit mask defined for the SHELLKEY enumeration, to produce a root, key and subkey that together define which shell key is intended.
If the root mask selects the current-user branch but the calling thread has an impersonation access token, then the shell key is not relative to HKEY_CURRENT_USER but to the appropriate branch of HKEY_USERS. To open that branch, the function needs to be running on Windows 2000 or higher (for the RegOpenCurrentUser function). If the function fails due to any of these considerations, it sets ERROR_ACCESS_DENIED as the last error.
If the key mask produces an undefined value, the function fails, and the last error will be E_INVALIDARG.
The function maintains a per-process cache of handles to whatever shell keys are ever opened or created, except for handles that are opened in another user’s branch because of impersonation. The cache provides for all combinations of root and key, but each of the defined subkeys is cached only for each of the defined roots, with no allowance for different keys. The function does not actually enforce any particular correspondence of subkey to key. If it is called to open a shell key selected by root, key1 and subkey, and is then called to open a shell key selected by root, key2 and subkey, it will use on the second call whatever handle was cached for the first call. It is not known whether this is an implementation detail or an intended limitation of the enumeration.
Having got a handle to the selected shell key, the function proceeds to open or create the subkey named by the pszSubkey argument. If pszSubKey is NULL, the handle returned is for the shell key, but is a new handle, not a cached one.
The SHGetShellKey function is exported from SHLWAPI as ordinal 491 in version 6.00 and higher.
Though this function dates from 2001, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.