To help applications take advantage of the power management features of portable computers that support these features, Windows 95 supplies two API functions, GetSystemPowerStatus and SetSystemPowerState, that provide information about, and control over, the status of your computer’s power. The PowerStatus class (POWERSTATUS.CLS) provides properties and methods you can use to investigate the computer’s use of power and even to suspend the computer, if it supports that functionality.
Unfortunately, power management features don’t work in Windows NT 4.0 (and many unhappy Windows NT 4.0 users will attest to this). None of the features in the PowerStatus class will work under the most current version of Windows NT. Although the properties don’t fail, they just return 0 in every case. You’ll want to use the properties of the SystemInfo class, covered in the section “Computer and Operating System Information” later in this chapter, to determine the operating system before attempting to use these features in your applications.
Table 9.18 lists all the properties of the PowerStatus class. They’re all read-only, as you’d expect. Because several of the properties return numeric values best represented by constants, we’ve also supplied a series of read-only properties (the best approximation VBA can provide for constants defined in a type library; see Chapter 5 for more information) representing constant return values. These properties are listed in Table 9.19.
Table 9.18: PowerStatus Class Properties
Property | Datatype | Description |
ACLineStatus | Byte | AC power status. One of: 0 (offline, using batteries), 1 (online, plugged in), 255 (unknown) |
BatteryState | Byte | Battery charge status. Any combination of one or more of the following: 1 (High), 2 (Low), 4 (Critical), 128 (No system battery), 255 (Unknown) |
BatteryCharging | Boolean | True or False |
BatteryLifePercent | Byte | Percentage of battery charge remaining from 0–100; 255 if unknown |
BatteryLifeTime | Long | Number of seconds of battery life remaining; –1 if unknown |
BatteryFullLifeTime | Long | Number of seconds of battery life available when the battery is at full charge; –1 if unknown. This estimate is based on the BatteryLifeTime and BatteryLifePercent fields |
Table 9.19: Read-Only Properties (Constants) and Their Associated Properties
Constant | Value | Associated Property |
pwrACLineOffline | 0 | ACLineStatus |
pwrACLineOnline | 1 | |
pwrACLineBackupPower | 2 | |
pwrACLineUnknown | 255 | |
pwrBatteryStateHigh | 1 | BatteryState |
pwrBatteryStateLow | 2 | |
pwrBatteryStateCritical | 4 | |
pwrBatteryStateNoBattery | 128 | |
pwrBatteryStateUnknown | 255 | |
pwrBatteryPercentageUnknown | 255 | BatteryLifePercent |
prwBatteryLifeUnknown | –1 | BatteryLifeTime, BatteryFullLifeTime |
In addition to the items in the two tables, the PowerStatus class includes a single method: Suspend. This method, which requires no parameters, attempts to use the computer’s built-in power management to suspend the computer. Of course, not all computers support this functionality.