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 [仅限桌面应用] |
| 标头 |
|