Método IMultiQI::QueryMultipleInterfaces (objidlbase.h)

  • Artigo

Recupera ponteiros para várias interfaces com suporte em um objeto .

Chamar esse método é equivalente a emitir uma série de chamadas QueryInterface separadas, exceto que você não incorre na sobrecarga de um número correspondente de chamadas RPC. Em aplicativos multithread e ambientes distribuídos, manter as chamadas RPC no mínimo é essencial para um desempenho ideal.

Sintaxe

HRESULT QueryMultipleInterfaces(
  [in]      ULONG    cMQIs,
  [in, out] MULTI_QI *pMQIs
);

Parâmetros

[in] cMQIs

O número de elementos na matriz pMQIs .

[in, out] pMQIs

Uma matriz de estruturas MULTI_QI . Para obter mais informações, consulte Comentários.

Retornar valor

Esse método pode retornar os valores a seguir.

Código de retorno Descrição
S_OK
 O método recuperou ponteiros para todas as interfaces solicitadas.
S_FALSE
 O método recuperou ponteiros para algumas, mas não todas, das interfaces solicitadas.
E_NOINTERFACE
 O método recuperou ponteiros para nenhuma das interfaces solicitadas.

Comentários

O método QueryMultipleInterfaces usa como entrada uma matriz de estruturas MULTI_QI . Cada estrutura especifica um IID de interface e contém dois membros adicionais para receber um ponteiro de interface e um valor retornado.

Esse método obtém o máximo possível de ponteiros de interface solicitados diretamente do proxy de objeto. Para cada interface não implementada no proxy, o método chama o servidor para obter um ponteiro. Ao receber um ponteiro de interface do servidor, o método cria um proxy de interface correspondente e retorna seu ponteiro junto com ponteiros para as interfaces que ele já implementa.

Anotações aos Chamadores

Um chamador deve começar consultando o proxy de objeto para a interface IMultiQI . Se o proxy de objeto retornar um ponteiro para essa interface, o chamador deverá criar uma estrutura MULTI_QI para cada interface que deseja obter. Cada estrutura deve especificar um IID de interface e definir seu membro pItf como NULL. A falha ao definir o membro pItf como NULL fará com que o proxy de objeto ignore a estrutura.

No retorno, QueryMultipleInterfaces grava o ponteiro de interface solicitado e um valor retornado em cada estrutura MULTI_QI na matriz do cliente. O membro pItf recebe o ponteiro; o membro hr recebe o valor retornado.

Se o valor retornado de uma chamada para QueryMultipleInterfaces for S_OK, os ponteiros serão retornados para todas as interfaces solicitadas.

Se o valor retornado for E_NOINTERFACE, os ponteiros serão retornados para nenhuma das interfaces solicitadas. Se o valor retornado for S_FALSE, os ponteiros para uma ou mais interfaces solicitadas não serão retornados. Nesse caso, o cliente deve marcar o membro de rh de cada estrutura MULTI_QI para determinar quais interfaces foram adquiridas e quais não foram.

Se um cliente souber antecipadamente que usará várias interfaces de um objeto, ele poderá chamar QueryMultipleInterfaces antecipadamente e, posteriormente, se um QueryInterface for feito para uma das interfaces já adquiridas por meio de QueryMultipleInterfaces, nenhuma chamada RPC será necessária.

No retorno, o chamador deve marcar o membro hr de cada estrutura MULTI_QI para determinar quais ponteiros de interface foram e não foram retornados.

O cliente é responsável por liberar cada uma das interfaces adquiridas chamando Release.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho objidlbase.h (inclua ObjIdl.h)

Confira também

IMultiQI