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

La méthode IWbemServices ::CreateInstanceEnumAsync crée un énumérateur qui retourne de manière asynchrone les instances d’une classe spécifiée en fonction de critères de sélection spécifiés par l’utilisateur. Cette méthode prend en charge les requêtes WQL (WMI Query Language) simples. Les requêtes plus complexes peuvent être traitées à l’aide de la méthode IWbemServices ::ExecQueryAsync .

Syntaxe

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

Paramètres

[in] strFilter

BSTR valide contenant le nom de la classe pour laquelle les instances sont souhaitées. Ce paramètre ne peut pas avoir la valeur NULL.

[in] lFlags

Ce paramètre peut prendre les valeurs suivantes.

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 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_DEEP

Cet indicateur force l’énumération à inclure les instances de cette classe et de 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 auprès de Windows Management une demande de réception de rapports de status intermédiaires via l’implémentation cliente d’IWbemObjectSink ::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur modifie le comportement.

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_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 retourne les 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, consultez Passer des appels à WMI.

[in] pResponseHandler

Pointeur vers l’implémentation d’IWbemObjectSink par l’appelant. Ce gestionnaire reçoit les objets dès qu’ils deviennent disponibles. 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. Gestion Windows appelle uniquement AddRef sur le pointeur dans les cas où WBEM_S_NO_ERROR retourne. Dans les cas où un code d’erreur retourne, le nombre de références est le même que lors de l’entrée. Pour plus d’informations, consultez Appel d’une méthode.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique le statut de l'appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.

En cas d’échec, vous pouvez obtenir plus d’informations à 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.

Un fournisseur de instance peut signaler la réussite ou l’échec avec le code de retour de CreateInstanceEnumAsync, ou via un appel à SetStatus effectué via pResponseHandler. Si vous choisissez d’appeler SetStatus, le code de retour envoyé via pResponseHandler est prioritaire.

Si CreateInstanceEnumAsync 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.

Remarques

La méthode IWbemObjectSink ::SetStatus est appelée pour indiquer la fin du jeu de résultats. Il peut également être appelé sans appel intermédiaire à IWbemObjectSink ::Indiquer si des conditions d’erreur se produisent.

É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 semi-synchrone au lieu d’une communication asynchrone.

Pour plus d’informations, consultez IWbemServices ::CreateInstanceEnum et Appel d’une méthode.

Exemples

L’exemple suivant montre comment implémenter CreateInstanceEnumAsync.

#define NUM_OF_INSTANCES 3

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

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

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

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

Dans l’exemple précédent, le fournisseur instance acquiert un thread de WMI pour effectuer toutes les opérations nécessaires. Vous pouvez appeler la méthode AddRef 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. Si le fournisseur choisit ou non la conception d’un thread unique par rapport à la conception à double thread dépend de la durée pendant laquelle le fournisseur prévoit d’utiliser le thread WMI. Il n’existe pas de règles fixes. L’expérimentation peut vous aider à déterminer comment votre conception affecte les performances WMI.

Configuration requise

Voir aussi

Appel d’une méthode

IWbemServices

IWbemServices::CreateInstanceEnum