Platform SDK: Hardware

IOCTL_BATTERY_QUERY_INFORMATION

Using the IOCTL_BATTERY_QUERY_INFORMATION operation returns a variety of information for the battery.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                // handle to battery
  IOCTL_BATTERY_QUERY_INFORMATION, // dwIoControlCode operation
  (LPVOID) lpInBuffer,             // input buffer
  (DWORD) nInBufferSize,           // size of input buffer
  (LPVOID) lpOutBuffer,            // output buffer
  (DWORD) nOutBufferSize,          // size of output buffer
  (LPDWORD) lpBytesReturned,       // number of bytes returned
  (LPOVERLAPPED) lpOverlapped      // OVERLAPPED structure
);

Parameters

hDevice

[in] Handle to the battery on which information is to be returned. To obtain a device handle, call the CreateFile function.

dwIoControlCode

[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use IOCTL_BATTERY_QUERY_INFORMATION for this operation.

lpInBuffer

[in] Pointer to a BATTERY_QUERY_INFORMATION structure.

nInBufferSize

[in] Size, in bytes, of the input buffer.

lpOutBuffer

[out] Pointer to the return buffer. The data type (and, therefore, size) of the return buffer depends on the information requested in the BATTERY_QUERY_INFORMATION_LEVEL member of the input BATTERY_QUERY_INFORMATION structure.

The following table shows the data returned by a given information level.

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 is 0), BATTERY_UNKNOWN_TIME is returned. Note that this value is not very accurate on some battery systems. The value 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 the date the cell pack was manufactured. The BATTERY_MANUFACTURE_DATE structure is returned.

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 will 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.

nOutBufferSize

[in] Size, in bytes, of the output buffer. Depending on the information level of data requested, this may be a variable-sized buffer.

lpBytesReturned

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 is 0), BATTERY_UNKNOWN_TIME is returned. Note that this value is not very accurate on some battery systems. The value 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 the date the cell pack was manufactured. The BATTERY_MANUFACTURE_DATE structure is returned.
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 will 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.

[out] Pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuffer.

If the output buffer is too small to return any data then the call fails, GetLastError returns the error code ERROR_INSUFFICIENT_BUFFER, and the returned byte count is zero.

If the output buffer is too small to hold all of the data but can hold some entries, then the operating system returns as much as fits, the call fails, GetLastError returns the error code ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data returned. Your application should call DeviceIoControl again with the same operation, specifying a new starting point.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped

[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.

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.

All requests for battery information will complete with the status of ERROR_FILE_NOT_FOUND whenever the BatteryTag element of the request does not match that of the current battery tag. This ensures that the returned battery information matches that of the requested battery. (See Battery Tags for more information.)

Remarks

This battery IOCTL returns a variety of information for the battery. The input parameter structure, BATTERY_QUERY_INFORMATION, indicates the type of information to be returned and when the battery information should be returned. The data type and contents of the output buffer vary based on the data requested.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

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

IOCTL_BATTERY_QUERY_INFORMATION

Parameters

Return Values

Remarks

Requirements

See Also