IFunctionInstanceCollectionQuery::Execute, méthode (functiondiscoveryapi.h)

[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.]

Exécute la requête définie par IFunctionDiscovery::CreateInstanceCollectionQuery.

Syntaxe

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

Paramètres

[out] ppIFunctionInstanceCollection

Pointeur vers un pointeur d’interface IFunctionInstanceCollection qui reçoit la fonction demandée instance collection.

Valeur retournée

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

Code de retour	Description
S_OK	La commande s'est correctement terminée. Les résultats sont retournés de manière synchrone dans ppIFunctonInstanceCollecton.
E_OUTOFMEMORY	La méthode ne peut pas allouer la mémoire nécessaire pour effectuer cette opération.
E_PENDING	Certains des résultats sont retournés par une notification asynchrone. Pour plus d'informations, consultez les notes.

 

Une requête prédéfinie est une requête d’une catégorie en couches. Lorsqu’une requête prédéfinie est exécutée, chaque fournisseur qui retourne une fonction instance renvoie également une valeur HRESULT. Les valeurs HRESULT du fournisseur sont agrégées, et la valeur retournée par la méthode Execute reflète ces résultats d’agrégation. Les résultats sont agrégés comme suit :

• Si tous les fournisseurs retournent S_OK, Exécuter retourne S_OK.
• Si au moins un fournisseur retourne E_PENDING et que tous les autres fournisseurs retournent S_OK ou E_PENDING, l’exécution retourne E_PENDING.
• Si tous les fournisseurs retournent une valeur d’erreur (autrement dit, une valeur autre que S_OK ou E_PENDING), Execute retourne la valeur d’erreur retournée par le fournisseur réseau qui a été interrogé pour la dernière fois. En outre, si la routine de rappel IFunctionDiscoveryNotification du client a été fournie à IFunctionDiscovery::CreateInstanceCollectionQuery, une notification OnError est envoyée pour chaque fournisseur. Chaque notification OnError contient le HRESULT retourné par le fournisseur.
• Si au moins un fournisseur retourne une valeur d’erreur et que tous les autres fournisseurs retournent S_OK, Execute retourne S_OK. Les notifications OnError sont envoyées comme décrit ci-dessus.
• Si au moins un fournisseur retourne une valeur d’erreur et qu’au moins un fournisseur retourne E_PENDING, Exécuter retourne E_PENDING. Les notifications OnError sont envoyées comme décrit ci-dessus.

Lorsque Execute retourne S_OK, ppIFunctionInstanceCollection contient les résultats de la requête. Si une interface IFunctionDiscoveryNotification est fournie à la méthode CreateInstanceCollectionQuery de IFunctionDiscovery, les modifications apportées aux résultats sont communiquées à l’aide de cette interface.

Lorsque Execute retourne E_PENDING, le jeu de résultats est retourné de manière asynchrone via l’interface IFunctionDiscoveryNotification fournie à la méthode CreateInstanceCollectionQuery de IFunctionDiscovery. ppIFunctionInstanceCollection peut avoir la valeur NULL ou contenir un jeu de résultats partiel. L’énumération est terminée une fois que la méthode OnEvent de IFunctionDiscoveryNotification est appelée avec FD_EVENTID_SEARCHCOMPLETE. Une fois l’événement FD_EVENTID_SEARCHCOMPLETE reçu, des notifications supplémentaires sont mises à jour des résultats.

Notes

Cette méthode doit être appelée par le programme client avant que des données puissent être récupérées à partir de l’objet de requête. Lorsqu’elle est appelée, cette méthode effectue les opérations suivantes :

1. Récupère la fonction instance objet de collection.
2. Interroge le fournisseur de la catégorie qui est passée dans IFunctionDiscovery::CreateInstanceCollectionQuery.
3. Récupère le fournisseur de catégories.
4. Interroge le fournisseur de catégories à l’aide des données de sous-catégorie pour générer la collection à l’aide de contraintes de requête.
5. Lance le mécanisme de notification de mise à jour si l’adresse de la routine de rappel IFunctionDiscoveryNotification du programme client est fournie à IFunctionDiscovery::CreateInstanceCollectionQuery.
6. Met en cache les données de collecte et retourne.

Les fournisseurs de réseau de découverte de fonctions retournent uniquement des instances de fonction via l’interface IFunctionDiscoveryNotification . Ils ne retournent aucune instance de fonction directement lorsque cette méthode est appelée. Au lieu de cela, Execute lance simplement une opération de récupération entièrement asynchrone et retourne E_PENDING pour indiquer que les résultats seront retournés de manière asynchrone. Les notifications doivent être utilisées pour récupérer des instances de fonction à partir de fournisseurs réseau de découverte de fonctions.

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

Requêtes de découverte de fonction

IFunctionInstanceCollectionQuery