QISearch function (shlwapi.h)
A table-driven implementation of the IUnknown::QueryInterface method.
HRESULT QISearch(
[in] void *that,
[in] LPCQITAB pqit,
[in] REFIID riid,
[out] void **ppv
);
[in] that
Type: void*
A pointer to the base of a COM object.
[in] pqit
Type: LPCQITAB
An array of QITAB structures. The last structure in the array must have its piid member set to NULL and its dwOffset member set to 0.
[in] riid
Type: REFIID
A reference to the IID of the interface to retrieve through ppv.
[out] ppv
Type: void**
When this method returns successfully, contains the interface pointer requested in riid.
Type: HRESULT
Returns S_OK if the requested interface was found in the table or if the requested interface was IUnknown. Returns E_NOINTERFACE if the requested interface was not found.
If QISearch reaches the end of the table without finding the interface, it returns E_NOINTERFACE and sets ppv to NULL.
It is important to include all applicable interfaces in the table. For example, if the object implements a derived interface, you should also include the base interface in the table.
We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error in riid that could lead to unexpected results.
The following example illustrates how to use QISearch to implement QueryInterface. It uses the offsetofclass macro from ATL to compute the offset from the base of the CSample object to a specified interface.
This object supports two interfaces aside from IUnknown, so there are two non-NULL entries in the QITAB table. The entry for each interface specifies a pointer to the associated IID (IID_IPersist or IID_IPersistFolder) and the offset of the interface pointer relative to the class's base pointer. The sample uses the offsetofclass macro from ATL to determine that offset.
class CSample : public IPersistFolder
{
public:
CSample() { /* other construction goes here */ }
STDMETHODIMP QueryInterface(REFIID riid, void **ppv);
STDMETHODIMP_(ULONG) AddRef();
STDMETHODIMP_(ULONG) Release();
// *** IPersist ***
STDMETHODIMP GetClassID(CLSID *pClassID);
// *** IPersistFolder ***
STDMETHODIMP Initialize(LPCITEMIDLIST pidl);
private:
// private members go here
};
HRESULT CSample::QueryInterface(REFIID riid, void **ppv)
{
static QITAB rgqit[] =
{
QITABENT(CSample, IPersist),
QITABENT(CSample, IPersistFolder)
{ 0 },
};
return QISearch(this, rgqit, IID_PPV_ARGS(&ppv));
}
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional, Windows XP [desktop apps only] |
Minimum supported server | Windows 2000 Server, Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | shlwapi.h |
Library | Shlwapi.lib |
DLL | Shlwapi.dll (version 5.0 or later) |