IOCTL_BATTERY_QUERY_TAG control code

Article
01/25/2022

Retrieves the battery's current tag.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to battery
  IOCTL_BATTERY_QUERY_TAG,     // dwIoControlCode
  (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

A handle to the battery from which the tag is to be retrieved. To retrieve a device handle, call the CreateFile function.

dwIoControlCode

The 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_TAG for this operation.

lpInBuffer

A pointer to a ULONG input buffer. The value indicates the number of milliseconds to wait if there is no battery. A value of -1 indicates the request will wait indefinitely (or until canceled by some other event).

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

A pointer to a ULONG output buffer. On success this buffer contains the current battery tag, which can be any value except BATTERY_TAG_INVALID. On failure, if GetLastError returns the error code ERROR_FILE_NOT_FOUND, this buffer contains the value BATTERY_TAG_INVALID.

nOutBufferSize

The size of the output buffer, in bytes.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the lpOutBuffer buffer, in bytes.

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

A 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 value

If the operation completes successfully, DeviceIoControl returns a nonzero value.

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

All requests for battery information will complete with the status of ERROR_NO_SUCH_DEVICE (or ERROR_FILE_NOT_FOUND in Windows 10 version 1809 and earlier) 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 retrieves the battery's current tag. The battery tag is a unique nonzero value that changes when the physical battery is reinserted, replaced, or undergoes any characteristic changes. See the Battery Tags section in the Battery Information overview topic for more detail on when a battery tag changes, how to detect the change, and how an application should proceed after a battery tag change. When a battery is not present, this request will wait the indicated time, and if there is still no battery present, then it will return ERROR_FILE_NOT_FOUND and set the battery tag to BATTERY_TAG_INVALID. (See Battery Information for more information.)

All requests for other battery information require the caller to supply the matching battery tag. This ensures that the caller is receiving information for the same battery for every request and ensures that the caller is aware of battery changes without constant polling.

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

Examples

For an example, see Enumerating Battery Devices.

Requirements

Requirement	Value
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