SWbemServices.ExecNotificationQueryAsync method

Artykuł
01/07/2021

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

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 asan 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

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