Método IUnknown::QueryInterface(REFIID,void**) (unknwn.h)

  • Artigo

Consulta um objeto COM para um ponteiro para uma de suas interfaces; identificando a interface por uma referência ao IID (identificador de interface). Se o objeto COM implementar a interface , ele retornará um ponteiro para essa interface depois de chamar IUnknown::AddRef nela.

Sintaxe

HRESULT QueryInterface(
  REFIID riid,
  void   **ppvObject
);

Parâmetros

riid

Tipo: REFIID

Uma referência ao IID (identificador de interface) da interface que está sendo consultada.

ppvObject

Tipo: void**

O endereço de um ponteiro para uma interface com o IID especificado no parâmetro riid . Como você passa o endereço de um ponteiro de interface, o método pode substituir esse endereço pelo ponteiro para a interface que está sendo consultada. Após o retorno bem-sucedido, *ppvObject (o endereço desreferenciado) contém um ponteiro para a interface solicitada. Se o objeto não der suporte à interface , o método definirá *ppvObject (o endereço desreferenciado) como nullptr.

Retornar valor

Esse método retornará S_OK se houver suporte para a interface e E_NOINTERFACE caso contrário. Se ppvObject (o endereço) for nullptr, esse método retornará E_POINTER.

Comentários

Para qualquer objeto COM fornecido (também conhecido como componente COM), uma consulta específica para a interface IUnknown em qualquer uma das interfaces do objeto deve sempre retornar o mesmo valor de ponteiro. Isso permite que um cliente determine se dois ponteiros apontam para o mesmo componente chamando QueryInterface com IID_IUnknown e comparando os resultados. Especificamente, não é o caso de que consultas para interfaces diferentes de IUnknown (até mesmo a mesma interface por meio do mesmo ponteiro) devem retornar o mesmo valor de ponteiro.

Há quatro requisitos para implementações de QueryInterface (nesses casos, "deve ter êxito" significa que "deve ter êxito ao impedir falhas catastróficas").

  • O conjunto de interfaces acessíveis em um objeto por meio de QueryInterface deve ser estático, não dinâmico. Isso significa que, se uma chamada para QueryInterface para um ponteiro para uma interface especificada for bem-sucedida na primeira vez, ela deverá ser bem-sucedida novamente. Se a chamada falhar pela primeira vez, ela deverá falhar em todas as chamadas subsequentes.
  • Ele deve ser reflexivo– se um cliente mantiver um ponteiro para uma interface em um objeto e as consultas de cliente para essa interface, a chamada deverá ser bem-sucedida.
  • Ele deve ser simétrico— se um cliente que mantém um ponteiro para uma interface consulta com êxito para outra, uma consulta por meio do ponteiro obtido para a primeira interface deve ter êxito.
  • Ele deve ser transitivo– se um cliente que mantém um ponteiro para uma consulta de interface com êxito por um segundo e, por meio dessa ponteiro, consultar com êxito uma terceira interface, uma consulta para a primeira interface por meio do ponteiro para a terceira interface deverá ter êxito.

Observações aos implementadores

As implementações de QueryInterface nunca devem marcar ACLs. O main motivo para essa regra é que o COM requer que um objeto que dê suporte a uma interface específica sempre retorne êxito quando consultado para essa interface. Outro motivo é que a verificação de ACLs em QueryInterface não fornece nenhuma segurança real porque qualquer cliente que tenha acesso a uma interface específica pode entregá-la diretamente a outro cliente sem nenhuma chamada ao servidor. Além disso, como o COM armazena em cache ponteiros de interface, ele não chama QueryInterface no servidor sempre que um cliente faz uma consulta.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho unknwn.h

Confira também