QISearch-Funktion (shlwapi.h)

Artikel
08/26/2023

Eine tabellengesteuerte Implementierung der IUnknown::QueryInterface-Methode .

Syntax

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

Parameter

[in] that

Typ: void*

Ein Zeiger auf die Basis eines COM-Objekts.

[in] pqit

Typ: LPCQITAB

Ein Array von QITAB-Strukturen . Für die letzte Struktur im Array muss der piid-Member auf NULL und sein dwOffset-Element auf 0 festgelegt sein.

[in] riid

Typ: REFIID

Ein Verweis auf die IID der Schnittstelle, die über ppv abgerufen werden soll.

[out] ppv

Typ: void**

Wenn diese Methode erfolgreich zurückgegeben wird, enthält den in riid angeforderten Schnittstellenzeiger.

Rückgabewert

Typ: HRESULT

Gibt S_OK zurück, wenn die angeforderte Schnittstelle in der Tabelle gefunden wurde oder wenn die angeforderte Schnittstelle IUnknown war. Gibt E_NOINTERFACE zurück, wenn die angeforderte Schnittstelle nicht gefunden wurde.

Hinweise

Hinweis Vor Windows Vista wurde QISearch nicht nach Namen exportiert oder in einer öffentlichen Headerdatei deklariert. Um es in diesen Fällen zu verwenden, müssen Sie GetProcAddress verwenden und die Ordnungszahl 219 von Shlwapi.dll anfordern, um einen Funktionszeiger abzurufen. Unter Windows Vista ist QISearch in Shlwapi.h enthalten und dies ist nicht erforderlich.

Wenn die angeforderte Schnittstelle IUnknown ist, verwendet QISearch den ersten Eintrag des angegebenen Arrays von QITAB-Strukturen . Andernfalls durchsucht QISearch die Tabelle, bis sie entweder eine übereinstimmende IID findet oder das Ende der Tabelle erreicht. Wenn eine übereinstimmende IID gefunden wird, erhöht die Funktion den zugeordneten Schnittstellenzeiger um die Anzahl der Bytes, die vom dwOffset-Member der QITAB-Struktur der Schnittstelle angegeben und als COM-Zeiger neu interpretiert werden. Dieser Zeiger wird dem ppv-Parameter der QISearch-Funktion zugewiesen. Die -Methode ruft auch IUnknown::AddRef auf, um die Verweisanzahl der Schnittstelle zu erhöhen.

Wenn QISearch das Ende der Tabelle erreicht, ohne die Schnittstelle zu finden, wird E_NOINTERFACE zurückgegeben und ppv auf NULL festgelegt.

Es ist wichtig, alle anwendbaren Schnittstellen in die Tabelle aufzunehmen. Wenn das -Objekt beispielsweise eine abgeleitete Schnittstelle implementiert, sollten Sie auch die Basisschnittstelle in die Tabelle aufnehmen.

Es wird empfohlen, das makro IID_PPV_ARGS zu verwenden, das in Objbase.h definiert ist, um die Parameter riid und ppv zu packen. Dieses Makro stellt die richtige IID basierend auf der Schnittstelle bereit, auf die der Wert in ppv verweist, wodurch die Möglichkeit eines Codierungsfehlers in riid vermieden wird, der zu unerwarteten Ergebnissen führen könnte.

Hinweis Active Template Library (ATL) bietet eine deutlich bessere Version einer tabellengesteuerten Implementierung von QueryInterface.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie QiSearch zum Implementieren von QueryInterface verwendet wird. Es verwendet das Offsetofclass-Makro von ATL, um den Offset von der Basis des CSample-Objekts zu einer angegebenen Schnittstelle zu berechnen.

Dieses Objekt unterstützt neben IUnknown zwei Schnittstellen, sodass in der QITAB-Tabelle zwei Einträge ungleich NULL vorhanden sind. Der Eintrag für jede Schnittstelle gibt einen Zeiger auf die zugeordnete IID (IID_IPersist oder IID_IPersistFolder) und den Offset des Schnittstellenzeigers relativ zum Basiszeiger der Klasse an. Im Beispiel wird das offsetofclass-Makro aus ATL verwendet, um diesen Offset zu bestimmen.

Hinweis Das Vergessen, alle Basisklassen einzuschließen, einschließlich der indirekten Klassen, ist ein häufiger Fehler. Beachten Sie, dass es einen Eintrag für die IPersist-Schnittstelle gibt. Diese Schnittstelle ist eine indirekte Basisklasse für CSample, die über IPersistFolder geerbt wird.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server, Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlwapi.h
Bibliothek	Shlwapi.lib
DLL	Shlwapi.dll (Version 5.0 oder höher)

Freigeben über