SWbemObject.ExecMethodAsync_ method

Artykuł
01/07/2021

The ExecMethodAsync_ method of SWbemObject asynchronously executes a method that a method provider exports. This method is similar to SWbemServices.ExecMethodAsync, but operates directly on the object of the method to be executed. Windows Management Instrumentation (WMI) does not implement this method. The provider implements this method.

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

objOutParams = .ExecMethodAsync_( _
  ByVal objWbemSink, _
  ByVal strMethodName, _
  [ ByVal objwbemInParams ], _
  [ ByVal iFlags ], _
  [ ByVal objwbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink [in]: Required. This is the object sink that receives the results of the method call. The outbound parameters are sent to the SWbemSink.OnObjectReady event of the supplied object sink. The results of the call mechanism are sent to the SWbemSink.OnCompleted event of the supplied object sink. Notice that SWbemSink.OnCompleted does not receive the return code of the method. However, it receives the return code of the actual call-return mechanism, and is only useful for verifying that the call occurred, or that it failed for mechanical reasons. The result code returned from the method is returned in the outbound parameter object supplied to SWbemSink.OnObjectReady. If any error code returns, then the supplied IWbemObjectSink object is not used. If the call is successful, then the user's IWbemObjectSink implementation is called to indicate the result of the operation.
strMethodName [in]: Required. This is the name of the method for the object.
objwbemInParams [in, optional]: This is an SWbemObject object that contains the input parameters for the method being executed. By default, this parameter is undefined. For more information, see Constructing InParameters Objects and Parsing OutParameters Objects.
iFlags [in, optional]: Integer that determines the behavior of the call. This parameter can accept the following values.
wbemFlagSendStatus (128 (0x80)): Causes asynchronous calls to send status updates to the SWbemSink.OnProgress event handler for the object sink.
wbemFlagDontSendStatus (0 (0x0)): Prevents asynchronous calls from sending status updates to the OnProgress event handler for the object sink.

objwbemNamedValueSet [in, optional]

Typically, it is undefined. Otherwise, this is an SWbemNamedValueSet object whose elements represent the context information that can be used by the provider that is servicing the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

objWbemAsyncContext [in, optional]

This is an SWbemNamedValueSet object that returns to the object sink to identify the source of the original asynchronous call. Use this parameter if you are making multiple asynchronous calls using the same object sink. To use this parameter, create an SWbemNamedValueSet object and use the SWbemNamedValueSet.Add method to add a value that identifies the asynchronous call you are making. This SWbemNamedValueSet object is returned to the object sink and the source of the call can be extracted using the SWbemNamedValueSet.Item method. For more information, see Calling a Method.

Return value

This method has no return values. If the call is successful, an OutParameters object, which is also an SWbemObject object, is supplied to the sink specified in objWbemSink. The returned OutParameters object contains the output parameters and return value for the method being executed.

Error codes

After completion of the ExecMethodAsync_ method, the Err object may contain one of the error codes in the following list.

wbemErrFailed - 2147749889 (0x80041001): Unspecified error.
wbemErrInvalidClass - 2147749904 (0x80041010): Specified class was not valid.
wbemErrInvalidParameter - 2147749896 (0x80041008): A specified parameter is not valid.
wbemErrOutOfMemory - 2147749894 (0x80041006): Not enough memory to complete the operation.
wbemErrInvalidMethod - 2147749934 (0x8004102E): Requested method was not available.
wbemErrAccessDenied - 2147749891 (0x80041003): Current user was not authorized to execute the method.

Remarks

Use the SWbemObject.ExecMethodAsync_ method as an alternative to direct access for executing a provider method when you cannot execute a method directly. For example, if your method has out parameters, use the SWbemObject.ExecMethodAsync_ method with a scripting language that does not support output parameters. Otherwise, it is recommended that you invoke a method using direct access. For more information, see Manipulating Class and Instance Information.

This call returns immediately. The requested objects and status are returned to the caller through callbacks delivered to the sink that is specified in objWbemSink. To process each object when it arrives, create an objWbemSink.OnObjectReady event subroutine. After all the objects are returned, you can perform final processing in your implementation of the objWbemSink.OnCompleted event.

An asynchronous callback allows a non-authenticated user to provide data to the sink. This poses security risks to your scripts and applications. To eliminate the risks, use either semisynchronous communication or synchronous communication. For more information, see Calling a Method.

If the method being executed has input parameters, the InParameters object and objWbemInParam parameter must be constructed as described in Constructing InParameters Objects and Parsing OutParameters Objects.

The SWbemObject.ExecMethodAsync_ method assumes the object represented by SWbemObject contains the method to execute. The SWbemServices.ExecMethodAsync method requires an object path.

Examples

The following example shows the ExecMethodAsync method. The script creates a Win32_Process object that represents a process that is running Notepad. It shows setting up of InParameters object, and how to obtain results from an OutParameters object.

For a script that shows the same operations performed synchronously, see SWbemObject.ExecMethod. For an example using direct access, see Create Method in Class Win32_Process. For an example of the same operation using an SWbemServices object, see SWbemServices.ExecMethodAsync.

On Error Resume Next

'Get a Win32_Process class description
Set oProcess = GetObject("winmgmts:Win32_Process")

' Create the SWbemMethod.InParameters object
' to hold the input parameter needed
' 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_

' Specify the name of the process to be run.
oInParams.CommandLine = "Notepad.exe"

' Create a sink to receive event resulting
' from the ExecMethodAsync call.
Set Sink = wscript.CreateObject( _
    "WbemScripting.SWbemSink", "Sink_")

' 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.
bDone = false

' Call SWbemObject.ExecMethodAsync on the oProcess object.
oProcess.ExecMethodAsync_ Sink, "Create", oInParams, 0 
' 
while not bDone
    wscript.sleep 1000
wend

' Sink subroutines
sub Sink_OnObjectReady(oOutParams, oContext)
    wscript.echo "Sink_OnObjectReady subroutine " _
    & VBNewLine & "ReturnValue = " _
    & oOutParams.ReturnValue & VBNewLine & _
    "ProcessId = " & oOutParams.ProcessId
end sub

sub Sink_OnCompleted(HResult, LastErrorObj, oContext)
    wscript.echo "Sink_OnCompleted subroutine, hresult = " _
    & hex(HResult)
    bdone = true
end sub

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Wbemdisp.h
Type library	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemObject
IID	IID_ISWbemObject

Udostępnij za pośrednictwem