Méthode IWbemEventConsumerProvider ::FindConsumer (wbemprov.h)

Article
03/13/2024

La fonction FindConsumer localise et retourne des objets récepteurs auxquels WMI peut envoyer des événements. WMI passe un pointeur vers un objet de consommateur logique, puis FindConsumer localise le consommateur physique associé au consommateur logique. Enfin, FindConsumer retourne à WMI un pointeur vers le récepteur appartenant au consommateur physique. WMI appelle AddRef sur le récepteur et commence à remettre les événements appropriés au récepteur. WMI libère le récepteur après une période configurable sans livraison. Si nécessaire, WMI peut appeler à nouveau FindConsumer pour charger à nouveau le récepteur.

Syntaxe

HRESULT FindConsumer(
  [in]  IWbemClassObject       *pLogicalConsumer,
  [out] IWbemUnboundObjectSink **ppConsumer
);

Paramètres

[in] pLogicalConsumer

Pointeur vers l’objet consommateur logique auquel les objets d’événement doivent être remis.

[out] ppConsumer

Retourne un récepteur d’objet d’événement à Windows Management. Windows Management appelle AddRef pour ce pointeur et remet à ce récepteur les événements associés au consommateur logique. Finalement, après un délai d’attente approprié, Windows Management appelle Release pour le pointeur.

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.

Remarques

Windows Management remet des événements sous la forme d’IWbemClassObject aux consommateurs logiques inscrits dans le schéma. Un fournisseur de consommateurs implémente FindConsumer pour fournir un récepteur d’événements à Windows Management chaque fois que des événements doivent être remis au consommateur logique.

Windows Management reconnaît l’objet consommateur logique et les objets d’événement sont prêts à être remis. Pour remettre un objet d’événement, WMI appelle ensuite FindConsumer. Le fournisseur consommateur doit créer un objet récepteur d’événements (pointeur vers IWbemUnboundObjectSink) et retourner le pointeur vers Windows Management afin que les événements puissent être remis.

À l’aide de cette technique, un seul fournisseur de consommateurs d’événements peut gérer la remise d’événements à de nombreux consommateurs logiques différents en retournant différents pointeurs IWbemUnboundObjectSink pour chacun d’eux.

Vous pouvez implémenter FindConsumer de plusieurs façons :

Fournissez un seul récepteur pour tous les consommateurs logiques.
Cette approche est la plus efficace en termes d’espace, car un seul objet COM est stocké en mémoire. Par exemple, prenons l’exemple d’un fournisseur de consommateurs d’événements qui fournit des récepteurs pour les consommateurs logiques qui journalisent les messages dans des fichiers : le récepteur unique est responsable de l’examen des données incluses avec chaque consommateur logique et de la façon de procéder. Très probablement, chaque événement reçu implique l’ouverture d’un fichier journal, la journalisation du message et la fermeture du fichier. Bien qu’efficace en termes d’espace, cette stratégie implique un temps de traitement important.
Fournissez un récepteur différent pour chaque consommateur logique.
Cette approche optimise les performances en ayant un récepteur dédié prêt à recevoir un événement à mesure que l’événement se produit. Cette stratégie est plus rapide qu’un seul récepteur, mais moins efficace en raison de son coût en termes de mémoire. Étant donné que chaque récepteur conserve son propre fichier journal, le fichier peut toujours être ouvert et prêt à journaliser les messages à mesure que des événements se produisent. Le récepteur peut ensuite fermer le fichier lorsque WMI libère le récepteur après un délai d’attente, ce qui fournit des performances efficaces à la fois dans les scénarios de livraison à grande vitesse et à faible vitesse.
Divisez les consommateurs logiques en groupes et fournissez un récepteur différent pour chaque groupe.
Cette approche fait des compromis entre les performances et l’efficacité. L’approche hybride peut impliquer l’utilisation de quelques fichiers journaux différents, éventuellement avec chacun d’eux lié au type de message à journaliser. Plusieurs objets COM gèrent plusieurs fichiers ouverts. Un fournisseur de consommateurs d’événements suivant cette approche lit le nom du fichier journal pendant l’appel FindConsumer , ouvre le fichier et retourne le récepteur qui journalise tous les messages dans ce fichier. Le fournisseur ferme le fichier lors du dernier appel à la méthode Release . Avec cette approche, le consommateur conserve l’efficacité, car il dispose d’informations sur le fichier à utiliser exactement ; le consommateur n’est pas tenu de rechercher ou d’ouvrir un nouveau fichier. En outre, le consommateur peut économiser de la mémoire en combinant des récepteurs qui enregistrent différents messages dans le même fichier.

Quelle que soit l’approche, votre implémentation doit dépendre de l’existence d’un fournisseur de consommateurs d’événements. WMI libère un fournisseur de consommateurs d’événements une fois qu’un intervalle désigné s’est écoulé entre les appels. Étant donné que WMI a besoin de votre fournisseur de consommateurs d’événements uniquement pour fournir des pointeurs vers des récepteurs pour les nouveaux consommateurs logiques, WMI peut libérer votre fournisseur de consommateurs d’événements après que votre fournisseur a fourni tous les consommateurs logiques en question. Toutefois, les récepteurs doivent rester pour recevoir tous les événements qui se produisent.

Exemples

L’exemple de code suivant décrit une implémentation de FindConsumer. Dans l’implémentation suivante, supposons qu’il existe deux récepteurs pour recevoir des événements, un pour chacun des deux filtres d’événements inscrits différents. Pour déterminer quel récepteur FindConsumer renvoie à WMI, le code examine l’objet consommateur logique entrant.

HRESULT MyEventConsumerClass::FindConsumer(
   /* [in] */ IWbemClassObject __RPC_FAR *pLogicalConsumer,
   /* [out] */ IWbemUnboundObjectSink __RPC_FAR *__RPC_FAR *ppConsumer
   )
{
   // Examine the logical consumer to see which one it is.
   // ====================================================

   VARIANT v;    
   VariantInit(&v);

   HRESULT hRes = WBEM_E_NOT_FOUND;
   *ppConsumer = 0;

   pLogicalConsumer->Get(_bstr_t(L"Name"), 0, &v, 0, 0);

   // Decide which of the two logical consumers to send back.
   // =======================================================

   if (_wcsicmp(V_BSTR(&v), L"Consumer1") == 0)
   {

    //send back the Consumer1 sink to WMI
    // For example:
      /*hRes =  m_pConsumer1->
         QueryInterface(IID_IWbemUnboundObjectSink,
                           (LPVOID*)ppConsumer);*/
   }
   else if (_wcsicmp(V_BSTR(&v), L"Consumer2") == 0)
   {
    //send back the Consumer2 sink to WMI
    // For example:
      /*hRes =  m_pConsumer2->
          QueryInterface(IID_IWbemUnboundObjectSink,
                            (LPVOID*)ppConsumer);*/
   }

   VariantClear(&v);
   return hRes;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wbemprov.h (include Wbemidl.h)
Bibliothèque	Wbemuuid.lib
DLL	Wbemsvc.dll

Voir aussi

IWbemEventConsumerProvider

Réception d’événements en permanence

Réception d’événements pendant la durée de votre application

Partager via