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

Voir aussi

IWbemServices

IWbemServices::ExecQueryAsync

Interrogation avec WQL