IOCTL_BATTERY_QUERY_TAG控制代码

  • 项目

检索电池的当前标记。

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

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

要从中检索标记的电池句柄。 若要检索设备句柄，请调用 CreateFile 函数。

dwIoControlCode

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

lpInBuffer

指向 ULONG 输入缓冲区的指针。 该值指示如果没有电池，则等待的毫秒数。 值为 -1 表示请求将无限期地等待 (或直到其他事件) 取消。

nInBufferSize

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

lpOutBuffer

指向 ULONG 输出缓冲区的指针。 成功后，此缓冲区包含当前电池标记，可以是除BATTERY_TAG_INVALID以外的任何值。 失败时，如果 GetLastError返回错误代码ERROR_FILE_NOT_FOUND，则此缓冲区包含 值BATTERY_TAG_INVALID。

nOutBufferSize

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

lpBytesReturned

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

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

如果 lpOverlapped 为 NULL (非重叠 I/O) ， 则 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。

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

备注

此电池 IOCTL 检索电池的当前标记。 电池标记是一个唯一的非零值，当物理电池重新插入、更换或发生任何特征更改时，该值会更改。 有关电池标记何时更改、如何检测更改以及应用程序在电池标记更改后应如何继续的详细信息，请参阅 电池信息 概述主题中的电池标记部分。 当电池不存在时，此请求将等待指示的时间，如果仍然没有电池，则会返回 ERROR_FILE_NOT_FOUND 并将电池标记设置为 BATTERY_TAG_INVALID。 (有关详细信息，请参阅电池信息。)

对其他电池信息的所有请求都需要调用方提供匹配的电池标记。 这可确保调用方接收每个请求的同一电池信息，并确保调用方知道电池变化，而无需持续轮询。

有关重叠 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

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_SET_INFORMATION