SWbemServices.ExecQuery, méthode

Article
06/29/2023

La méthode ExecQuery de l’objet SWbemServices exécute une requête pour récupérer des objets. Ces objets sont accessibles via la collection SWbemObjectSet retournée.

Cette méthode est appelée en mode semi-synchrone. Pour plus d’informations, consultez Appel d’une méthode.

Pour obtenir une explication de cette syntaxe, consultez Conventions de document pour l’API de script.

Syntaxe

objWbemObjectSet = .ExecQuery( _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ] _
)

Paramètres

strQuery: Obligatoire. Chaîne qui contient le texte de la requête. Ce paramètre ne peut pas être vide. 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.
strQueryLanguage [facultatif]: Chaîne qui contient le langage de requête à utiliser. Si elle est spécifiée, la valeur doit être « WQL ».
iFlags [facultatif]: Entier qui détermine le comportement de la requête et si cet appel est suivi d’un retour immédiat. La valeur par défaut de ce paramètre est wbemFlagReturnImmediately. Ce paramètre peut accepter les valeurs suivantes.
wbemFlagForwardOnly (32 (0x20)): Provoque le retour d’un énumérateur uniquement vers l’avant. Les énumérateurs de ce type sont généralement beaucoup plus rapides et utilisent moins de mémoire que les énumérateurs conventionnels, mais ils ne permettent pas les appels à SWbemObject.Clone_.
wbemFlagBidirectional (0 (0x0)): Permet à WMI de conserver les pointeurs vers les objets de l’énumération jusqu’à ce que le client libère l’énumérateur.
wbemFlagReturnImmediately (16 (0x10)): Provoque le retour immédiat de l’appel.
wbemFlagReturnWhenComplete (0 (0x0)): Entraîne le blocage de cet appel jusqu’à ce que la requête soit terminée. Cet indicateur appelle la méthode en mode synchrone.
wbemQueryFlagPrototype (2 (0x2)): Utilisé pour le prototypage. Cet indicateur empêche la requête de s’exécuter et retourne un objet qui ressemble à un objet de résultat classique.
wbemFlagUseAmendedQualifiers (131072 (0x20000)): Permet à WMI de retourner des données de modification de classe avec la définition de classe de base. Pour plus d’informations, consultez Localisation des informations de classe WMI.

objWbemNamedValueSet [facultatif]

En règle générale, ceci n’est pas défini. Sinon, il s’agit d’un objet SWbemNamedValueSet dont les éléments représentent les informations de contexte qui peuvent être utilisées par le fournisseur répondant à la demande. Un fournisseur qui prend en charge ou requiert de telles informations doit documenter les noms de valeur reconnus, le type de données de la valeur, les valeurs autorisées et la sémantique.

Valeur retournée

Si aucune erreur ne se produit, cette méthode retourne un objet SWbemObjectSet. Il s’agit d’une collection d’objets qui contient le jeu de résultats de la requête. L’appelant peut examiner la collection en utilisant l’implémentation de collections pour le langage de programmation que vous utilisez. Pour plus d’informations, consultez Accès à une collection.

Codes d’erreur

Une fois la méthode ExecQuery terminée, l’objet Err peut contenir l’un des codes d’erreur de la liste suivante.

wbemErrAccessDenied - 2147749891 (0x80041003): L’utilisateur actuel n’a pas l’autorisation nécessaire pour afficher le jeu de résultats.
wbemErrFailed - 2147749889 (0x80041001): Erreur non spécifiée.
wbemErrInvalidParameter - 2147749896 (0x80041008): Un paramètre non valide a été spécifié.
wbemErrInvalidQuery - 2147749911 (0x80041017): La syntaxe de requête n’est pas valide.
wbemErrInvalidQueryType - 2147749912 (0x80041018): Le langage de requête demandé n’est pas pris en charge.
wbemErrOutOfMemory - 2147749894 (0x80041006): La mémoire disponible est insuffisante pour terminer cette opération.

Notes

ExecQuery est l’un des appels les plus couramment utilisés pour récupérer des informations WMI. Un appel standard à ExecQuery se présente comme suit :

strComputer = "."
Set objWMIService = GetObject("winmgmts:" & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

Set colServices = objWMIService.ExecQuery ("Select * from Win32_Service where Name='Alerter'")
For Each objService in colServices
    Return = objService.StopService()
    If Return <> 0 Then
        Wscript.Echo "Failed " &VBNewLine & "Error code = " & Return 
    Else
       WScript.Echo "Succeeded"
    End If
Next

Notez que l’objet SWbemServices est créé avec un moniker qui représente l’espace de noms et la sécurité appropriés, et que l’appel ExecQuery est passé via le service. Pour plus d’informations, consultez Création d’un script WMI et Énumération de WMI.

Comme la méthode InstancesOf, la méthode ExecQuery retourne toujours une collection SWbemObjectSet. Par conséquent, votre script WMI doit énumérer la collection retournée par ExecQuery afin d’accéder à chaque instance de ressource managée de la collection, comme le montre cet exemple :

strComputer = "."
Set objSWbemServices = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colSWbemObjectSet = objSWbemServices.ExecQuery _
   ("SELECT * FROM Win32_Service")
For Each objSWbemObject In colSWbemObjectSet
    Wscript.Echo "Name: " & objSWbemObject.Name
Next

Parmi les autres méthodes SWbemServices qui retournent un SWbemObjectSet figurent AssociatorsOf, ReferencesTo et SubclassesOf.

Il ne s’agit pas d’une erreur si la requête retourne un jeu de résultats vide. La méthode ExecQuery retourne les propriétés de clé, que la propriété de clé soit demandée ou non dans l’argument strQuery. Si une erreur se produit pendant l’exécution de cette méthode et que vous n’utilisez pas l’indicateur wbemFlagReturnImmediately, l’objet Err n’est pas défini tant que vous n’avez pas tenté d’accéder au jeu d’objets retourné. Cependant, si vous utilisez l’indicateur wbemFlagReturnWhenComplete, l’objet Err est défini quand la méthode ExecQuery est appelée.

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 à retourner 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.

Exemples

L’exemple de code VBScript suivant localise tous les lecteurs de disque sur l’ordinateur local et affiche l’ID de l’appareil et le type du lecteur de disque.

Set colDisks = GetObject( _
    "Winmgmts:").ExecQuery("Select * from Win32_LogicalDisk")
For Each objDisk in colDisks
 
    Select Case objDisk.DriveType
        Case 1
            Wscript.Echo "No root directory. Drive type could not be determined."
        Case 2
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Removable drive" 
        Case 3
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Local hard disk" 
        Case 4
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Network disk" 
        Case 5
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Compact disk" 
        Case 6
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = RAM disk" 
        Case Else
            Wscript.Echo "Drive type could not be determined."
    End Select
Next

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
En-tête	Wbemdisp.h
Bibliothèque de types	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemServices
IID	IID_ISWbemServices

Voir aussi

SWbemServices
SWbemServices.Get
Interrogation avec WQL
Création d’un script WMI
Énumération de WMI

Share via