Méthode IFunctionDiscovery::GetInstanceCollection (functiondiscoveryapi.h)

Article
08/23/2023

[La découverte de fonctions peut être utilisée dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il peut être modifié ou indisponible dans les versions suivantes.]

Obtient la collection spécifiée d’instances de fonction, en fonction de la catégorie et de la sous-catégorie.

Syntaxe

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

Paramètres

[in] pszCategory

Identificateur de la catégorie à énumérer. Consultez Définitions de catégorie.

[in] pszSubCategory

Identificateur de la sous-catégorie à énumérer. Consultez Définitions de sous-catégorie. Ce paramètre peut être NULL.

[in] fIncludeAllSubCategories

Si la valeur est TRUE, cette méthode énumère de manière récursive toutes les sous-catégories de la catégorie spécifiée dans pszCategory, renvoyant une collection contenant des instances de fonction de toutes les sous-catégories de pszCategory.

Si la valeur est FALSE, cette méthode se limite à retourner des instances de fonction dans la catégorie spécifiée par pszCategory et la sous-catégorie spécifiée par pszSubCategory.

[out] ppIFunctionInstanceCollection

Pointeur vers un pointeur d’interface IFunctionInstanceCollection qui reçoit la fonction instance collection contenant les instances de fonction demandées. La collection est vide si aucune instance de fonction éligible n’est trouvée.

Valeur retournée

Les valeurs de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code/valeur de retour	Description
S_OK	La commande s'est correctement terminée.
E_INVALIDARG	La valeur de pszCategory n’est pas valide. La valeur retournée dans le paramètre ppIFunctionInstanceCollection est NULL.
E_OUTOFMEMORY	La méthode ne peut pas allouer la mémoire nécessaire pour effectuer cette opération.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	La valeur de pszCategory ou pszSubCategory est inconnue.
E_PENDING	L’appel a été exécuté pour un fournisseur qui retourne des résultats de manière asynchrone.

Notes

Certains fournisseurs de découverte de fonctions retournent leurs résultats de requête avec l’interface IFunctionDiscoveryNotification . GetInstanceCollection ne trouve pas les instances de fonction retournées de cette manière et échoue avec E_PENDING. Il est recommandé aux clients d’utiliser la méthode CreateInstanceQuery de l’interface IFunctionDiscovery pour rechercher des instances de fonction pour ces fournisseurs.

Si la méthode réussit, mais qu’aucune instance de fonction correspondant aux paramètres de requête n’a été trouvée, S_OK est retournée et ppFunctionInstanceCollection pointe vers une collection vide (la méthode GetCount de la collection renvoie 0).

Les requêtes de sous-catégorie sont uniquement prises en charge pour les catégories en couches et certaines catégories de fournisseurs. Le fournisseur de registre, le fournisseur d’association PnP-X et le fournisseur de publication prennent en charge les requêtes de sous-catégorie. Les fournisseurs personnalisés peuvent être conçus explicitement pour prendre en charge les requêtes de sous-catégorie. Pour d’autres fournisseurs, les collections instance de fonction peuvent être filtrées à l’aide de contraintes de requête. Pour obtenir la liste des contraintes de requête, consultez Définitions de contraintes.

Exemples

Le code suivant retourne les instances de fonction associées au fournisseur SSDP dans l’espace de noms Microsoft.Networking.Devices.

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

Consultez Contraintes d’interface sur IFunctionInstanceQuery pour filtrer sur plusieurs interfaces à la fois ou pour filtrer sur les fournisseurs qui ne prennent pas en charge les requêtes de sous-catégorie.

Spécifications


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	functiondiscoveryapi.h
DLL	FunDisc.dll

Voir aussi

IFunctionDiscovery

Partager via