Compartilhar via

Método IFunctionDiscovery::GetInstanceCollection (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.]

Obtém a coleção especificada de instâncias de função, com base na categoria e na subcategoria.

Sintaxe

HRESULT GetInstanceCollection(
  [in]  const WCHAR                 *pszCategory,
  [in]  const WCHAR                 *pszSubCategory,
  [in]  BOOL                        fIncludeAllSubCategories,
  [out] IFunctionInstanceCollection **ppIFunctionInstanceCollection
);

Parâmetros

[in] pszCategory

O identificador da categoria a ser enumerada. Consulte Definições de categoria.

[in] pszSubCategory

O identificador da subcategoria a ser enumerada. Consulte Definições de subcategoria. Este parâmetro pode ser NULL.

[in] fIncludeAllSubCategories

Se TRUE, esse método enumera recursivamente todas as subcategorias da categoria especificada em pszCategory, retornando uma coleção que contém instâncias de função de todas as subcategorias de pszCategory.

Se FALSE, esse método se restringe a retornar instâncias de função na categoria especificada por pszCategory e a subcategoria especificada por pszSubCategory.

[out] ppIFunctionInstanceCollection

Um ponteiro para um ponteiro de interface IFunctionInstanceCollection que recebe a coleção de instâncias de função que contém as instâncias de função solicitadas. A coleção estará vazia se nenhuma instância de função qualificada for encontrada.

Valor retornado

Os valores retornados possíveis 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 valor de pszCategory é inválido. O valor retornado no parâmetro ppIFunctionInstanceCollection é NULL.
E_OUTOFMEMORY
 O método não pode alocar a memória necessária para executar essa operação.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
0x80070002
 O valor de pszCategory ou pszSubCategory é desconhecido.
E_PENDING
 A chamada foi executada para um provedor que retorna resultados de forma assíncrona.

Comentários

Alguns provedores de descoberta de funções retornam seus resultados de consulta com a interface IFunctionDiscoveryNotification . GetInstanceCollection não encontra instâncias de função retornadas dessa maneira e falhará com E_PENDING. É recomendável que os clientes usem o método CreateInstanceQuery da interface IFunctionDiscovery para localizar instâncias de função para esses provedores.

Se o método for bem-sucedido, mas nenhuma instância de função tiver sido encontrada que corresponda aos parâmetros de consulta, S_OK será retornado e ppFunctionInstanceCollection apontará para uma coleção vazia (o método GetCount da coleção retornará 0).

As consultas de subcategoria só têm suporte para categorias em camadas e algumas categorias de provedor. O Provedor do Registro, o provedor de associação PnP-X e o provedor de publicação dão suporte a consultas de subcategoria. Provedores personalizados podem ser explicitamente projetados para dar suporte a consultas de subcategoria. Para outros provedores, as coleções de instâncias de função podem ser filtradas usando restrições de consulta. Para obter uma lista de restrições de consulta, consulte Definições de restrição.

Exemplos

O código a seguir retorna as instâncias de função associadas ao provedor SSDP no namespace Microsoft.Networking.Devices.

hr = spDisco->GetInstanceCollection(FCTN_CATEGORY_NETWORKDEVICES,
                                   FCTN_SUBCAT_NETWORKDEVICES_SSDP, 
                                   FALSE, 
                                   &spFunctionInstanceCollection);

Consulte restrições de interface em IFunctionInstanceQuery para filtrar em várias interfaces ao mesmo tempo ou para filtrar provedores que não dão suporte a consultas de subcategoria.

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

IFunctionDiscovery

  • Last updated on