BATTERY_INFORMATION structure

Contains battery information. This structure is returned by the IOCTL_BATTERY_QUERY_INFORMATION control code when the BatteryInformation information level is requested.

Syntax


typedef struct _BATTERY_INFORMATION {
  ULONG Capabilities;
  UCHAR Technology;
  UCHAR Reserved[3];
  UCHAR Chemistry[4];
  ULONG DesignedCapacity;
  ULONG FullChargedCapacity;
  ULONG DefaultAlert1;
  ULONG DefaultAlert2;
  ULONG CriticalBias;
  ULONG CycleCount;
} BATTERY_INFORMATION, *PBATTERY_INFORMATION;

Members

Capabilities

The battery capabilities. This member can be one or more of the following values.

ValueMeaning
BATTERY_CAPACITY_RELATIVE
0x40000000

Indicates that the battery capacity and rate information are relative, and not in any specific units. If this bit is not set, the reporting units are milliwatt-hours (mWh) for capacity and milliwatts (mW) for rate. If this bit is set, all references to units in the other battery documentation can be ignored. All rate information is reported in units per hour. For example, if the fully charged capacity is reported as 100, a rate of 200 indicates that the battery will use all of its capacity in half an hour.

BATTERY_IS_SHORT_TERM
0x20000000

Indicates that the normal operation is for a fail-safe function. If this bit is not set the battery is expected to be used during normal system usage.

BATTERY_SET_CHARGE_SUPPORTED
0x00000001

Indicates that set information requests of the type BatteryCharge are supported by this battery device.

BATTERY_SET_DISCHARGE_SUPPORTED
0x00000002

Indicates that set information requests of the type BatteryDischarge are supported by this battery device.

BATTERY_SYSTEM_BATTERY
0x80000000

Indicates that the battery can provide general power to run the system.

 

Technology

The battery technology. This member can be one of the following values.

ValueMeaning
0

Nonrechargeable battery, for example, alkaline.

1

Rechargeable battery, for example, lead acid.

 

Reserved

Reserved.

Chemistry

An abbreviated character string that indicates the battery's chemistry. This string is not necessarily zero-terminated. The following is a partial list of abbreviations that can be returned and the associated chemistries.

Unicode stringMeaning
PbAc

Lead Acid

LION

Lithium Ion

Li-I

Lithium Ion

NiCd

Nickel Cadmium

NiMH

Nickel Metal Hydride

NiZn

Nickel Zinc

RAM

Rechargeable Alkaline-Manganese

 

Other chemistries may appear in the future and your code should be able to handle them.

DesignedCapacity

The theoretical capacity of the battery when new, in mWh unless BATTERY_CAPACITY_RELATIVE is set. In that case, the units are undefined.

FullChargedCapacity

The battery's current fully charged capacity in mWh (or relative). Compare this value to DesignedCapacity to estimate the battery's wear.

DefaultAlert1

The manufacturer's suggested capacity, in mWh, at which a low battery alert should occur. Definitions of low vary from manufacturer to manufacturer. In general, a warning state will occur before a low state, but you should not assume that it always will. To reduce risk of data loss, this value is usually used as the default setting for the critical battery alarm.

DefaultAlert2

The manufacturer's suggested capacity, in mWh, at which a warning battery alert should occur. Definitions of warning vary from manufacturer to manufacturer. In general, a warning state will occur before a low state, but you should not assume that it always will. To reduce risk of data loss, this value is usually used as the default setting for the low battery alarm.

CriticalBias

A bias from zero, in mWh, which is applied to battery reporting. Some batteries reserve a small charge that is biased out of the battery's capacity values to show "0" as the critical battery level. Critical bias is analogous to setting a fuel gauge to show "empty" when there are several liters of fuel left.

CycleCount

The number of charge/discharge cycles the battery has experienced. This provides a means to determine the battery's wear. If the battery does not support a cycle counter, this member is zero.

Remarks

Generally, a warning state occurs before a low state, but you should not assume it will. It is possible to poll a battery and find that neither alert level has occurred, and poll the battery again and find it discharged to the extent that both levels have been achieved. This may indicate that you are not polling often enough. It may also indicate that the battery is unable to hold a charge for very long and is discharging more rapidly than you expected. Such a battery may be nearing the end of its useful life, or it may be damaged.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Poclass.h;
Batclass.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP

See also

IOCTL_BATTERY_QUERY_INFORMATION

 

 

Community Additions

ADD
Show:
© 2014 Microsoft