Méthode IWbemServices::ExecQuery (wbemcli.h)
La méthode IWbemServices::ExecQuery exécute une requête pour récupérer des objets.
Pour connaître les types de requêtes valides qui peuvent être effectuées, consultez Interrogation avec WQL.
Syntaxe
HRESULT ExecQuery(
[in] const BSTR strQueryLanguage,
[in] const BSTR strQuery,
[in] long lFlags,
[in] IWbemContext *pCtx,
[out] IEnumWbemClassObject **ppEnum
);
Paramètres
[in] strQueryLanguage
BSTR valide qui contient l’un des langages de requête pris en charge par Windows Management. Il doit s’agir de « WQL », l’acronyme du langage de requête WMI.
[in] strQuery
BSTR valide qui contient le texte de la requête. Ce paramètre ne peut pas avoir la valeur NULL. Pour plus d’informations sur la création de chaînes de requête WMI, consultez Interrogation avec WQL et les informations de référence sur WQL.
[in] lFlags
Les indicateurs suivants affectent le comportement de cette méthode. La valeur suggérée pour ce paramètre est WBEM_FLAG_RETURN_IMMEDIATELY et WBEM_FLAG_FORWARD_ONLY pour de meilleures performances.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Si cet indicateur est défini, WMI récupère les qualificateurs modifiés stockés dans l’espace de noms localisé des paramètres régionaux de la connexion actuelle. S’il n’est pas défini, seuls les qualificateurs stockés dans l’espace de noms immédiat sont récupérés.
WBEM_FLAG_FORWARD_ONLY
Cet indicateur entraîne le retour d’un énumérateur avant uniquement. Les énumérateurs vers l’avant uniquement sont généralement beaucoup plus rapides et utilisent moins de mémoire que les énumérateurs conventionnels, mais n’autorisent pas les appels à cloner ou réinitialiser.
WBEM_FLAG_BIDIRECTIONAL
Cet indicateur permet à Gestion Windows de conserver les pointeurs vers les objets de l’énumération jusqu’à ce que le client libère l’énumérateur.
WBEM_FLAG_RETURN_IMMEDIATELY
Cet indicateur fait qu’il s’agit d’un appel semi-synchronisé. Pour plus d’informations, consultez Appel d’une méthode.
WBEM_FLAG_ENSURE_LOCATABLE
Cet indicateur garantit que tous les objets retournés contiennent suffisamment d’informations pour que les propriétés système, telles que __PATH, __RELPATH et __SERVER, soient non NULL.
WBEM_FLAG_PROTOTYPE
Cet indicateur est utilisé pour le prototypage. Elle n’exécute pas la requête et retourne à la place un objet qui ressemble à un objet de résultat classique.
WBEM_FLAG_DIRECT_READ
Cet indicateur entraîne un accès direct au fournisseur pour la classe spécifiée sans égard à sa ou ses sous-classes parentes.
[in] pCtx
Généralement NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext qui peut être utilisé par le fournisseur qui fournit les classes ou instances demandées. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation du fournisseur en question. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.
[out] ppEnum
Si aucune erreur ne se produit, cela reçoit l’énumérateur qui permet à l’appelant de récupérer les instances dans le jeu de résultats de la requête. Ce n’est pas une erreur pour que la requête ait un jeu de résultats avec 0 instances. Cela est déterminé uniquement en tentant d’itérer à travers les instances. Cet objet retourne avec un nombre de références positif. L’appelant doit appeler Release lorsque l’objet n’est plus requis.
Valeur retournée
Cette méthode retourne une valeur HRESULT qui indique l’état de l’appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.
En cas d’échec, vous pouvez obtenir toutes les informations disponibles à partir de la fonction COM GetErrorInfo.
Les codes d’erreur spécifiques à COM peuvent également être retournés si des problèmes réseau vous font perdre la connexion à distance à Windows Management.
Remarques
La méthode IWbemServices::ExecQuery traite la requête spécifiée dans le paramètre strQuery et crée un énumérateur par lequel l’appelant peut accéder aux résultats de la requête. L’énumérateur est un pointeur vers une interface IEnumWbemClassObject ; les résultats de la requête sont des instances d’objets de classe mis à disposition via l’interface IWbemClassObject .
Il existe des limites au nombre de mots clés « AND » et « OR » qui peuvent être utilisés dans les requêtes WQL. La présence d’un grand nombre de mots clés WQL dans une requête complexe peut amener WMI à renvoyer le code d’erreur WBEM_E_QUOTA_VIOLATION comme valeur HRESULT. La limite des mots clés WQL dépend de la complexité de la requête.
Spécifications
| Client minimal pris en charge | Windows Vista |
| Serveur minimal pris en charge | Windows Server 2008 |
| Plateforme cible | Windows |
| En-tête | wbemcli.h (inclure Wbemidl.h) |
| Bibliothèque | Wbemuuid.lib |
| DLL | Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll |