IQuerySource

The original IQuerySource methods are (as ordered in the virtual function table after the IUnknown methods):

with prototypes:

HRESULT EnumValues (IEnumString **);

HRESULT EnumSources (IEnumString **);

HRESULT QueryValueString (PCWSTR, PCWSTR, PWSTR *);

HRESULT QueryValueDword (PCWSTR, PCWSTR, DWORD *);

HRESULT QueryValueExists (PCWSTR, PCWSTR);

HRESULT QueryValueDirect (PCWSTR, PCWSTR, FLAGGED_BYTE_BLOB **);

HRESULT OpenSource (PCWSTR, BOOL, IQuerySource **);

HRESULT SetValueDirect (PCWSTR, PCWSTR, DWORD, DWORD, PBYTE);

The revision deletes one method, inserts another and rearranges the table:

with new or different prototypes:

HRESULT QueryValueGuid (PCWSTR, PCWSTR, GUID *);

HRESULT OpenSource (PCWSTR, IQuerySource **);

The methods deal with named values in a hierarchy of named sources. Each value has data, which may be a string, a dword, a GUID or a byte stream. A source may contain any number of values, and also a default value. A source may also contain more sources. The obvious model is the Windows registry, with keys and subkeys as sources.

Given an IQuerySource interface to a source, the EnumValues and EnumSources methods provide respectively for enumerating the source’s values and sub-sources. The QueryValueString, QueryValueDword, QueryValueGuid and QueryValueDirect methods get data in the various supported forms from a value in the source or in a sub-source. Each of these methods, and also QueryValueExists and SetValueDirect, take as their first two arguments

• the name of a sub-source, or NULL to represent the source;
• either the name of a value, or NULL to represent the default value.

The OpenSource method obtains an IQuerySource interface to a named sub-source.

Implementations

The original implementation (in SHLWAPI) provides for query-source objects to represent registry keys. Instantiation is arranged by calling the exported function QuerySourceCreateFromKey. Having called this function to obtain a query-source object for a particular registry key, the IQuerySource methods then provide for ways to:

• enumerate, query and (in the original version of the interface) set values in the key;
• enumerate subkeys;
• create a new query-source object for a subkey.

In Windows Vista, this SHLWAPI implementation is reproduced in PROPSYS.DLL, though without exporting the function.

The revised interface also has a new implementation in SHELL32, to provide a hard-coded simulation of a registry tree.

Availability

The IQuerySource interface is implemented in SHLWAPI.DLL version 6.00 and higher, and in SHELL32.DLL version 6.00 and higher. The revision begins with the builds of version 6.00 from Windows Vista.

Though this interface 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).