BATTERY_QUERY_INFORMATION

The BATTERY_QUERY_INFORMATION structure is used by the IOCTL_BATTERY_QUERY_INFORMATION operation to determine the type of information to return.

typedef struct _BATTERY_QUERY_INFORMATION {
  ULONG                           BatteryTag;
  BATTERY_QUERY_INFORMATION_LEVEL InformationLevel;
  LONG                            AtRate;
} BATTERY_QUERY_INFORMATION, *PBATTERY_QUERY_INFORMATION;

Members

BatteryTag

Specifies the current battery tag for the battery. Only information for a battery matching the tag can be returned. Whenever this value does not match the battery's current tag, the IOCTL request will be completed with ERROR_FILE_NOT_FOUND. This indicates to the caller that the battery associated with the tag longer exists. The caller may opt to use the IOCTL_BATTERY_QUERY_TAG operation to determine the tag of the newly installed battery, if one exists. (See Battery Tags for more information.)

When a query information request is made, this value is verified. In addition, if the request is in progress while this value changes, the request is aborted with the status of ERROR_FILE_NOT_FOUND.

InformationLevel

Value that represents the battery information being queried. The data returned by the IOCTL depends on the value of InformationLevel. This will be one of the following values:

Information Level	Return
BatteryDeviceName	Zero ('\0') terminated Unicode (wide) string that contains the battery's name.
BatteryEstimatedTime	ULONG estimated battery run time, in seconds. If the rate of drain provided in the AtRate element of the BATTERY_QUERY_INFORMATION structure is 0, this calculation is based on the present rate of drain. If AtRate is nonzero, the time returned is the expected run time for the given rate. If the estimated time is unknown (for example, the battery is not discharging and the AtRate specified was 0) this will return BATTERY_UNKNOWN_TIME. Note that this value is not very accurate on some battery systems, and may vary widely depending on present power usage, which could be affected by disk activity and other factors. There is no notification mechanism for changes in this value.
BatteryGranularityInformation	An array of BATTERY_REPORTING_SCALE structures, never more than four entries.
BatteryInformation	BATTERY_INFORMATION structure.
BatteryManufactureDate	Returns in the BATTERY_MANUFACTURE_DATE structure the date the cell pack was manufactured.
BatteryManufactureName	Zero ('\0') terminated Unicode (wide) string that contains the name of the manufacturer of the battery.
BatterySerialNumber	Zero ('\0') terminated Unicode (wide) string that contains the battery's serial number.
BatteryTemperature	ULONG that contains the battery's current temperature in 10ths of a degree Kelvin.
BatteryUniqueID	Zero ('\0') terminated Unicode (wide) string that uniquely identifies the battery. This value can be used to track a specific battery. In the case of smart batteries, this ID would be the concatenation of the manufacturer's name, device name, date of manufacture, and a printable representation of the serial number. This value is not intended to be displayed to the end user.

AtRate

This value has meaning only when asking for the BatteryEstimatedTime.

If this value is nonzero, it is a rate of drain that will be used to calculate the time until the battery is discharged for the BatteryEstimatedTime of an individual battery. It must be specified in mW, and must be a negative value to represent a battery discharge rate.

Remarks

Some information about batteries is optional or may be meaningless for some batteries. If the particular type of data requested is not available for the current battery, then ERROR_INVALID_FUNCTION is returned.

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_INFORMATION, IOCTL_BATTERY_QUERY_TAG, BATTERY_REPORTING_SCALE, BATTERY_INFORMATION, BATTERY_MANUFACTURE_DATE