SWbemServices.InstancesOfAsync method

The InstancesOfAsync method of the SWbemServices object retrieves instances of a specified class according to user-specified criteria.

The method is called in the asynchronous mode. For more information, see Calling a Method.

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

Syntax

SWbemServices.InstancesOfAsync( _
  ByVal ObjWbemSink, _
  ByVal strClass, _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

ObjWbemSink

Object sink that receives the instances asynchronously. Create a SWbemSink object to receive the objects.

strClass

Required. String that contains the name of the class for the instances that you want. This parameter cannot be blank.

iFlags [optional]

Determines the depth of the call enumeration, and whether or not the call returns immediately. This parameter can accept the following values.

wbemQueryFlagShallow (1 (0x1))

Forces the enumeration to include only immediate subclasses of the specified parent class.

wbemQueryFlagDeep (0 (0x0))

Default for this parameter. This value forces the enumeration to include all classes in the hierarchy.

wbemFlagSendStatus (128 (0x80))

Causes asynchronous calls to send status updates to the 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.

wbemFlagUseAmendedQualifiers (131072 (0x20000))

Causes WMI to return class amendment data with the base class definition. For more information, see Localizing WMI Class Information.

objWbemNamedValueSet [optional]

Typically, this 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 context information must document the recognized value names, data type of the value, allowed values, and semantics.

objWbemAsyncContext [optional]

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.

Return value

This method does not return a value. If successful, the sink receives an OnObjectReady event per instance. After the last instance, the object sink receives an OnCompleted event.

Error codes

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

wbemErrAccessDenied - 2147749891 (0x80041003)

Current user does not have the permission to view instances of the specified class.

wbemErrFailed - 2147749889 (0x80041001)

Unspecified error occurred.

wbemErrInvalidClass - 2147749904 (0x80041010)

Specified class is not valid.

wbemErrInvalidParameter - 2147749896 (0x80041008)

A specified parameter is not valid.

wbemErrOutOfMemory - 2147749894 (0x80041006)

Not enough memory to complete the operation.

Remarks

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 returns, create an objWbemSink.OnObjectReady event subroutine. After all the objects are returned, you can perform the 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, see Setting Security on an Asynchronous Call

The InstancesOfAsync method only works for class objects. It is not an error for the returned enumerator to have zero (0) elements.

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_SWbemServices
IID	IID_ISWbemServices

See also

SWbemServices

Calling a Method