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

La méthode IWbemServices::ExecQueryAsync exécute une requête pour récupérer des objets de manière asynchrone.

Syntaxe

HRESULT ExecQueryAsync(
  [in] const BSTR      strQueryLanguage,
  [in] const BSTR      strQuery,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Paramètres

[in] strQueryLanguage

BSTR valide qui contient l’un des langages de requête pris en charge par Windows Management Instrumentation (WMI). Il doit s’agir de « WQL ».

[in] strQuery

BSTR valide qui contient le texte de la requête. Il ne peut pas s’agir de NULL. Lorsque vous implémentez un fournisseur de instance, votre fournisseur peut refuser la requête, car elle est trop complexe. Lorsqu’un fournisseur détermine qu’une requête est trop complexe, WMI peut réessayer le fournisseur avec une requête simple, ou choisir de récupérer et d’énumérer le sur-ensemble des instances de requête.

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 peut prendre les valeurs suivantes.

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_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_SEND_STATUS

Cet indicateur enregistre une demande auprès de WMI pour recevoir des rapports de status intermédiaires via l’implémentation par le client de IWbemObjectSink::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur change.

WBEM_FLAG_ENSURE_LOCATABLE

Cet indicateur garantit que les objets retournés contiennent suffisamment d’informations pour que les propriétés système, telles que __PATH, __RELPATH et __SERVER, ne soient pas NULL.

WBEM_FLAG_PROTOTYPE

Cet indicateur est utilisé pour le prototypage. Elle n’exécute pas la requête, mais retourne 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 tenir compte de sa ou de ses sous-classes parentes.

[in] pCtx

Généralement NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext que le fournisseur peut utiliser pour retourner les classes ou instances 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 IWbemObjectSink par l’appelant. Ce gestionnaire reçoit les objets dans le jeu de résultats de la requête à mesure 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. Windows Management Instrumentation (WMI) appelle IWbemObjectSink::Indicate avec les objets un nombre quelconque de fois, suivi d’un appel unique à IWbemObjectSink::SetStatus pour indiquer la status finale.

WMI appelle uniquement AddRef au pointeur lorsque WBEM_S_NO_ERROR retourne. Lorsqu’un code d’erreur est retourné, le nombre de références est le même que lors de l’entrée. Pour obtenir une explication détaillée des méthodes d’appel asynchrones, 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. La liste suivante répertorie la valeur contenue dans un HRESULT.

En cas d’échec, vous pouvez obtenir des informations à partir de la fonction COM GetErrorInfo.

D’autres codes d’erreur sont retournés au récepteur d’objets spécifié par le paramètre pResponseHandler .

Des codes d’erreur spécifiques à COM peuvent être retournés si des problèmes réseau vous font perdre la connexion à distance à WMI.

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

Remarques

Le nombre de mots-clés 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.

La méthode IWbemObjectSink::Indicate de l’appelant peut être appelée pour signaler les status intermittents. La méthode IWbemObjectSink::SetStatus est appelée pour indiquer la fin du jeu de résultats.

Lorsqu’un fournisseur ne prend pas en charge le traitement des requêtes, WMI peut le prendre en charge. Toutefois, une implémentation de fournisseur de traitement des requêtes est probablement plus efficace que la version WMI. Pour prendre en charge les requêtes, votre fournisseur de instance doit implémenter la méthode ExecQueryAsync. Si un fournisseur prend en charge ExecQueryAsync, WMI envoie une requête SELECT unaire simple directement au fournisseur via le paramètre strQuery et le fournisseur doit analyser la requête et retourner les instances appropriées. Le fournisseur doit analyser la requête, car WMI ne modifie pas la requête, même lorsque la requête est écrite en WQL.

Pour utiliser WMI pour le traitement des requêtes, ne définissez pas la propriété QuerySupportLevels dans votre __InstanceProviderRegistration. Dans ce cas, WMI appelle votre implémentation de CreateInstanceEnumAsync et publie des filtres les résultats afin que l’appelant obtienne uniquement les instances qui répondent aux critères de requête.

L’exemple suivant montre une implémentation de fournisseur de instance standard de ExecQueryAsync. 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::Indique 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 des semi-synchrones au lieu d’une communication asynchrone. Si vous avez besoin d’une communication asynchrone, consultez Appel d’une méthode.

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

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

// Parse the query.
//   You must implement ParseQuery().
    if (!ParseQuery(strQuery))  return WBEM_E_PROVIDER_NOT_CAPABLE;   

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

// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
    int iNumInst = GetNumberInst();

// Now loop through the private source and create each   
// instance which is part of the result set of the query.
    for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
    {
// Prepare an empty object to receive the class definition.
         IWbemClassObject *pNextInst = 0;
         hRes = pClass->SpawnInstance(0, &pNextInst);

// Create the instance.
//   You must implement FillInst().
         /*FillInst(pNextInst, iCnt);*/ 

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

// Clean up memory
    pClass->Release();
  
// Send finish message to WMI.

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

    return hRes;
}

Dans l’exemple précédent, le fournisseur de instance acquiert un thread auprès de WMI pour effectuer les opérations de synchronisation 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.

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
    WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS, 
    WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);

Configuration requise

Voir aussi

Appel d’une méthode

IWbemObjectSink::SetStatus

IWbemServices

IWbemServices::ExecQuery

Interrogation avec WQL