Méthode IWbemServices ::ExecNotificationQuery (wbemcli.h)

Article
03/06/2024

La méthode IWbemServices ::ExecNotificationQuery exécute une requête pour recevoir des événements. L’appel est retourné immédiatement et l’utilisateur peut interroger l’énumérateur retourné pour les événements qui arrivent. La libération de l’énumérateur renvoyé annule la requête.

Syntaxe

HRESULT ExecNotificationQuery(
  [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 ne peut pas s’agir de NULL. Actuellement, seul le langage de requête WMI (WQL) est pris en charge.

[in] strQuery

BSTR valide qui contient le texte de la requête liée aux événements. Il ne peut pas s’agir de 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

Ce paramètre doit être défini sur WBEM_FLAG_RETURN_IMMEDIATELY et WBEM_FLAG_FORWARD_ONLY sinon l’appel échoue.

WBEM_FLAG_FORWARD_ONLY

Cet indicateur entraîne le retour d’un énumérateur avant uniquement. Les énumérateurs 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_RETURN_IMMEDIATELY

L’utilisateur doit spécifier cet indicateur ou l’appel échoue. En effet, les événements sont reçus en continu, ce qui signifie que l’utilisateur doit interroger l’énumérateur renvoyé. Le blocage indéfini de cet appel pendant l’attente d’un événement possible bloque le thread pendant une durée indéterminée. Pour plus d’informations, consultez Appel d’une méthode.

[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 événements demandés. 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, ce paramètre 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. L’appelant appelle régulièrement IEnumWbemClassObject ::Next pour voir si des événements sont disponibles. Notez que, dans cette utilisation, Reset ne déplace pas l’énumérateur au début de la séquence d’événements ; elle n’a aucun effet. Le paramètre peut continuer à recevoir des événements jusqu’à ce que Release soit appelé sur l’énumérateur retourné.

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.

Des 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

Le nombre de mots clés AND et OR utilisables dans les requêtes WQL est limité. 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

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wbemcli.h (include 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