Power Status

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.

© 1997 by SYBEX Inc. All rights reserved.