Export (0) Print
Expand All

SWbemServices.ExecQueryAsync method

The ExecQueryAsync method of the SWbemServices object executes a query to retrieve objects. The call to this method returns immediately, and the results and status are returned to the caller through events delivered to the sink that is specified in objWbemSink. To handle each returned object, create an objWbemSink.OnObjectReady event subroutine.

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

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

Syntax


objWbemObjectSet = .ExecQueryAsync( _
  [ ByVal objWbemSink ], _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objwbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink [optional]

Object sink that executes the query asynchronously. Create an SWbemSink object to receive the objects.

strQuery

Required. String that contains the text of the query. This parameter cannot be blank. For more information on building WMI query strings, see Querying with WQL and the WQL reference.

strQueryLanguage [optional]

String that contains the query language to be used. If specified, the value must be "WQL".

iFlags [optional]

Integer that determines the behavior of the query. This parameter can accept the following values.

ValueMeaning
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.

wbemQueryFlagPrototype
2 (0x2)

Used for a prototype. It stops the query from happening and instead, returns an object that looks like a typical result object.

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 services 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 to make 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 successful, the sink receives an OnObjectReady event per instance. After the last instance, the object sink receives an OnCompleted event.

Error codes

After the completion of the ExecQueryAsync method, the Err object can contain one of the error codes in the following table.

Error (Name/Dec/Hex)Meaning
wbemErrAccessDenied
2147749891 (0x80041003)

Current user does not have the permission to view the result set.

wbemErrFailed
2147749889 (0x80041001)

Unspecified error.

wbemErrInvalidParameter
2147749896 (0x80041008)

Invalid parameter was specified.

wbemErrInvalidQuery
2147749911 (0x80041017)

Query syntax is not valid.

wbemErrInvalidQueryType
2147749912 (0x80041018)

Requested query language is not supported.

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, 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 ExecQueryAsync method returns an empty result set when there are no objects to match the criteria in the query. This method returns key properties whether or not the Key property is requested in the strQuery parameter.

There are limits to the number of AND and OR keywords that can be used in WQL queries. Large numbers of WQL keywords used in a complex query can cause WMI to return the WBEM_E_QUOTA_VIOLATION error code as an HRESULT value. The limit of WQL keywords depends on how complex the query is.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Type library

Wbemdisp.tlb

DLL

Wbemdisp.dll

See also

SWbemServices
Calling a Method
SWbemServices.Get

 

 

Show:
© 2014 Microsoft