ExecQueryWmi, fonction
Exécute une requête pour récupérer des objets.
Notes
Cette API est destinée à un usage interne uniquement. Elle n’est pas destinée à être utilisée dans le code du développeur.
Syntaxe
HRESULT ExecQueryWmi (
[in] BSTR strQueryLanguage,
[in] BSTR strQuery,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IEnumWbemClassObject** ppEnum,
[in] DWORD authLevel,
[in] DWORD impLevel,
[in] IWbemServices* pCurrentNamespace,
[in] BSTR strUser,
[in] BSTR strPassword,
[in] BSTR strAuthority
);
Paramètres
strQueryLanguage
[in] Chaîne indiquant le langage de requête valide pris en charge par Windows Management. Il doit s’agir de « WQL », l’acronyme de WMI Query Language.
strQuery
[in] Texte de la requête. Ce paramètre ne peut pas être null.
lFlags
[in] Combinaison d’indicateurs qui affectent le comportement de cette fonction. Les valeurs suivantes sont définies dans le fichier d’en-tête WbemCli.h, ou vous pouvez les définir comme constantes dans votre code :
| Constant | Valeur | Description |
|---|---|---|
WBEM_FLAG_USE_AMENDED_QUALIFIERS |
0x20000 | Si une valeur est définie, la fonction récupère les qualificateurs modifiés qui sont stockés dans l’espace de noms localisé des paramètres régionaux de la connexion actuelle. Si aucune valeur n’est définie, la fonction récupère uniquement les qualificateurs qui sont stockés dans l’espace de noms immédiat. |
WBEM_FLAG_RETURN_IMMEDIATELY |
0x10 | L’indicateur provoque un appel semi-synchrone. |
WBEM_FLAG_FORWARD_ONLY |
0x20 | La fonction renvoie un énumérateur de type avant uniquement. En règle générale, les énumérateurs de ce type sont plus rapides et utilisent moins de mémoire que les énumérateurs conventionnels, mais ils ne permettent pas les appels à Clone. |
WBEM_FLAG_BIDIRECTIONAL |
0 | WMI conserve les pointeurs vers les objets de l’énumération jusqu’à ce qu’ils soient libérés. |
WBEM_FLAG_ENSURE_LOCATABLE |
0x100 | Garantit que tous 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 |
2 | Cet indicateur est utilisé pour le prototypage. Elle n’exécute pas la requête et retourne à la place un objet qui ressemble à un objet de résultat classique. |
WBEM_FLAG_DIRECT_READ |
0x200 | Génère un accès direct au fournisseur pour la classe spécifiée, sans tenir compte de sa classe parente ou de toute sous-classe. |
Pour des performances optimales, les indicateurs recommandés sont WBEM_FLAG_RETURN_IMMEDIATELY et WBEM_FLAG_FORWARD_ONLY.
pCtx
[in] En règle générale, cette valeur est null. Sinon, il s’agit d’un pointeur vers une instance IWbemContext utilisable par le fournisseur des classes demandées.
ppEnum
[out] Si aucune erreur ne se produit, reçoit le pointeur vers l’énumérateur qui permet à l’appelant de récupérer les instances dans le jeu de résultats de la requête. La requête peut avoir un jeu de résultats avec zéro instance. Pour plus d’informations, consultez la section Remarques.
authLevel
[in] Niveau d’autorisation.
impLevel
[in] Niveau d’emprunt d’identité.
pCurrentNamespace
[in] Pointeur vers un objet IWbemServices qui représente l’espace de noms actuel.
strUser
[in] Nom d’utilisateur. Pour plus d’informations, reportez-vous à la fonction ConnectServerWmi.
strPassword
[in] Mot de passe. Pour plus d’informations, reportez-vous à la fonction ConnectServerWmi.
strAuthority
[in] Nom de domaine de l’utilisateur. Pour plus d’informations, reportez-vous à la fonction ConnectServerWmi.
Valeur retournée
Les valeurs suivantes renvoyées par cette fonction sont définies dans le fichier d’en-tête WbemCli.h, ou vous pouvez les définir comme constantes dans votre code :
| Constant | Valeur | Description |
|---|---|---|
WBEM_E_ACCESS_DENIED |
0x80041003 | L’utilisateur n’est pas autorisé à afficher une ou plusieurs des classes que la fonction peut renvoyer. |
WBEM_E_FAILED |
0x80041001 | Une erreur inconnue s’est produite. |
WBEM_E_INVALID_PARAMETER |
0x80041008 | Un paramètre n'est pas valide. |
WBEM_E_INVALID_QUERY |
0x80041017 | La requête comportait une erreur de syntaxe. |
WBEM_E_INVALID_QUERY_TYPE |
0x80041018 | Le langage de la requête demandé n'est pas pris en charge. |
WBEM_E_QUOTA_VIOLATION |
0x8004106c | La requête est trop complexe. |
WBEM_E_OUT_OF_MEMORY |
0x80041006 | La mémoire n'est pas suffisante pour terminer cette opération. |
WBEM_E_SHUTTING_DOWN |
0x80041033 | WMI a probablement été arrêté et est en cours de redémarrage. Appelez de nouveau ConnectServerWmi. |
WBEM_E_TRANSPORT_FAILURE |
0x80041015 | La liaison de l’appel de procédure distante (RPC) entre le processus actuel et WMI a échoué. |
WBEM_E_NOT_FOUND |
0x80041002 | La requête spécifie une classe qui n’existe pas. |
WBEM_S_NO_ERROR |
0 | L’appel de fonction a abouti. |
Notes
Cette fonction enveloppe un appel à la méthode IWbemServices::ExecQuery.
Cette fonction traite la requête spécifiée dans le paramètre strQuery et crée un énumérateur par lequel l’appelant peut accéder aux résultats de la requête. L’énumérateur est un pointeur vers une interface IEnumWbemClassObject ; les résultats de la requête sont des instances d’objets de classe mis à disposition via l’interface IWbemClassObject .
Le nombre de mots clés AND et OR 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 (ou 0x8004106c) comme valeur HRESULT. La limite des mots clés WQL dépend de la complexité de la requête.
Si l’appel de fonction échoue, vous pouvez obtenir des informations supplémentaires sur l’erreur en appelant la fonction GetErrorInfo.
Spécifications
Plateformes : Consultez Configuration requise.
En-tête : WMINet_Utils.idl
Versions de .NET Framework : disponibles depuis la version 4.7.2
