Provider::ExecQuery, méthode (provider.h)

Article
08/25/2023

[La classe Provider fait partie de L’infrastructure de fournisseur WMI, qui est maintenant considérée dans l’état final, et aucun développement, amélioration ou mise à jour supplémentaire ne sera disponible pour les problèmes non liés à la sécurité affectant ces bibliothèques. Les API MI doivent être utilisées dans tout nouveau développement.]

La méthode ExecQuery est appelée par WMI pour traiter une requête WQL (WMI Query Language).

Syntaxe

HRESULT ExecQuery(
        MethodContext     *pMethodContext,
  [ref] CFrameworkQuery & cQuery,
        long              lFlags
);

Paramètres

pMethodContext

Pointeur vers l’objet de contexte pour cet appel. Cette valeur contient toutes les propriétés IWbemContext spécifiées par le client. En outre, ce pointeur doit être utilisé comme paramètre pour tous les appels dans WMI.

[ref] cQuery

Pointeur vers une requête qui a déjà été analysée par l’infrastructure du fournisseur.

lFlags

Masque de bits d’indicateurs avec des informations sur l’opération d’exécution de requête. Il s’agit de la valeur spécifiée par le client dans la méthode IWbemServices::ExecQuery .

Les indicateurs suivants sont gérés par (et filtrés) par WMI :

WBEM_FLAG_ENSURE_LOCATABLE
WBEM_FLAG_FORWARD_ONLY
WBEM_FLAG_BIDIRECTIONAL
WBEM_FLAG_USE_AMENDED_QUALIFIERS
WBEM_FLAG_RETURN_IMMEDIATELY
WBEM_FLAG_PROTOTYPE

Valeur retournée

L’implémentation du fournisseur d’infrastructure par défaut de cette méthode retourne WBEM_E_PROVIDER_NOT_CAPABLE à la méthode appelante. La méthode IWbemServices::ExecQuery répertorie les valeurs de retour courantes, bien que vous puissiez choisir de retourner n’importe quel code de retour COM.

Notes

WMI appelle souvent ExecQuery en réponse à un appel client à IWbemServices::ExecQuery, où le client transmet une liste de propriétés sélectionnées ou une clause WHERE. WMI peut également appeler ExecQuery si la requête cliente contient une instruction « ASSOCIATORS OF » ou « REFERENCES OF » décrivant votre classe. Si votre implémentation de ExecQuery retourne WBEM_E_NOT_SUPPORTED, le client s’appuie sur WMI pour gérer la requête.

WMI gère une requête en appelant votre implémentation de CreateInstanceEnum pour fournir toutes les instances. WMI filtre ensuite les instances obtenues avant de retourner les instances au client. Par conséquent, toute implémentation de ExecQuery que vous créez doit être plus efficace que CreateInstanceEnum.

L’exemple suivant décrit une implémentation courante de ExecQuery :

Créez un instance vide de votre classe à l’aide de Provider::CreateNewInstance.
Déterminez le sous-ensemble d’instances que vous devez créer.
Vous pouvez utiliser des méthodes telles que IsPropertyRequired pour voir les propriétés requises et GetValuesForProp pour voir les instances WMI requises. Les autres méthodes qui traitent des propriétés demandées incluent CFrameworkQuery::GetRequiredProperties, CFrameworkQuery::AllPropertiesAreRequired et CFrameworkQuery::KeysOnly.
Renseignez les propriétés du instance vide à l’aide des méthodes Set de la classe CInstance, telles que CInstance::SetByte ou CInstance::SetStringArray.
Renvoyez le instance au client à l’aide de CInstance::Commit.
Retourne les valeurs de retour appropriées.
L’implémentation par défaut du fournisseur de framework ExecQuery retourne WBEM_E_PROVIDER_NOT_CAPABLE. Si vous implémentez ExecQuery, vous devez utiliser les valeurs de retour courantes répertoriées dans IWbemServices::ExecQuery. Si nécessaire, toutefois, vous pouvez retourner n’importe quel code de retour COM.

WMI n’envoie pas de requêtes « ASSOCIATORS OF » ou « REFERENCES OF » aux fournisseurs d’infrastructure. Au lieu de cela, WMI utilise le schéma pour déterminer quelles classes sont liées à la classe en question et génère une requête WQL appropriée pour récupérer les résultats. Par conséquent, vous n’avez pas besoin de coder une prise en charge supplémentaire des requêtes « ASSOCIATORS OF » et « REFERENCES OF ».

Toutefois, vous devez garder à l’esprit ce qui suit lors de l’écriture de votre fournisseur d’infrastructure :

Veillez à prendre en charge les requêtes standard dans votre classe d’association, en particulier les requêtes où les propriétés de référence sont utilisées dans une clause WHERE. Pour plus d’informations, consultez CFrameworkQuery::GetValuesForProp.
Dans votre prise en charge des classes d’association, lorsque vous case activée pour voir si les points de terminaison existent, veillez à utiliser les méthodes CWbemProviderGlue::GetInstanceKeysByPath ou CWbemProviderGlue::GetInstancePropertiesByPath.
Ces méthodes permettent aux points de terminaison d’ignorer le remplissage des propriétés gourmandes en ressources ou inutiles.
Assurez-vous que toutes les classes de point de terminaison d’association prennent en charge les méthodes Get par propriété. Pour plus d’informations, consultez Prise en charge des opérations Partial-Instance. Pour plus d’informations sur le paramètre de requête, consultez CFrameworkQuery.

Spécifications


Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	provider.h (inclure FwCommon.h)
Bibliothèque	FrameDyn.lib
DLL	FrameDynOS.dll; FrameDyn.dll

Partager via