3.4 Core OS components event providers
3.4 Core OS components event providers
3.4.1 The Clock provider
The Win32 Clock provider is an instance and an event provider. The provider capabilities are summarized in Table 3.34.
| Provider Name | Provider Namespace | Class Provider | Instance Provider | Method Provider | Property Provider | Event Provider | Event Consumer Provider | Support Get | Support Put | Support Enumeration | Support Delete | Windows XP | Windows Server 2003 | Windows 2000 Professional | Windows 2000 Server |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Clock Provider | |||||||||||||||
| Win32ClockProvider | Root/CIMV2 | X | X | X | X | X | X |
As shown in Table 3.35, this provider supports two classes: the Win32_LocalTime and Win32_UTCTime classes.
| Name | Type | Comments |
|---|---|---|
| Win32_LocalTime | Dynamic (Singleton) | Represents an instance of the local time |
| Win32_UTCTime | Dynamic (Singleton) | Represents an instance of the UTC time |
These two classes are created from the Win32_CurrentTime superclass (see Figure 3.18). All classes are singleton classes. There is no particular event class, since the Clock provider works with the __InstanceModificationEvent intrinsic event class.
Figure 3.18: The Win32_CurrentTime class and its child classes.
Because this provider is implemented as an event provider, it is possible to formulate a WQL query without the WITHIN statement. For example, the following query:
Select * From __InstanceModificationEvent Where TargetInstance ISA 'Win32_LocalTime'
will trigger a notification every time the local time changes. We can obtain the same result by performing a WQL event query with the Win32_UTCTime:
Select * From __InstanceModificationEvent Where TargetInstance ISA 'Win32_UTCTime'
Now, if we want to get a notification every new minute for the UTC time, we can use the following query:
Select * From __InstanceModificationEvent Where TargetInstance ISA 'Win32_UTCTime' AND Target Instance.Second=0
In Understanding WMI Scripting, Chapter 6, when we talked about the Timer Events, we saw how to use the interval timer event with its corresponding __IntervalTimerInstruction class. This last WQL event query could represent a good alternative to the interval timer event.
With the help of the Win32_CurrentTime class, it is possible to get the current system time. In the previous chapter, we wrote a script to manage scheduled jobs. This script makes use of the Win32_CurrentTime class, but we didn't examine this part of the code (see Samples 2.56 through 2.59). When we schedule jobs, it is sometimes useful to retrieve the current system time, especially when these jobs are scheduled on a remote computer. Because the Win32_CurrentTime class is a superclass for the Win32_UTCTime and Win32_LocalTime classes, it is possible to retrieve the current time in two forms: UTC and localized.
The portion of code retrieving the system time is shown in Sample 3.32 (lines 275 and 319) and is an extract of Samples 2.56 through 2.59.
Sample 3.32: Getting the current time (UTC and local)
 |
1:<?xml version="1.0"?> .: 8:<package> 9: <job> ..: 13: <runtime> ..: 37: </runtime> 38: 39: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\DecodeDaysOfWeekFunction.vbs" /> 40: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\DecodeDaysOfMonthFunction.vbs" /> 41: 42: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\ConvertStringInArrayFunction.vbs" /> 43: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\DisplayFormattedPropertyFunction.vbs" /> 44: <script language="VBScript" src="/books/2/679/1/html/2/..\Functions\TinyErrorHandler.vbs" /> 45: 46: <object prog reference="true"/> 47: <object prog /> 48: 49: <script language="VBscript"> 50: <![CDATA[ ..: 54: ' ---------------------------------------------------------------------------------------- 55: Const cComputerName = "LocalHost" 56: Const cWMINameSpace = "Root/cimv2" 57: 58: Const cWMIScheduledJobClass = "Win32_ScheduledJob" 59: Const cWMICurrentTimeClass = "Win32_CurrentTime" ..: 94: ' -------------------------------------------------------------------------------- 95: ' Parse the command line parameters 96: If WScript.Arguments.Named.Count = 0 Then 97: WScript.Arguments.ShowUsage() 98: WScript.Quit 99: End If ...: ...: ...: 273: 274: ' TIME ----------------------------------------------------------------------------------- 275: If boolGetTime Then 276: Set objWMIInstances = objWMIServices.InstancesOf (cWMICurrentTimeClass) ...: 279: For Each objWMIInstance in objWMIInstances 280: objWMIDateTime.Year = objWMIInstance.Year 281: objWMIDateTime.YearSpecified = True 282: objWMIDateTime.Month = objWMIInstance.Month 283: objWMIDateTime.MonthSpecified = True 284: objWMIDateTime.Day = objWMIInstance.Day 285: objWMIDateTime.DaySpecified = True 286: 287: objWMIDateTime.Hours = objWMIInstance.Hour 288: objWMIDateTime.HoursSpecified = True 289: objWMIDateTime.Minutes = objWMIInstance.Minute 290: objWMIDateTime.MinutesSpecified = True 291: objWMIDateTime.Seconds = objWMIInstance.Second 292: objWMIDateTime.SecondsSpecified = True 293: 294: objWMIDateTime.IsInterval = False 295: If objWMIInstance.Path_.Class = "Win32_UTCTime" Then 296: WScript.Echo "- UTC " & String (70, "-") 297: WScript.Echo "Current date/time is: " & _ 298: objWMIDateTime.GetVarDate (False) & _ 299: " (" & objWMIDateTime.Value & ")." 300: Else 301: WScript.Echo "- Local " & String (68, "-") 302: WScript.Echo "Current date/time is: " & _ 303: objWMIDateTime.GetVarDate (False) & _ 304: " (" & objWMIDateTime.Value & ")." 305: End If 306: 307: Set objWMIPropertySet = objWMIInstance.Properties_ 308: For Each objWMIProperty In objWMIPropertySet 309: DisplayFormattedProperty objWMIInstance, _ 310: objWMIProperty.Name, _ 311: objWMIProperty.Name, _ 312: Null 313: Next ...: 316: WScript.Echo 317: Next 318: WScript.Echo 319: End If ...: 324: ]]> 325: </script> 326: </job> 327:</package> |
Because we want the script to show the time type (UTC or local), it retrieves the collection available from the Win32_CurrentTime (line 276). This collection is made up of the Win32_UTCTime singleton instance and the Win32_LocalTime singleton instance. Next, it enumerates the collection (lines 279 through 317), and, for each instance found, the script stores the time result in an SWBemDateTime object (lines 280 through 292). Based on the class name of the retrieved time (Win32_LocalTime or Win32_UTCTime at line 295), the script displays the corresponding time message with the class properties. Once executed, we get the following output:
1: C:\>WMIScheduledJob.wsf /GetTime+ 2: Microsoft (R) Windows Script Host Version 5.6 3: Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. 4: 5: - Local - --- --------------------------------------------------------------------------------------------- 6: Current date/time is: 01-11-2001 19:35:54 (20011101193554.000000+000). 7: Day: ..................................... 1 8: DayOfWeek: ............................... 4 9: Hour: .................................... 19 10: Minute: .................................. 35 11: Month: ................................... 11 12: Quarter: ................................. 4 13: Second: .................................. 54 14: WeekInMonth: ............................. 1 15: Year: .................................... 2001 16: 17: - UTC--------------------------------------------------------------------------- 18: Current date/time is: 01-11-2001 18:35:54 (20011101183554.000000+000). 19: Day: ..................................... 1 20: DayOfWeek: ............................... 4 21: Hour: .................................... 18 22: Minute: .................................. 35 23: Month: ................................... 11 24: Quarter: ................................. 4 25: Second: .................................. 54 26: WeekInMonth: ............................. 1 27: Year: .................................... 2001
3.4.2 Power management provider
The power management provider consists of only one event provider (see Table 3.36) supporting one event class.
| Provider Name | Provider Namespace | Class Provider | Instance Provider | Method Provider | Property Provider | Event Provider | Event Consumer Provider | Support Get | Support Put | Support Enumeration | Support Delete | Windows Server 2003 | Windows XP | Windows 2000 Server | Windows 2000 Professional | Windows NT 4.0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Power Management Provider | ||||||||||||||||
| MS_Power_Management_Event_Provider | Root/CIMV2 | X | X | X | X | X | X |
This provider is designed to trigger a WMI event notification to every event consumer who has subscribed to receive power management event notifications. The Win32_PowerManagementEvent class is the only class supported and is an extrinsic event class available in the Root\CIMv2 namespace. This provider is not an instance or property provider and therefore does not expose information about the power devices themselves. To gather information about the power devices, you must refer to the previous chapter (section 2.3.5), and work with one of the following classes: Win32_Battery, Win32_CurrentProbe, Win32_PortableBattery, Win32_UninterruptiblePowerSupply, or Win32_VoltageProbe. The WQL event query to receive all power management events is as follows:
Select * From Win32_PowerManagementEvent
The easiest way to test this WQL event query with a script is to execute Sample 6.17 ("A generic script for asynchronous event notification"), available in the appendix on a laptop. For example, once you have started the script with the following command line, you can switch the laptop to standby mode. Note that if you switch your laptop to hibernate mode, you should obtain the same result. The output would be as follows:
1: C:\>GenericEventAsyncConsumer.wsf "Select * From Win32_PowerManagementEvent' 2: Microsoft (R) Windows Script Host Version 5.6 3: Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. 4: 5: Waiting f for events... 6: 7: BEGIN - OnObjectReady. 8: Tuesday, 20 November, 2001 at 15:41:27: 'Win32_PowerManagementEvent' has been triggered. 9: EventType (wbemCimtypeUint16) = 4 10: OEMEventCode (wbemCimtypeUint16) = (null) 11: END - OnObjectReady. 12: 13: BEGIN - OnObjectReady. 14: Tuesday, 20 November, 2001 at 15:41:56: 'Win32_PowerManagementEvent' has been triggered. 15: EventType (wbemCimtypeUint16) = 18 16: OEMEventCode (wbemCimtypeUint16) = (null) 17: END - OnObjectReady. 18: 19: BEGIN - OnObjectReady. 20: Tuesday, 20 November, 2001 at 15:41:56: 'Win32_PowerManagementEvent' has been triggered. 21: EventType (wbemCimtypeUint16) = 7 22: OEMEventCode (wbemCimtypeUint16) = (null) 23: END - OnObjectReady.
Each time a power management event occurs (lines 7, 13, and 19), the script receives the event represented by a Win32_PowerManagementEvent instance. This class exposes a property called EventType, and its value corresponds to the power management event type (lines 9, 15, and 21). The meaning of the values is shown in Table 3.37.
| Meaning | Values |
|---|---|
| Entering Suspend | 4 |
| Resume from Suspend | 7 |
| Power Status Change | 10 |
| OEM Event | 11 |
| Resume Automatic | 18 |
In the sample output, the OEMEventCode property is always set to Null, because there is no OEM event reported. Note that if you remove the power supply of the laptop, it will switch on the battery and this will trigger power management event 10 ("Power Status Change").
This event type can be useful for applications that must perform specific tasks when the power status of the computer changes.
3.4.3 Shutdown provider
As with the power management provider, the shutdown provider is also made up of one event provider supporting only one single extrinsic event class, which is called Win32_ComputerShutdownEvent (see Table 3.38.)
| Provider Name | Provider Namespace | Class Provider | Instance Provider | Method Provider | Property Provider | Event Provider | Event Consumer Provider | Support Get | Support Put | Support Enumeration | Support Delete | Windows Server 2003 | Windows XP | Windows 2000 Server | Windows 2000 Professional | Windows NT 4.0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Shutdown Provider | ||||||||||||||||
| MS_Shutdown_Event_Provider | Root/CIMV2 | X | X | X |
This event class represents events when a computer has begun the process of shutting down. To receive a computer shutdown notification, the following WQL event query must be used:
Select * From Win32_ComputerShutdownEvent
Again by reusing Sample 6.17 ("A generic script for asynchronous event notification") available in the appendix, we obtain the following output:
1: C:\>GenericEventAsyncConsumer.wsf "Select * From Win32_ComputerShutdownEvent" 2: Microsoft (R) Windows Script Host Version 5.6 3: Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. 4: 5: Waiting for events... 6: 7: BEGIN - OnObjectReady. 8: Tuesday, 20 November, 2001 at 16:46:33: 'Win32_ComputerShutdownEvent' has been triggered. 9: 10: - Win32_ComputerShutdownEvent --------------------------------------------------- 11: MachineName: ........................... NET-DPEN6400A 12: TIME_CREATED: .......................... 20-11-2001 14:44:22 (20011120134422.849164+060) 13: Type: .................................. 0 14: 15: END - OnObjectReady. 16: 17: BEGIN - OnObjectReady. 18: Tuesday, 20 November, 2001 at 16:46:39: 'Win32_ComputerShutdownEvent' has been triggered. 19: 20: - Win32_ComputerShutdownEvent --------------------------------------------- 21: MachineName: ........................... NET-DPEN6400A 22: TIME_CREATED: .......................... 20-11-2001 14:44:28 (20011120134428.717603+060) 23: Type: .................................. 1 24: 25:
The output sample is obtained when a server reboot or shutdown is requested. You will notice two events: the first event (lines 11 through 13) corresponds to a Logoff (value 0 of the type property at line 13); the second event (lines 21 through 23) corresponds to a shutdown or reboot (value 1 of the type property at line 23). From this output, it is interesting to note that this provider notifies any Logoff event to the subscribed consumers in addition to detecting Operating System shutdowns.
As with the power management event, this event type can be useful for an application that must perform some specific tasks when a user logoff or machine shutdown is invoked.
3.4.4 Configuration Change provider
The Configuration Change provider is implemented as an event provider (Table 3.39). Only available under Windows XP or Windows Server 2003, this provider indicates with the Win32_SystemConfigurationChangeEvent extrinsic event class that the device list on the system has been refreshed. This means that a device has been added, removed, or reconfigured.
| Provider Name | Provider Namespace | Class Provider | Instance Provider | Method Provider | Property Provider | Event Provider | Event Consumer Provider | Support Get | Support Put | Support Enumeration | Support Delete | Windows Server 2003 | Windows XP | Windows 2000 Server | Windows 2000 Professional | Windows NT 4.0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Configuration Change Provider | ||||||||||||||||
| SystemConfigurationChangeEvents | Root/CIMV2 | X | X | X |
The Win32_SystemConfigurationChangeEvent event class is the only class supported by the Configuration Change provider. The change to the device list is not contained in the event and therefore an application or a script is required to refresh its knowledge of the device list in order to obtain the current system settings. Configuration changes can be anything related to the system configuration, such as IRQ settings, COM ports, and BIOS version, to name a few. For example, in the previous chapter, we developed a script to retrieve the hardware resource information (see Samples 2.4 through 2.7, "Retrieving hardware resource information"). This script can be easily reused and expanded to determine the updated configuration. The only relevant information contained in the extrinsic event is the event type, which is contained in the EventType property. This property indicates the type of device change notification event that has occurred (Table 3.40).
| Meaning | Values |
|---|---|
| Configuration Changed | 1 |
| Device Arrival | 2 |
| Device Removal | 3 |
| Docking | 4 |
If we reuse Sample 6.17 ("A generic script for asynchronous event notification") in the appendix, and if you connect a USB device to your Windows Server 2003 or Windows XP system, you may get an output similar to the following one:
1: C:\>GenericEventAsyncConsumer.wsf "Select * From Win32_SystemConfigurationChangeEvent' 2: Microsoft (R) Windows Script Host Version 5.6 3: Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. 4: 5: Waiting for events... 6: 7: BEGIN - OnObjectReady. 8: Sunday, 17 Feb, 2002 at 11:01:00: 'Win32_SystemConfigurationChangeEvent' has been triggered. 9: EventType (wbemCimtypeUint16) = 1 10: SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null) 11: TIME_CREATED (wbemCimtypeUint64) = 17-02-2002 10:01:00 (20020217100100.359920+060) 12: 13: END - OnObjectReady. 14: 15: BEGIN - OnObjectReady. 16: Sunday, 17 Feb, 2002 at 11:01:00: 'Win32_SystemConfigurationChangeEvent' has been triggered. 17: EventType (wbemCimtypeUintl6) = 1 18: SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null) 19: TIME_CREATED (wbemCimtypeUint64) = 17-02-2002 10:01:00 (20020217100100.460064+060) 20: 21: END - OnObjectReady.
Based on Table 3.40, we clearly see that the WMI event corresponds to a configuration change (lines 9 and 17).
3.4.5 Volume Change event provider
The Volume Change event provider supports only one extrinsic event class available in the Root\CIMv2 namespace (Table 3.41). Its purpose is to detect the addition or the removal of a drive letter or mounted/dismounted drive on the computer system.
| Provider Name | Provider Namespace | Class Provider | Instance Provider | Method Provider | Property Provider | Event Provider | Event Consumer Provider | Support Get | Support Put | Support Enumeration | Support Delete | Windows Server 2003 | Windows XP | Windows 2000 Server | Windows 2000 Professional | Windows NT 4.0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Volume Change Provider | ||||||||||||||||
| VolumeChangeEvents | Root/CIMV2 | X | X | X |
The Win32_VolumeChangeEvent event class represents a local drive event resulting from the change. Network drives are not currently supported. The Win32_VolumeChangeEvent event class is generally used in a WQL event query:
Select * From Win32_VolumeChangeEvent
If we reuse Sample 6.17 ("A generic script for asynchronous event notification") in the appendix, and if we change the drive letter of volume E: to Z: in a Windows Server 2003 or Windows XP system, we may get an output similar to the following one:
C:\>GenericEventAsyncConsumer.wsf "Select * From Win32_VolumeChangeEvent" Microsoft (R) Windows Script Host Version 5.6 Copyright (C) Microsoft Corporation 1996-2001. All rights reserved. Waiting for events... BEGIN - OnObjectReady. Wednesday, 14 August, 2002 at 17:23:56: 'Win32_VolumeChangeEvent' has been triggered. DriveName (wbemCimtypeString) = E: EventType (wbemCimtypeUintl6) = 3 SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null) TIME_CREATED (wbemCimtypeUint64) = 14-08-2002 15:23:56 (20020814152356.796875+120) END - OnObjectReady. BEGIN - OnObjectReady. Wednesday, 14 August, 2002 at 17:23:57: Win32_VolumeChangeEvent' has been triggered. DriveName (wbemCimtypeString) = Z: EventType (wbemCimtypeUint16) = 2 SECURITY_DESCRIPTOR (wbemCimtypeUint8) = (null) TIME_CREATED (wbemCimtypeUint64) = 14-08-2002 15:23:56 (20020814152356.984375+120) END - OnObjectReady.
The Win32_VolumeChangeEvent class exposes an EventType property. You can refer to Table 3.40 for more information about this property.
EAN: 2147483647
Pages: 82