Método IFunctionInstanceCollectionQuery::Execute (functiondiscoveryapi.h)

[A Descoberta de Funções está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele pode estar alterado ou indisponível em versões subsequentes.]

Executa a consulta definida por IFunctionDiscovery::CreateInstanceCollectionQuery.

Sintaxe

HRESULT Execute(
  [out] IFunctionInstanceCollection **ppIFunctionInstanceCollection
);

Parâmetros

[out] ppIFunctionInstanceCollection

Um ponteiro para um ponteiro de interface IFunctionInstanceCollection que recebe a coleção de instâncias de função solicitada.

Valor retornado

Os possíveis valores retornados incluem, mas não se limitam a, o seguinte.

Código de retorno	Descrição
S_OK	O método foi concluído com sucesso. Os resultados são retornados de forma síncrona em ppIFunctonInstanceCollecton.
E_OUTOFMEMORY	O método não pode alocar a memória necessária para executar essa operação.
E_PENDING	Alguns dos resultados serão retornados por notificação assíncrona. Confira os comentários para obter detalhes.

 

Uma consulta predefinida é uma consulta de uma categoria em camadas. Quando uma consulta predefinida é executada, cada provedor que retorna uma instância de função também retorna um valor HRESULT. Os valores HRESULT do provedor são agregados e o valor retornado pelo método Execute reflete esses resultados agregados. Os resultados são agregados da seguinte maneira:

• Se todos os provedores retornarem S_OK, Execute retornará S_OK.
• Se pelo menos um provedor retornar E_PENDING e todos os outros provedores retornarem S_OK ou E_PENDING, Execute retornará E_PENDING.
• Se todos os provedores retornarem um valor de erro (ou seja, um valor diferente de S_OK ou E_PENDING), Execute retornará o valor de erro retornado pelo provedor de rede que foi consultado pela última vez. Além disso, se a rotina de retorno de chamada IFunctionDiscoveryNotification do cliente tiver sido fornecida a IFunctionDiscovery::CreateInstanceCollectionQuery, uma notificação onError será enviada para cada provedor. Cada notificação onError contém o HRESULT retornado pelo provedor.
• Se pelo menos um provedor retornar um valor de erro e todos os outros provedores retornarem S_OK, Execute retornará S_OK. As notificações onError são enviadas conforme descrito acima.
• Se pelo menos um provedor retornar um valor de erro e pelo menos um provedor retornar E_PENDING, Execute retornará E_PENDING. As notificações onError são enviadas conforme descrito acima.

Quando Execute retorna S_OK, ppIFunctionInstanceCollection contém os resultados da consulta. Se uma interface IFunctionDiscoveryNotification for fornecida ao método CreateInstanceCollectionQuery de IFunctionDiscovery, as alterações nos resultados serão comunicadas usando essa interface.

Quando Execute retornar E_PENDING, o conjunto de resultados será retornado de forma assíncrona por meio da interface IFunctionDiscoveryNotification fornecida ao método CreateInstanceCollectionQuery de IFunctionDiscovery. ppIFunctionInstanceCollection pode ser NULL ou pode conter um conjunto de resultados parcial. A enumeração é concluída depois que o método OnEvent de IFunctionDiscoveryNotification é chamado com FD_EVENTID_SEARCHCOMPLETE. Depois que o evento FD_EVENTID_SEARCHCOMPLETE é recebido, notificações adicionais são atualizações para os resultados.

Comentários

Esse método deve ser invocado pelo programa cliente antes que qualquer dado possa ser recuperado do objeto de consulta. Quando chamado, esse método executa o seguinte:

1. Recupera o objeto de coleção de instâncias de função.
2. Consulta o provedor da categoria que é passada para IFunctionDiscovery::CreateInstanceCollectionQuery.
3. Recupera o provedor de categoria.
4. Consulta o provedor de categoria usando os dados de subcategoria para gerar a coleção usando restrições de consulta.
5. Inicia o mecanismo de notificação de atualização se o endereço da rotina de retorno de chamada IFunctionDiscoveryNotification do programa cliente for fornecido a IFunctionDiscovery::CreateInstanceCollectionQuery.
6. Armazena em cache os dados de coleta e retorna.

Os provedores de rede do Function Discovery retornam apenas instâncias de função por meio da interface IFunctionDiscoveryNotification . Eles não retornam instâncias de função diretamente quando esse método é invocado. Em vez disso, Execute simplesmente inicia uma operação de recuperação totalmente assíncrona e retorna E_PENDING para indicar que os resultados serão retornados de forma assíncrona. As notificações devem ser usadas para recuperar instâncias de função de provedores de rede de Descoberta de Funções.

Requisitos

Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	functiondiscoveryapi.h
DLL	FunDisc.dll

Confira também

Consultas de descoberta de funções

IFunctionInstanceCollectionQuery