Share via

IOCTL_BATTERY_QUERY_INFORMATION控制代码

  • 项目

检索电池的各种信息。

若要执行此操作，请使用以下参数调用 DeviceIoControl 函数。

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

参数

hDevice

要返回信息的电池句柄。 若要检索设备句柄，请调用 CreateFile 函数。

dwIoControlCode

操作的控制代码。 此值标识要执行的特定操作以及要执行该操作的设备类型。 对此操作使用 IOCTL_BATTERY_QUERY_INFORMATION 。

lpInBuffer

指向 BATTERY_QUERY_INFORMATION 结构的指针。

nInBufferSize

输入缓冲区的大小（以字节为单位）。

lpOutBuffer

指向返回缓冲区的指针。 数据类型 (，因此返回缓冲区的大小) 取决于输入BATTERY_QUERY_INFORMATION结构的 BATTERY_QUERY_INFORMATION_LEVEL 成员中请求的信息。

下表显示了给定信息级别返回的数据。

信息级别 返回的数据
BatteryDeviceName 以 Null 结尾的 Unicode 字符串，用于指定电池的名称。
BatteryEstimatedTime 一个 ULONG ，指定估计的电池运行时间（以秒为单位）。 如果 BATTERY_QUERY_INFORMATION 结构的 AtRate 成员中提供的排出速率为零，则此计算基于当前的排出速率。 如果 AtRate 为非零，则返回的时间是给定速率的预期运行时间。 例如，如果估计时间未知 (电池未放电， AtRate) 为零， 则返回BATTERY_UNKNOWN_TIME 。 请注意，此值在某些电池系统上不是非常准确。 值可能因当前电源使用情况而大不相同，这可能会受到磁盘活动和其他因素的影响。 此值中没有更改的通知机制。
BatteryGranularityInformation BATTERY_REPORTING_SCALE 结构的可变 长度数组，其中包含从 IOCTL_BATTERY_QUERY_STATUS返回的电池容量的报告粒度。 当粒度取决于电池的当前容量时，将返回多个条目。 有关条目数组的解释，请参阅 BATTERY_REPORTING_SCALE 。 条目数由返回的缓冲区大小指示，可以按 (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE) ) 进行计算。 将返回的最大条目数为 4。
BatteryInformation BATTERY_INFORMATION结构。
BatteryManufactureDate BATTERY_MANUFACTURE_DATE结构。
BatteryManufactureName 以 Null 结尾的 Unicode 字符串，其中包含电池制造商的名称。
BatterySerialNumber 包含电池序列号的以 Null 结尾的 Unicode 字符串。
BatteryTemperature 包含电池当前温度的 ULONG ，以 10 度开氏度为单位。
BatteryUniqueID 唯一标识电池的以 Null 结尾的 Unicode 字符串。 此值可用于跟踪特定电池。 对于智能电池，此 ID 将是制造商名称、设备名称、制造日期以及序列号的可打印表示形式。 此值不应显示给用户。

nOutBufferSize

输出缓冲区的大小（以字节为单位）。 根据请求的数据的信息级别，这可能是大小可变的缓冲区。

lpBytesReturned

指向变量的指针，该变量接收 lpOutBuffer 缓冲区中返回的数据的大小（以字节为单位）。

如果输出缓冲区太小，无法返回任何数据，则调用将失败， GetLastError将返回错误代码ERROR_INSUFFICIENT_BUFFER，返回的字节计数为零。

如果 lpOverlapped (非重叠 I/O) 为 NULL ， 则 lpBytesReturned 不能为 NULL。

如果 lpOverlapped 不为 NULL (重叠的 I/O) ， 则 lpBytesReturned 可以为 NULL。 如果这是重叠操作，可以通过调用 GetOverlappedResult 函数检索返回的字节数。 如果 hDevice 与 I/O 完成端口相关联，可以通过调用 GetQueuedCompletionStatus 函数来获取返回的字节数。

lpOverlapped

指向 OVERLAPPED 结构的指针。

如果使用 FILE_FLAG_OVERLAPPED 标志打开 hDevice，则 lpOverlapped 必须指向有效的 OVERLAPPED 结构。 在这种情况下， DeviceIoControl 作为重叠 (异步) 操作执行。 如果使用 FILE_FLAG_OVERLAPPED 标志打开设备，并且 lpOverlapped 为 NULL，则该函数以不可预知的方式失败。

如果在未指定FILE_FLAG_OVERLAPPED标志的情况下打开 hDevice，则忽略 lpOverlapped，并且 DeviceIoControl 函数在操作完成或发生错误之前不会返回。

返回值

如果操作成功完成， DeviceIoControl 将返回非零值。

如果操作失败或挂起， DeviceIoControl 返回零。 要获得更多的错误信息，请调用 GetLastError。

有关电池的某些信息是可选的，或者对于某些电池来说可能毫无意义。 如果请求的特定类型的数据不适用于当前电池，则返回 ERROR_INVALID_FUNCTION 。

每当请求的 BatteryTag 元素与当前电池标记的电池标记元素不匹配时，Windows 10版本 1809 及更早版本中) 的所有电池信息请求都将完成状态为ERROR_NO_SUCH_DEVICE (或ERROR_FILE_NOT_FOUND。 这可确保返回的电池信息与所请求的电池信息匹配 (请参阅 电池标记 以获取) 的详细信息。

备注

此电池 IOCTL 检索电池的各种信息。 输入参数结构 （BATTERY_QUERY_INFORMATION）指示要返回的信息的类型以及何时应返回电池信息。 输出缓冲区的数据类型和内容因请求的数据而异。

有关重叠 I/O 对此操作的影响，请参阅 DeviceIoControl 主题的“备注”部分。

示例

有关示例，请参阅 枚举电池设备。

要求

要求 值
最低受支持的客户端
 Windows XP [仅限桌面应用]
最低受支持的服务器
 Windows Server 2003 [仅限桌面应用]
标头
Poclass.h;
Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP 上的 BatClass.h

另请参阅

电池信息

电源管理控制代码

DeviceIoControl

BATTERY_QUERY_INFORMATION

BATTERY_REPORTING_SCALE

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_QUERY_TAG

IOCTL_BATTERY_SET_INFORMATION