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 中可能導致非預期結果的編碼錯誤的可能性。

注意 Active Template Library (ATL) 提供查詢Interface 數據表驅動實作的大幅改善版本。
 

範例

下列範例說明如何使用 QISearch 來實作 QueryInterface。 它會使用 ATL 的 offsetofclass 宏，計算從 CSample 物件的基底到指定介面的位移。

除了 IUnknown 之外，這個物件還支援兩個介面，因此 QITAB 數據表中有兩個非 NULL 專案。 每個介面的專案會指定相關聯 IID 的指標 (IID_IPersist 或IID_IPersistFolder) ，以及相對於類別基底指標的介面指標位移。 此範例會使用 ATL 的 offsetofclass 宏來判斷該位移。

注意 忘記包含所有基類，包括間接類別，是常見的錯誤。 請注意， IPersist 介面有一個專案。 此介面是透過 IPersistFolder 繼承的 CSample 間接基類。
 

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
程式庫 Shlwapi.lib
Dll Shlwapi.dll (5.0 版或更新版本)