Função QISearch (shlwapi.h)

  • Artigo

Uma implementação controlada por tabela do método IUnknown::QueryInterface .

Sintaxe

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

Parâmetros

[in] that

Tipo: void*

Um ponteiro para a base de um objeto COM.

[in] pqit

Tipo: LPCQITAB

Uma matriz de estruturas QITAB . A última estrutura na matriz deve ter seu membro piid definido como NULL e seu membro dwOffset definido como 0.

[in] riid

Tipo: REFIID

Uma referência ao IID da interface a ser recuperada por meio de ppv.

[out] ppv

Tipo: void**

Quando esse método retorna com êxito, contém o ponteiro de interface solicitado em riid.

Retornar valor

Tipo: HRESULT

Retorna S_OK se a interface solicitada foi encontrada na tabela ou se a interface solicitada foi IUnknown. Retorna E_NOINTERFACE se a interface solicitada não foi encontrada.

Comentários

Nota Antes do Windows Vista, QISearch não era exportado por nome ou declarado em um arquivo de cabeçalho público. Para usá-lo nesses casos, você deve usar GetProcAddress e solicitar o ordinal 219 de Shlwapi.dll para obter um ponteiro de função. No Windows Vista, QISearch está incluído em Shlwapi.h e isso não é necessário.
 
Se a interface solicitada for IUnknown, o QISearch usará a primeira entrada da matriz especificada de estruturas QITAB . Caso contrário, o QISearch pesquisa a tabela até encontrar um IID correspondente ou chegar ao final da tabela. Se um IID correspondente for encontrado, a função avançará o ponteiro de interface associado pelo número de bytes especificado pelo membro dwOffset da estrutura QITAB da interface e será reinterpretada como um ponteiro COM. Esse ponteiro é atribuído ao parâmetro ppv da função QISearch. O método também chama IUnknown::AddRef para incrementar a contagem de referência da interface.

Se QISearch atingir o final da tabela sem localizar a interface, ela retornará E_NOINTERFACE e definirá ppv como NULL.

É importante incluir todas as interfaces aplicáveis na tabela. Por exemplo, se o objeto implementar uma interface derivada, você também deverá incluir a interface base na tabela.

Recomendamos que você use a macro IID_PPV_ARGS , definida em Objbase.h, para empacotar os parâmetros riid e ppv . Essa macro fornece o IID correto com base na interface apontada pelo valor em ppv, o que elimina a possibilidade de um erro de codificação no riid que pode levar a resultados inesperados.

Nota A ATL (Biblioteca de Modelos Ativos) fornece uma versão significativamente melhor de uma implementação controlada por tabela de QueryInterface.
 

Exemplos

O exemplo a seguir ilustra como usar QISearch para implementar QueryInterface. Ele usa a macro offsetofclass da ATL para calcular o deslocamento da base do objeto CSample para uma interface especificada.

Esse objeto dá suporte a duas interfaces além de IUnknown, portanto, há duas entradas não NULL na tabela QITAB . A entrada para cada interface especifica um ponteiro para o IID associado (IID_IPersist ou IID_IPersistFolder) e o deslocamento do ponteiro da interface em relação ao ponteiro base da classe. O exemplo usa a macro offsetofclass da ATL para determinar esse deslocamento.

Nota Esquecer de incluir todas as classes base, incluindo as indiretas, é um erro comum. Observe que há uma entrada para a interface IPersist . Essa interface é uma classe base indireta para CSample, herdada por meio de 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));
}

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server, Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shlwapi.h
Biblioteca Shlwapi.lib
DLL Shlwapi.dll (versão 5.0 ou posterior)