Méthode SWbemServices.ExecMethodAsync
La méthode ExecMethodAsync de l'objet SWbemServices exécute une méthode exportée par un fournisseur de méthodes. L’appel retourne immédiatement au client tandis que les paramètres entrants sont transférés au fournisseur approprié où la méthode s’exécute. Les informations et l'état sont renvoyés à l'appelant par le biais d'événements transmis au puits spécifié dans objWbemSink. Plutôt que Windows Management Instrumentation (WMI), c’est le fournisseur qui implémente la méthode.
La méthode est appelée en mode asynchrone. 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
SWbemServices.ExecMethodAsync( _
ByVal objWbemSink, _
ByVal strObjectPath, _
ByVal strMethodName, _
[ ByVal objWbemInParams ], _
[ ByVal iFlags ], _
[ ByVal objWbemNamedValueSet ], _
[ ByVal objWbemAsyncContext ] _
)
Paramètres
-
objWbemSink
-
Obligatoire. Créez un objet SWbemSink pour recevoir les objets. Récepteur d’objets recevant le résultat de l’appel de méthode. Les paramètres sortants sont envoyés à l’événement SWbemSink.OnObjectReady du récepteur d’objets fourni. Les résultats du mécanisme d’appel sont envoyés à l’événement SWbemSink.OnCompleted du récepteur d’objets fourni. N’oubliez pas que SWbemSink.OnCompleted ne reçoit pas le code de retour de la méthode WMI. Cependant, il reçoit le code de retour du mécanisme de retour d'appel réel et n'est utile que pour vérifier que l'appel a eu lieu ou qu'il a échoué pour des raisons mécaniques. Le code de résultat retourné par la méthode WMI est retourné dans l’objet de paramètre sortant fourni dans SWbemSink.OnObjectReady. Si un code d’erreur est retourné, l’objet IWbemObjectSink fourni n’est pas utilisé. Si l’appel réussit, l’implémentation IWbemObjectSink de l’utilisateur est appelée pour indiquer le résultat de l’opération.
-
strObjectPath
-
Obligatoire. Chaîne contenant le chemin d’accès de l’objet pour lequel la méthode est exécutée. Pour plus d’informations, consultez Description de l’emplacement d’un objet WMI.
-
strMethodName
-
Obligatoire. Nom de la méthode à exécuter.
-
objWbemInParams [facultatif]
-
Il s’agit d’un objet SWbemObject qui contient les paramètres d’entrée de la méthode en cours d’exécution. Par défaut, ce paramètre n’est pas défini. Pour plus d'informations, voir Construction des objets InParameters et Analyse des objets OutParameters.
-
iFlags [facultatif]
-
Entier qui détermine le comportement de l’appel. Ce paramètre peut accepter les valeurs suivantes.
-
wbemFlagSendStatus (128 (0x80))
-
Provoque des appels asynchrones pour envoyer des mises à jour de l’état du récepteur d’objets au gestionnaire d’événements OnProgress.
-
wbemFlagDontSendStatus (0 (0x0))
-
Empêche les appels asynchrones d’envoyer des mises à jour d’état au gestionnaire d’événements OnProgress du récepteur d’objets.
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.
objWbemAsyncContext [facultatif]
Un objet SWbemNamedValueSet qui retourne au récepteur d’objets pour identifier la source de l’appel asynchrone d’origine. Utilisez ce paramètre si vous effectuez plusieurs appels asynchrones à l’aide du même récepteur d’objets. Pour utiliser ce paramètre, créez un objet SWbemNamedValueSet et utilisez la méthode SWbemNamedValueSet.Add pour ajouter une valeur qui identifie l’appel asynchrone que vous effectuez. Cet objet SWbemNamedValueSet est retourné au récepteur de l’objet et la source de l’appel peut être extraite à l’aide de la méthode SWbemNamedValueSet.Item. Pour plus d’informations, consultez Effectuer un appel asynchrone avec VBScript.
Valeur retournée
Cette méthode ne retourne pas de valeur. Si l’appel réussit, un objet OutParameters, qui est également un objet SWbemObject, est fourni au récepteur spécifié dans objWbemSink. L’objet OutParameters retourné contient les paramètres de sortie et la valeur de retour de la méthode en cours d’exécution. Pour plus d'informations, voir Construction des objets InParameters et Analyse des objets OutParameters.
Codes d’erreur
Une fois la méthode ExecMethodAsync terminée, l’objet Err peut contenir l’un des codes d’erreur de la liste suivante.
-
wbemErrFailed - 2147749889 (0x80041001)
-
Erreur non spécifiée.
-
wbemErrInvalidClass - 2147749904 (0x80041010)
-
La classe spécifiée n'est pas valide.
-
wbemErrInvalidParameter - 2147749896 (0x80041008)
-
Un paramètre spécifié n’est pas valide.
-
wbemErrOutOfMemory - 2147749894 (0x80041006)
-
La mémoire disponible est insuffisante pour terminer cette opération.
-
wbemErrInvalidMethod - 2147749934 (0x8004102E)
-
La méthode demandée n’était pas disponible.
-
wbemErrAccessDenied - 2147749891 (0x80041003)
-
L’utilisateur actuel n’était pas autorisé à exécuter la méthode.
Notes
Si la méthode exécutée a des paramètres d’entrée, l’objet InParameters dans le paramètre objWbemInParam doit être identique à la description se trouvant dans les rubriques Construction d’objets InParameters et Analyse des objets OutParameters.
Utilisez SWbemServices.ExecMethodAsync comme alternative à l’accès direct pour l’exécution d’une méthode de fournisseur dans les cas où il n’est pas possible d’exécuter une méthode directement. Par exemple, utilisez-le avec un langage de script qui ne prend pas en charge les paramètres de sortie, c’est-à-dire si votre méthode a des paramètres OUT. Sinon, il est recommandé d’utiliser l’accès direct pour appeler une méthode. Pour plus d’informations, consultez Manipulation des informations sur les classes et les instances.
La méthode SWbemServices.ExecMethodAsync nécessite un chemin d’objet. Si le script contient déjà un objet SWbemObject, vous pouvez appeler SWbemObject.ExecMethodAsync.
Cet appel est retourné immédiatement. Les informations et l'état sont renvoyés à l'appelant par le biais d'événements transmis au récepteur spécifié dans objWbemSink. Pour continuer le traitement une fois l’appel terminé, implémentez une sous-routine pour l’événementobjWbemSink. OnCompleted.
Un rappel asynchrone permet à un utilisateur non authentifié de fournir des données au récepteur. Cela présente des risques de sécurité pour vos scripts et applications. Pour plus d’informations sur la façon d’éliminer les risques, consultez Définition de la sécurité concernant un appel asynchrone.
Utilisez le paramètre objWbemAsyncContext dans les scripts pour vérifier la source d’un appel.
Exemples
L'exemple de code suivant affiche la méthode ExecMethodAsync. Le script crée un objet Win32_Process qui représente un processus exécutant Notepad. Il montre la configuration d’un objet InParameters et comment obtenir les résultats d’un objet OutParameters . Pour un script qui montre les mêmes opérations effectuées de manière synchrone, consultez SWbemServices.ExecMethod. Pour obtenir un exemple d’utilisation de l’accès direct, consultez Créer une méthode dans la classe Win32_Process. Pour obtenir un exemple de la même opération à l’aide de SWbemObject, consultez SWbemObject.ExecMethodAsync.
' Connect to WMI.
set Services = getobject("winmgmts:root\cimv2")
' Obtain the class definition object
' of a Win32_Process object.
Set oProcess = Services.Get("Win32_Process")
' Create the SWbemMethod.InParameters object
' to hold the input parameter required
' for the Win32_Process.Create method call.
' The oProcess.Methods_("Create") call
' obtains a class object that defines
' the correct input parameters
' for the Win32_Process.Create call.
' The InParameters object is an
' SWbemObject object, so SWbemObject.SpawnInstance_
' can be called to create it.
Set oInParams = oProcess.Methods_("Create"). _
InParameters.SpawnInstance_
oInParams.CommandLine = "Notepad.exe"
' Create sink to receive event resulting
' from the ExecMethodAsync call.
set Sink = wscript.CreateObject( _
"WbemScripting.SWbemSink","Sink_")
' Call SWbemServices.ExecMethodAsync
' with the WMI path Win32_Process.
bDone = false
Services.ExecMethodAsync Sink, _
"Win32_Process", "Create", oInParams
' Call the Win32_Process.Create method asynchronously.
' Set up a wait so the results of the method
' execution can be returned to
' the sink subroutines.
while not bDone
wscript.sleep 1000
wend
' Sink subroutines
sub Sink_OnObjectReady(oOutParams, oContext)
wscript.echo "Sink_OnObjectReady subroutine " _
&VBCR & "ReturnValue = " _
& oOutParams.ReturnValue &VBCR & _
"ProcessId = " & oOutParams.ProcessId
end sub
sub Sink_OnCompleted(HResult, LastErrorObj, oContext)
wscript.echo "Sink_OnCompleted subroutine, hresult = " _
& hex(HResult)
bdone = true
end sub
Spécifications
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows Vista |
| Serveur minimal pris en charge |
Windows Server 2008 |
| En-tête |
|
| Bibliothèque de types |
|
| DLL |
|
| CLSID |
CLSID_SWbemServices |
| IID |
IID_ISWbemServices |