| Platform SDK: Hardware |
Batteries can provide power for portable computers and computers running on an uninterruptible power supply (UPS). On these computers, the operating system provides information on the state of the battery so applications can provide useful functions for the user. (Some older nonstandard battery systems and UPSs are not supported.)
Note that this overview assumes you are familiar with device management.
To obtain information about the battery status, use the GetSystemPowerStatus function. This function which returns general information about all power sources in the system. You should use GetSystemPowerStatus whenever possible.
In some cases, however, detailed information about each individual battery is necessary. For this purpose, each battery device exposes an IOCTL interface. These IOCTL operations are performed using the DeviceIoControl function:
IOCTL_BATTERY_QUERY_INFORMATION
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION
To use this interface, an application must follow several steps. First, it must use setup routines to enumerate all devices that have a battery class interface. Note that these devices represent the battery ports, not actual batteries present in the system. The application must then open a handle to each device so it can use DeviceIoControl to send requests to the device, and then acquire tags for any batteries that are inserted. After completing these steps, the application can send queries to each battery device.
To enumerate the battery devices currently on the computer, use the SetupDiGetClassDevs function. The ClassGuid parameter is a pointer to GUID_DEVICE_BATTERY (defined in batclass.h). To enumerate all of the batteries, set the Enumerator parameter to NULL and set the Flags parameter to DIGCF_PRESENT | DIGCF_INTERFACEDEVICE. To obtain the names of the battery devices, use the SetupDiEnumInterfaceDevice and SetupDiGetInterfaceDeviceDetail functions on the data returned. To open a file handle for each of the battery devices, call the CreateFile function with these names .
Because each battery device represents a slot into which a battery can be inserted, there must be a way to determine when the battery is removed or changed. To do this, each battery that is inserted in a particular slot is assigned a tag. This tag must be used for all queries for information. If the tag provided by the application doesn't match the battery, the query fails, indicating to the application that the battery has been removed or changed. Acquire the tag using the IOCTL_BATTERY_QUERY_TAG operation. If a battery is present in that slot, the tag returned can be passed to any of the other battery IOCTLs to perform other functions. If the battery is changed, any further requests using this tag will fail, and a new one must be acquired using the IOCTL_BATTERY_QUERY_TAG operation. Note that this tag is unique for each battery device, not throughout the system.