IWbemServices::CreateClassEnumAsync, méthode (wbemcli.h)

Article
08/27/2023

La méthode IWbemServices::CreateClassEnumAsync retourne une énumération de toutes les classes que le fournisseur de classes prend en charge. Le fournisseur de classes crée chaque définition de classe à partir de zéro et retourne uniquement les sous-classes de la classe demandée. En tant que méthode asynchrone, CreateClassEnumAsync retourne immédiatement un message status, puis met à jour le récepteur transmis via le paramètre pResponseHandler, si nécessaire.

Lorsqu’un appel réussit, WMI appelle AddRef sur le pointeur pResponseHandler, retourne immédiatement, puis appelle de façon asynchrone pResponseHandler– >Indique à partir d’un autre thread avec des définitions de classe jusqu’à ce que la requête soit satisfaite.

Syntaxe

HRESULT CreateClassEnumAsync(
  [in] const BSTR      strSuperclass,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Paramètres

[in] strSuperclass

S’il n’est pas NULL ou vide, ce paramètre spécifie un nom de classe parent. Seules les classes qui sont des sous-classes de cette classe sont retournées dans l’énumérateur. Si null ou vide et lFlags est WBEM_FLAG_SHALLOW, seules les classes de niveau supérieur (celles qui n’ont pas de classe parente) sont retournées. S’il est NULL ou vide et que lFlags est WBEM_FLAG_DEEP, toutes les classes de l’espace de noms sont retournées.

[in] lFlags

Une ou plusieurs des valeurs suivantes sont valides.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si cet indicateur est défini, Windows Management Instrumentation (WMI) récupère les qualificateurs modifiés stockés dans l’espace de noms localisé des paramètres régionaux de connexion actuels. 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_BIDIRECTIONAL

Cet indicateur oblige WMI à conserver les pointeurs vers les objets de l’énumération jusqu’à ce que le client libère l’énumérateur.

WBEM_FLAG_DEEP

Cet indicateur force l’énumération à inclure ceci et toutes les sous-classes dans la hiérarchie.

WBEM_FLAG_SHALLOW

Cet indicateur force l’énumération à inclure uniquement les instances pures de cette classe, à l’exclusion de toutes les instances de sous-classes qui fournissent des propriétés introuvables dans cette classe.

WBEM_FLAG_SEND_STATUS

Cet indicateur inscrit une demande dans WMI pour recevoir des rapports status intermédiaires via l’implémentation cliente de IWbemObjectSink::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur modifie le comportement.

Note Si strSuperclass a la valeur NULL ou vide et que WBEM_FLAG_DEEP est spécifié, toutes les classes sont retournées.

[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 retourne les classes demandées. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation du fournisseur. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.

[in] pResponseHandler

Pointeur vers l’implémentation de l’appelant de IWbemObjectSink. Ce gestionnaire reçoit les objets à mesure qu’ils deviennent disponibles à l’aide de la méthode IWbemObjectSink::Indicate . Quand aucun objet n’est disponible, la méthode IWbemObjectSink::SetStatus est appelée par WMI. Si un code d’erreur est retourné, le pointeur IWbemObjectSink fourni n’est pas utilisé. Si WBEM_S_NO_ERROR est retourné, l’implémentation IWbemObjectSink de l’utilisateur est appelée pour indiquer le résultat de l’opération. WMI appelle uniquement AddRef sur le pointeur lorsque WBEM_S_NO_ERROR retourne. Lorsqu’un code d’erreur est retourné, le nombre de références est identique à aucune entrée. Pour obtenir une explication détaillée de ce paramètre, consultez Appel d’une méthode.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique l’état de l’appel de méthode. En cas d’échec, vous pouvez obtenir les informations disponibles à partir de la fonction COM GetErrorInfo. Les codes d’erreur spécifiques à COM peuvent être retournés si des problèmes réseau vous font perdre la connexion à distance à WMI. Notez que si CreateClassEnumAsync retourne WBEM_S_NO_ERROR, WMI attend un résultat de la méthode SetStatus du gestionnaire de réponses. WMI attend indéfiniment sur une connexion locale ou jusqu’à ce qu’un délai d’expiration de connexion à distance se produise. La liste suivante répertorie la valeur contenue dans un HRESULT.

Remarques

Étant donné que le rappel peut ne pas être retourné au même niveau d’authentification que celui requis par le client, il est recommandé d’utiliser des données semi-synchronisées au lieu d’une communication asynchrone. Si vous avez besoin d’une communication asynchrone, consultez Appel d’une méthode.

Pour plus d’informations sur l’utilisation semi-synchrone des méthodes, consultez IWbemServices::CreateClassEnum et Appel d’une méthode.

Exemples

L’exemple de code suivant montre comment implémenter CreateClassEnumAsync.

HRESULT CStdProvider::CreateClassEnumAsync( 
            /* [in] */ BSTR strSuperclass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0;

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

        // Deliver the class to WMI.
        pResponseHandler->Indicate(1, &pNextClass);
        pNextClass->Release( );

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

Dans l’exemple précédent, le fournisseur de classes acquiert un thread à partir de WMI pour effectuer les opérations nécessaires. Vous pouvez appeler la méthode AddRef du récepteur et créer un autre thread pour remettre les objets dans le jeu de résultats. La création d’un autre thread permet au thread actuel de revenir à WMI sans épuiser le pool de threads. Le choix par le fournisseur de la conception d’un thread unique ou de la conception à deux threads dépend de la durée pendant laquelle le fournisseur prévoit d’utiliser le thread WMI. Il n’existe aucune règle fixe. L’expérimentation peut vous aider à déterminer comment votre conception affecte les performances WMI.

Configuration requise


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