BATTERY_STATUS

The BATTERY_STATUS structure indicates the state of the battery at the time the operation returns. It is an output from the IOCTL_BATTERY_QUERY_STATUS operation.

typedef struct _BATTERY_STATUS {
  ULONG       PowerState;
  ULONG       Capacity;
  ULONG       Voltage;
  LONG        Rate;
} BATTERY_STATUS, *PBATTERY_STATUS;

Members

PowerState

Indicate the battery state. This member can be zero, one, or more of the following values.

Value	Description
BATTERY_POWER_ON_LINE	Indicates that the system has access to AC power, so no batteries are being discharged.
BATTERY_DISCHARGING	Indicates that the battery is currently discharging.
BATTERY_CHARGING	Indicates that the battery is currently charging.
BATTERY_CRITICAL	Indicates that battery failure is imminent. See the Remarks later in this topic for more information.

Capacity

The current battery capacity in mWh (or relative). This value can be used to generate a "gas gauge" display by dividing it by FullChargedCapacity member of the BATTERY_INFORMATION structure. If the capacity is unavailable, Capacity will contain the value BATTERY_UNKNOWN_CAPACITY.

Voltage

The current battery voltage in millivolts (mv) across the battery terminals. If the voltage is unavailable, this will contain BATTERY_UNKNOWN_VOLTAGE.

Rate

The current rate of battery charge or discharge. This value will be in mW unless the battery is relative, in which case it will be in arbitrary units per hour. To determine if a battery is relative, examine the BATTERY_CAPACITY_ RELATIVE flag in the Capabilities element of the BATTERY_INFORMATION structure. A nonzero positive rate indicates charging; a negative rate indicates discharging. If the rate is unavailable, this will return BATTERY_UNKNOWN_RATE.

Remarks

The BATTERY_CRITICAL flag in the PowerState member of this structure indicates a hardware "battery critical" condition. This critical level is set by the battery manufacturer, not by the user in the "critical battery alarm." It generally means that the battery system has calculated that the battery is totally drained, and any power being drawn is beyond what is expected. If all of the batteries in a system are critical, and no other source of power is available, the system will be shut down automatically.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Batclass.h.

See Also

Device Input and Output Overview, Device Input and Output Structures, DeviceIoControl, IOCTL_BATTERY_QUERY_STATUS