Export (0) Print
Expand All

SWbemServices.ExecNotificationQueryAsync method

The ExecNotificationQueryAsync method of the SWbemServices object executes a query to receive events. This call returns immediately and the results and status are returned to the caller through events delivered to the sink that is specified in objWbemSink.

The events that are specified in the query can be intrinsic Windows Management Instrumentation (WMI) events, such as __InstanceCreationEvent, or extrinsic events, such as Win32_IP4RouteTableEvent or RegistryKeyChangeEvent. For more information, see Determining the Type of Event to Receive.

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


SWbemServices.ExecNotificationQueryAsync( _
  ByVal objWbemSink, _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objwbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink

Required. Object sink that receives the notification of events asynchronously. Create a SWbemSink object to receive the objects.

strQuery

Required. String that contains the text of the event-related 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, this value must be "WQL".

iFlags [optional]

Integer that determines the behavior of the query. This parameter can be set to 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.

 

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

objWbemAsyncContext [optional]

This is 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. The 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 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

After the completion of the ExecNotificationQueryAsync method, the Err object may contain one of the error codes identified in the following table.

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

Current user is not authorized to view the result set.

wbemErrFailed
2147749889 (0x80041001)

Unspecified error.

wbemErrInvalidParameter
2147749896 (0x80041008)

Invalid parameter is 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

The ExecNotificationQueryAsync method returns event type objects that future events generate. The event objects that ExecNotificationQueryAsync requests can be intrinsic (for example, __InstanceCreationEvent), or extrinsic (for example, RegistryKeyChangeEvent or SNMP events). For more information, see Determining the Type of Event to Receive.

The call to ExecNotificationQueryAsync 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 is returned, create an objWbemSink.OnObjectReady event subroutine. After all the objects are returned, perform the final processing to implement 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.

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.

Examples

The following VBScript code example shows a script that is waiting for a WMI event notification that indicates that a process has terminated. It is waiting for a WMI intrinsic event, an instance of the event class __InstanceDeletionEvent. The __InstanceDeletionEvent must represent the deletion of an instance of Win32_Process. For more information about WMI intrinsic events, see Determining the Type of Event to Receive.

The following script runs indefinitely until the computer is rebooted, WMI is stopped, or the script is stopped. To stop the script manually, use Task Manager to stop the process. To stop it programmatically, use the Terminate method in the Win32_Process class.


strComputer = "." 
Set objWMIService = GetObject("winmgmts:\\" & _
    strComputer & "\root\CIMV2") 
Set MySink = WScript.CreateObject( _
    "WbemScripting.SWbemSink","SINK_")

objWMIservice.ExecNotificationQueryAsync MySink, _
    "SELECT * FROM __InstanceCreationEvent WITHIN 1 WHERE " _
    & "TargetInstance ISA 'Win32_Process'"

WScript.Echo "Waiting for events..."

While (True)
    Wscript.Sleep(1000)
Wend

Sub SINK_OnObjectReady(objObject, objAsyncContext)
    WScript.Echo "Event occurred."
End Sub

Sub SINK_OnCompleted(objObject, objAsyncContext)
    WScript.Echo "Event call complete."
End Sub

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Type library

Wbemdisp.tlb

DLL

Wbemdisp.dll

See also

SWbemServices
SWbemServices.ExecQuery
SWbemServices.ExecQueryAsync
Registering for System Registry Events
Determining the Type of Event to Receive
Calling a Method
Setting Security on an Asynchronous Call

 

 

Show:
© 2014 Microsoft