Geoff Chappell - Software Analyst
This function presents a registry key as a query-source object.
HRESULT
QuerySourceCreateFromKey (
HKEY hKey,
PCWSTR lpSubKey,
BOOL bCreate,
REFIID riid,
PVOID *ppv);
The hKey argument provides either a handle to an open key or to a root key.
The lpSubKey argument provides the address of a null-terminated Unicode string that names a subkey that this function is to represent as a query-source object. This argument can be NULL to have the query-source object represent the key that is already open as hKey.
The bCreate argument is non-zero to permit the function to create the given key if it does not exist already (requires lpSubKey be not NULL).
The riid argument provides the IID of a desired interface to the query-source object.
The ppv argument provides the address of a variable that is to receive a pointer to the desired interface.
The function returns zero for success, else an error code.
If the function cannot get memory to support a registry-based query-source object, it fails (returning E_OUTOFMEMORY).
If the bCreate argument is zero, the function opens the given subkey, or if lpSubKey is NULL, opens a new handle to the key already represented by hKey. If the bCreate argument is non-zero, the function opens or creates the subkey named by lpSubKey, which must be non-NULL. (Specifically, the function obtains the behaviour of passing hKey and lpSubKey to the standard API function RegOpenKeyEx if bCreate is zero, else RegCreateKeyEx.) Whatever is given as bCreate, the function seeks KEY_READ access only. Failure to open or create the registry key is failure for the function.
The function queries the newly created query-source object for the interface represented by riid, to store an interface pointer at the address given by ppv. Failure to obtain the desired interface is failure for the function. The supported interfaces (in addition to IUnknown) are IObjectWithRegistryKey and IQuerySource.
The QueryValueString method accepts both REG_SZ and REG_EXPAND_SZ data (and expands the latter). If asked for a key’s default value, empty string data is regarded as an error.
The QueryValueDword method requires REG_DWORD data.
The QueryValueGuid method requires REG_SZ or REG_EXPAND_SZ data in the standard string representation of a GUID in curly braces.
The QueryValueDirect method is based on RegQueryValueEx and does not translate REG_EXPAND_SZ data. When it succeeds, the fFlags member of the FLAGGED_BYTE_BLOB holds the data type (e.g., REG_SZ).
Each of the querying methods takes a subkey and value as its first two arguments. If given a subkey, the method opens the subkey, queries for the value and closes the subkey. If querying multiple values in the one subkey, first call the OpenSource method to obtain a new query-source object for the subkey and then query the values in the new object.
The preceding description is for the SHLWAPI build 6.0.6000.16386 from Windows Vista. The following variations are known for earlier builds.
The IQuerySource interface has a method, SetValueDirect, that can set a value. To support this, KEY_READ access does not suffice, and the function instead asks for the MAXIMUM_ALLOWED access rights.
The QueryValueDword method accepts data of any type, up to 4 bytes. If there are not exactly 4 bytes of data, the function succeeds but the data is better regarded as undefined.
The QuerySourceCreateFromKey function is exported from SHLWAPI.DLL as ordinal 544 in version 6.00 and higher.
Though this function dates from 2001, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).