BATTERY_WAIT_STATUS

The BATTERY_WAIT_STATUS structure indicates when the battery status is to be collected and returned by the operation. It is an input to the IOCTL_BATTERY_QUERY_STATUS operation.

typedef struct _BATTERY_WAIT_STATUS {
  ULONG       BatteryTag;
  ULONG       Timeout;
  ULONG       PowerState;
  ULONG       LowCapacity;
  ULONG       HighCapacity;
} BATTERY_WAIT_STATUS, *PBATTERY_WAIT_STATUS;

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 DeviceIoControl operation will fail with an error code of ERROR_FILE_NOT_FOUND, which indicates to the caller that the battery for which it has a tag is no longer installed The caller may opt to use the IOCTL_BATTERY_QUERY_TAG operation to determine the tag of the newly installed battery, if any. In addition, if the request is in progress when the battery is removed, or the tag changes, the operation is aborted with the status of ERROR_FILE_NOT_FOUND. (See Battery Tags for more information.)

Timeout

Specifies the number of milliseconds the request will wait for the condition specified by the PowerState, LowCapacity, and HighCapacity elements before completing. A value of -1 indicates that the request will wait indefinitely for the conditions to be satisfied. A value of 0 indicates that the requested battery information is to be returned immediately, regardless of the other conditions. Any other value indicates that the request should wait that length of time, or until any one of the other conditions is satisfied.

If the computer has entered sleep mode, the clock will continue to run, but exhausting the count will not wake the computer up. If the count is exhausted when the computer is awoken, and other conditions are satisfied, the call will return immediately on awakening.

PowerState

This has zero, one, or more of the following status bits on to indicate the state of the battery. It is identical to the PowerState member of the BATTERY_STATUS structure.

Value	Meaning
BATTERY_POWER_ON_LINE	Indicates that the battery has access to AC power.
BATTERY_DISCHARGING	Indicates that the battery is currently discharging.
BATTERY_CHARGING	Indicates that the battery is currently charging.
BATTERY_CRITICAL	Indicates that battery failure is imminent. See the Remarks later in this topic for more information.

LowCapacity

The current battery capacity in mWh (or relative). This value is identical to the Capacity member of the BATTERY_STATUS structure.

HighCapacity

The current battery capacity in mWh (or relative). This value is identical to the Capacity member of the BATTERY_STATUS structure.

Remarks

Requests for battery information are postponed until one of the following occurs:

• The timeout expires (assuming it is not -1)
• The battery's current status does not match PowerState
• The battery's capacity is below LowCapacity
• The battery's capacity is above HighCapacity
• The battery tag changes

When any one of these conditions is satisfied, the data is collected and the operation returns. This allows applications to monitor typical dynamic battery information without polling the device.

Before using either of the two Capacity conditions, make sure the battery supports them by calling the IOCTL_BATTERY_QUERY_STATUS DeviceIoControl operation with a time-out of zero. Examine the results to determine if the Capacity element is supported (that is, not BATTERY_UNKNOWN_CAPACITY).

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_STATUS, IOCTL_BATTERY_QUERY_TAG, Battery Tags