Función QISearch (shlwapi.h)

Una implementación controlada por tablas del método IUnknown::QueryInterface .

Sintaxis

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

Parámetros

[in] that

Tipo: void*

Puntero a la base de un objeto COM.

[in] pqit

Tipo: LPCQITAB

Matriz de estructuras QITAB . La última estructura de la matriz debe tener su miembro piid establecido en NULL y su miembro dwOffset establecido en 0.

[in] riid

Tipo: REFIID

Referencia al IID de la interfaz que se va a recuperar a través de ppv.

[out] ppv

Tipo: void**

Cuando este método se devuelve correctamente, contiene el puntero de interfaz solicitado en riid.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se encontró la interfaz solicitada en la tabla o si la interfaz solicitada era IUnknown. Devuelve E_NOINTERFACE si no se encontró la interfaz solicitada.

Comentarios

Nota Antes de Windows Vista, QISearch no se exportó por nombre ni se declaró en un archivo de encabezado público. Para usarlo en esos casos, debe usar GetProcAddress y solicitar ordinal 219 desde Shlwapi.dll para obtener un puntero de función. En Windows Vista, QISearch se incluye en Shlwapi.h y esto no es necesario.

 

Si la interfaz solicitada es IUnknown, QISearch usa la primera entrada de la matriz especificada de estructuras QITAB . De lo contrario, QISearch busca en la tabla hasta que encuentre un IID coincidente o llegue al final de la tabla. Si se encuentra un IID coincidente, la función avanza el puntero de interfaz asociado por el número de bytes especificado por el miembro dwOffset de la estructura QITAB de la interfaz y se reinterpreta como un puntero COM. Ese puntero se asigna al parámetro ppv de la función QISearch. El método también llama a IUnknown::AddRef para incrementar el recuento de referencias de la interfaz.

Si QISearch llega al final de la tabla sin encontrar la interfaz, devuelve E_NOINTERFACE y establece ppv enNULL.

Es importante incluir todas las interfaces aplicables en la tabla. Por ejemplo, si el objeto implementa una interfaz derivada, también debe incluir la interfaz base en la tabla.

Se recomienda usar la macro IID_PPV_ARGS , definida en Objbase.h, para empaquetar los parámetros riid y ppv . Esta macro proporciona el IID correcto basado en la interfaz a la que apunta el valor de ppv, lo que elimina la posibilidad de un error de codificación en riid que podría dar lugar a resultados inesperados.

Nota Active Template Library (ATL) proporciona una versión significativamente mejor de una implementación controlada por tablas de QueryInterface.

 

Ejemplos

En el ejemplo siguiente se muestra cómo usar QISearch para implementar QueryInterface. Usa la macro offsetofclass de ATL para calcular el desplazamiento desde la base del objeto CSample a una interfaz especificada.

Este objeto admite dos interfaces aparte de IUnknown, por lo que hay dos entradas que no son NULL en la tabla QITAB . La entrada de cada interfaz especifica un puntero al IID asociado (IID_IPersist o IID_IPersistFolder) y el desplazamiento del puntero de interfaz en relación con el puntero base de la clase. En el ejemplo se usa la macro offsetofclass de ATL para determinar ese desplazamiento.

Nota Olvidar incluir todas las clases base, incluidas las indirectas, es un error común. Observe que hay una entrada para la interfaz IPersist . Esta interfaz es una clase base indirecta para CSample, heredada a través 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	Value
Cliente mínimo compatible	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server, Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Library	Shlwapi.lib
Archivo DLL	Shlwapi.dll (versión 5.0 o posterior)