Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

SWbemServices.ExecNotificationQuery method

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.

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.

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

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application 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

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Type library

Wbemdisp.tlb

DLL

Wbemdisp.dll

See also

SWbemEventSource.NextEvent
SWbemServices.ExecQuery
Receiving a WMI Event
Querying with WQL
WQL (SQL for WMI)
Determining the Type of Event to Receive

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.