通过

QISearch 函数 (shlwapi.h)

  • 项目

IUnknown：：QueryInterface 方法的表驱动实现。

语法

HRESULT QISearch(
  [in]  void     *that,
  [in]  LPCQITAB pqit,
  [in]  REFIID   riid,
  [out] void     **ppv
);

参数

[in] that

类型： void*

指向 COM 对象基的指针。

[in] pqit

类型： LPCQITAB

QITAB 结构的数组。 数组中的最后一个结构必须将其 piid 成员设置为 NULL ，其 dwOffset 成员设置为 0。

[in] riid

类型： REFIID

对要通过 ppv 检索的接口的 IID 的引用。

[out] ppv

类型： void**

此方法成功返回时，包含 riid 中请求的接口指针。

返回值

类型： HRESULT

如果在表中找到请求的接口或请求的接口为 IUnknown，则返回S_OK。 如果未找到请求的接口，则返回E_NOINTERFACE。

注解

注意 在 Windows Vista 之前， QISearch 未按名称导出或在公共头文件中声明。 若要在这些情况下使用它，必须使用 GetProcAddress 并从 Shlwapi.dll 请求序号 219 来获取函数指针。 在 Windows Vista 下， QISearch 包含在 Shlwapi.h 中，这不是必需的。
 
如果请求的接口为 IUnknown，则 QISearch 使用指定 QITAB 结构数组的第一个条目。 否则， QISearch 将搜索表，直到找到匹配的 IID 或到达表的末尾。 如果找到匹配的 IID，则该函数会按接口 QITAB 结构的 dwOffset 成员指定的字节数来推进关联的接口指针，并重新解释为 COM 指针。 该指针分配给 QISearch 函数的 ppv 参数。 方法还调用 IUnknown：：AddRef 来递增接口的引用计数。

如果 QISearch 到达表的末尾而未找到接口，则返回E_NOINTERFACE并将 ppv 设置为 NULL。

请务必在表中包括所有适用的接口。 例如，如果 对象实现派生接口，则还应在表中包括基接口。

建议使用 objbase.h 中定义的 IID_PPV_ARGS 宏来打包 riid 和 ppv 参数。 此宏基于 ppv 中值指向的接口提供正确的 IID，这消除了可能导致意外结果的 riid 编码错误的可能性。

注意 活动模板库 (ATL) 提供了查询接口的表驱动实现的明显更好的版本。
 

示例

以下示例演示如何使用 QISearch 实现 QueryInterface。 它使用 ATL 中的 offsetofclass 宏来计算从 CSample 对象基到指定接口的偏移量。

此对象支持除 IUnknown 以外的两个接口，因此 QITAB 表中有两个非 NULL 条目。 每个接口的条目指定指向关联的 IID (IID_IPersist 或IID_IPersistFolder) 的指针，以及接口指针相对于类的基指针的偏移量。 该示例使用 ATL 中的 offsetofclass 宏来确定该偏移量。

注意 忘记包含所有基类（包括间接基类）是一个常见错误。 请注意， IPersist 接口有一个条目。 此接口是 CSample 的间接基类，通过 IPersistFolder 继承。
 

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));
}

要求

要求 值
最低受支持的客户端 Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server、Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 shlwapi.h
Library Shlwapi.lib
DLL Shlwapi.dll (5.0 或更高版本)