Método IFunctionInstanceQuery::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::CreateInstanceQuery.

Sintaxe

HRESULT Execute(
  [out] IFunctionInstance **ppIFunctionInstance
);

Parâmetros

[out] ppIFunctionInstance

Um ponteiro para um ponteiro de interface IFunctionInstance que recebe a instância de função solicitada.

Retornar valor

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

Valor/código retornado	Descrição
S_OK	O método foi concluído com sucesso.
E_INVALIDARG	O parâmetro ppIFunctionInstance é NULL.
E_OUTOFMEMORY	O método não pode alocar a memória necessária para executar essa operação.
E_PENDING	Os resultados a serem retornados por um provedor virão por meio de notificação assíncrona.
HRESULT_FROM_WIN32(ERROR_OBJECT_NOT_FOUND) 0x800710d8	A instância de função representada pela ID especificada não existe neste computador.
HRESULT_FROM_WIN32(ERROR_KEY_DELETED) 0x800703fa	A instância de função não pôde ser retornada porque a chave correspondente à instância de função foi excluída por outro processo. Esse erro será retornado pelo provedor do Registro se uma chave for excluída enquanto o processamento de consulta estiver ocorrendo.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	A instância de função não pôde ser retornada porque a chave correspondente à instância de função não pôde ser encontrada. Esse erro é retornado pelo provedor do Registro quando o provedor não encontrou instâncias correspondentes para uma consulta de instância.

 

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.

Comentários

Esse método deve ser invocado pelo programa cliente para recuperar dados do objeto de consulta. Quando chamado, esse método executa o seguinte:

1. Recupera a instância da função.
2. 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::CreateInstanceQuery.

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.

Se Execute for chamado duas vezes no mesmo objeto de consulta, a primeira consulta será encerrada antes da segunda consulta ser executada.

Requisitos

Requisito	Valor
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

IFunctionInstanceQuery