BATTERY_WAIT_STATUS structure

Contains information about the conditions under which the battery status is to be retrieved. This structure is used by the IOCTL_BATTERY_QUERY_STATUS control code.

Syntax


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

Members

BatteryTag

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

The number of milliseconds the request will wait for the condition specified by the PowerState, LowCapacity, and HighCapacity members before completing. A value of -1 indicates that the request will wait indefinitely for the conditions to be satisfied. A value of zero 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

Zero, one, or more of the following status bits, which indicate the state of the battery. It is identical to the PowerState member of the BATTERY_STATUS structure.

ValueMeaning
BATTERY_CHARGING
0x00000004

Indicates that the battery is currently charging.

BATTERY_CRITICAL
0x00000008

Indicates that battery failure is imminent. See the Remarks section for more information.

BATTERY_DISCHARGING
0x00000002

Indicates that the battery is currently discharging.

BATTERY_POWER_ON_LINE
0x00000001

Indicates that the battery has access to AC power.

 

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 time-out expires (assuming Timeout 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 using the IOCTL_BATTERY_QUERY_STATUS control code with a time-out of zero. Examine the results to determine if the Capacity member is supported (that is, not BATTERY_UNKNOWN_CAPACITY).

Requirements

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

See also

BATTERY_STATUS
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_QUERY_TAG

 

 

Community Additions

ADD
Show:
© 2014 Microsoft