FONCTION QISearch (shlwapi.h)

Article
08/26/2023

Implémentation table de la méthode IUnknown ::QueryInterface .

Syntaxe

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

Paramètres

[in] that

Type : void*

Pointeur vers la base d’un objet COM.

[in] pqit

Type : LPCQITAB

Tableau de structures QITAB . La dernière structure du tableau doit avoir son membre piid défini sur NULL et son membre dwOffset défini sur 0.

[in] riid

Type : REFIID

Référence à l’IID de l’interface à récupérer via ppv.

[out] ppv

Type : void**

Lorsque cette méthode retourne correctement, contient le pointeur d’interface demandé dans riid.

Valeur retournée

Type : HRESULT

Retourne S_OK si l’interface demandée a été trouvée dans la table ou si l’interface demandée était IUnknown. Retourne E_NOINTERFACE si l’interface demandée est introuvable.

Remarques

Note Avant Windows Vista, QISearch n’était pas exporté par nom ou déclaré dans un fichier d’en-tête public. Pour l’utiliser dans ces cas, vous devez utiliser GetProcAddress et demander l’ordinal 219 à partir de Shlwapi.dll pour obtenir un pointeur de fonction. Sous Windows Vista, QISearch est inclus dans Shlwapi.h, ce qui n’est pas nécessaire.

Si l’interface demandée est IUnknown, QISearch utilise la première entrée du tableau spécifié de structures QITAB . Sinon, QISearch recherche la table jusqu’à ce qu’elle trouve un IID correspondant ou atteigne la fin de la table. Si un IID correspondant est trouvé, la fonction avance le pointeur d’interface associé par le nombre d’octets spécifié par le membre dwOffset de la structure QITAB de l’interface et réinterprété en tant que pointeur COM. Ce pointeur est affecté au paramètre ppv de la fonction QISearch. La méthode appelle également IUnknown ::AddRef pour incrémenter le nombre de références de l’interface.

Si QISearch atteint la fin de la table sans trouver l’interface, il retourne E_NOINTERFACE et définit ppv sur NULL.

Il est important d’inclure toutes les interfaces applicables dans la table. Par exemple, si l’objet implémente une interface dérivée, vous devez également inclure l’interface de base dans la table.

Nous vous recommandons d’utiliser la macro IID_PPV_ARGS , définie dans Objbase.h, pour empaqueter les paramètres riid et ppv . Cette macro fournit l’IID correct en fonction de l’interface pointée par la valeur dans ppv, ce qui élimine la possibilité d’une erreur de codage dans riid qui pourrait entraîner des résultats inattendus.

Note Active Template Library (ATL) fournit une version nettement meilleure d’une implémentation pilotée par table de QueryInterface.

Exemples

L’exemple suivant montre comment utiliser QISearch pour implémenter QueryInterface. Il utilise la macro offsetofclass d’ATL pour calculer le décalage de la base de l’objet CSample vers une interface spécifiée.

Cet objet prend en charge deux interfaces en dehors de IUnknown. Il existe donc deux entrées non NULL dans la table QITAB . L’entrée de chaque interface spécifie un pointeur vers l’IID associé (IID_IPersist ou IID_IPersistFolder) et le décalage du pointeur d’interface par rapport au pointeur de base de la classe. L’exemple utilise la macro offsetofclass d’ATL pour déterminer ce décalage.

Note Le fait d’oublier d’inclure toutes les classes de base, y compris les classes indirectes, est une erreur courante. Notez qu’il existe une entrée pour l’interface IPersist . Cette interface est une classe de base indirecte pour CSample, héritée via 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));
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server, Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 5.0 ou ultérieure)

Partager via