SWbemServices.ExecNotificationQuery method

Article
01/07/2021

The ExecNotificationQuery method of the SWbemServices object executes a query to receive events. The call returns immediately. The user can poll the returned enumerator for events as they arrive.

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

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

Syntax

objwbemEventsource = .ExecNotificationQuery( _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ] _
)

Parameters

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]: This is an integer that determines the behavior of the query. The default value is wbemFlagReturnImmediately + wbemFlagForwardOnly. If you specify this parameter, this parameter must be set to both wbemFlagReturnImmediately and wbemFlagForwardOnly or the call fails. This parameter can accept the following values.
wbemFlagForwardOnly (32 (0x20)): Causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but they do not allow calls to SWbemObject.Clone_.
wbemFlagReturnImmediately (16 (0x10)): Causes the call to return immediately.

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

Return value

If no error occurs, this method returns an SWbemEventSource object. You can call the SWbemEventSource.NextEvent method to retrieve events as they arrive.

Error codes

After the completion of the ExecNotificationQuery method, the Err object may contain one of the error codes 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 was specified.
wbemErrInvalidQuery - 2147749911 (0x80041017): Query syntax is not valid.
wbemErrInvalidQueryType - 2147749912 (0x80041018): The requested query language is not supported.
wbemErrOutOfMemory - 2147749894 (0x80041006): Not enough memory to complete the operation.

Remarks

Unlike the SWbemServices.ExecQueryAsync method, ExecNotificationQuery returns event type objects that are generated by future events rather than existing objects. The event objects that ExecNotificationQuery requests can either be intrinsic (such as __InstanceCreationEvent) or extrinsic (such as registry provider events like RegistryKeyChangeEvent or SNMP events). For more information, see Determining the Type of Event to Receive and Receiving Event Notifications.

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 monitors changes to volumes on a local computer. Note that Win32_VolumeChangeEvent is an extrinsic event that is defined by a provider not an intrinsic WMI-defined event. For more information, see Determining the Type of Event to Receive.

Set colMonitoredEvents = _
   GetObject("Winmgmts:").ExecNotificationQuery_
      ("Select * from Win32_VolumeChangeEvent")

Do While i = 0
   Set strLatestEvent = colMonitoredEvents.NextEvent
   Wscript.Echo strLatestEvent.DriveName & "Time Created = " _
      & strLatestEvent.Time_Created

    Select Case strLatestEvent.EventType 
       Case 1        
            WScript.Echo "EventType = Configuration Changed"
       Case 2
            WScript.Echo "EventType = Device Arrival"
       Case 3
            WScript.Echo "EventType = Device Removal"
       Case 4
            WScript.Echo "EventType = Docking"

       Case Else
            WScript.Echo "Unrecognized EventType"
       End Select
Loop

The following VBScript code example monitors process deletion. If you delete a process in Task Manager or close an application, then the script displays a message. Note that this script queries an intrinsic event that is defined by WMI - __InstanceDeletionEvent.

Set objWMIService = GetObject( _
    "Winmgmts:{impersonationLevel=impersonate}" )
Set colMonitoredProcesses = _
    objWMIService.ExecNotificationQuery( _
    "SELECT * FROM __InstanceDeletionEvent WITHIN 10 WHERE " _
    & "TargetInstance ISA 'Win32_Process'")
i = 0
Do While i < 11
    Set strLatestProcess = colMonitoredProcesses.NextEvent
    WScript.Echo strLatestProcess.TargetInstance.Name
    WScript.Sleep 10000
    i= i + 1
Loop

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