Funzione QISearch (shlwapi.h)

Articolo
03/05/2024

Implementazione basata su tabella del metodo IUnknown::QueryInterface .

Sintassi

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

Parametri

[in] that

Tipo: void*

Puntatore alla base di un oggetto COM.

[in] pqit

Tipo: LPCQITAB

Matrice di strutture QITAB . L'ultima struttura nella matrice deve avere il membro piid impostato su NULL e il membro dwOffset impostato su 0.

[in] riid

Tipo: REFIID

Riferimento all'IID dell'interfaccia da recuperare tramite ppv.

[out] ppv

Tipo: void**

Quando questo metodo restituisce correttamente, contiene il puntatore dell'interfaccia richiesto in riid.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se l'interfaccia richiesta è stata trovata nella tabella o se l'interfaccia richiesta era IUnknown. Restituisce E_NOINTERFACE se l'interfaccia richiesta non è stata trovata.

Commenti

Nota Prima di Windows Vista, QISearch non è stato esportato per nome o dichiarato in un file di intestazione pubblica. Per usarlo in questi casi, è necessario usare GetProcAddress e richiedere ordinale 219 da Shlwapi.dll per ottenere un puntatore a funzione. In Windows Vista, QISearch è incluso in Shlwapi.h e questo non è necessario.

Se l'interfaccia richiesta è IUnknown, QISearch usa la prima voce della matrice specificata di strutture QITAB . In caso contrario, QISearch cerca la tabella finché non trova un IID corrispondente o raggiunge la fine della tabella. Se viene trovato un IID corrispondente, la funzione avanza il puntatore dell'interfaccia associato in base al numero di byte specificati dal membro dwOffset della struttura QITAB dell'interfaccia e reinterpretata come puntatore COM. Tale puntatore viene assegnato al parametro ppv della funzione QISearch. Il metodo chiama anche IUnknown::AddRef per aumentare il conteggio dei riferimenti dell'interfaccia.

Se QISearch raggiunge la fine della tabella senza trovare l'interfaccia, restituisce E_NOINTERFACE e imposta ppv su NULL.

È importante includere tutte le interfacce applicabili nella tabella. Ad esempio, se l'oggetto implementa un'interfaccia derivata, è necessario includere anche l'interfaccia di base nella tabella.

È consigliabile usare la macro IID_PPV_ARGS definita in Objbase.h per creare il pacchetto dei parametri riid e ppv . Questa macro fornisce l'IID corretto in base all'interfaccia a cui punta il valore in ppv, che elimina la possibilità di un errore di codifica in riid che potrebbe causare risultati imprevisti.

Nota Active Template Library (ATL) offre una versione significativamente migliore di un'implementazione basata su tabelle di QueryInterface.

Esempio

Nell'esempio seguente viene illustrato come usare QISearch per implementare QueryInterface. Usa la macro offsetofclass da ATL per calcolare l'offset dalla base dell'oggetto CSample a un'interfaccia specificata.

Questo oggetto supporta due interfacce a parte IUnknown, quindi sono presenti due voci non NULL nella tabella QITAB . La voce per ogni interfaccia specifica un puntatore all'IID associato (IID_IPersist o IID_IPersistFolder) e all'offset del puntatore dell'interfaccia rispetto al puntatore di base della classe. L'esempio usa la macro offsetofclass da ATL per determinare tale offset.

Nota Dimenticando di includere tutte le classi di base, incluse quelle indirette, è un errore comune. Si noti che è presente una voce per l'interfaccia IPersist . Questa interfaccia è una classe di base indiretta per CSample, ereditata tramite 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));
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional, Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server, Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlwapi.h
Libreria	Shlwapi.lib
DLL	Shlwapi.dll (versione 5.0 o successiva)

Condividi tramite