код элемента управления IOCTL_BATTERY_QUERY_INFORMATION

Статья
06/12/2023

Извлекает различные сведения для батареи.

Для выполнения этой операции вызовите функцию 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_LEVEL структуры входных BATTERY_QUERY_INFORMATION .

В следующей таблице показаны данные, возвращаемые заданным уровнем информации.

Уровень сведений	Возвращенные данные
BatteryDeviceName	Строка Юникода, завершающаяся null, которая указывает имя батареи.
BatteryEstimatedTime	Значение ULONG, указывающее предполагаемое время работы батареи в секундах. Если скорость стока, указанная в элементе AtRateструктуры BATTERY_QUERY_INFORMATION , равна нулю, это вычисление основано на текущей скорости стока. Если значение AtRate не равно нулю, возвращаемое время является ожидаемым временем выполнения для заданной скорости. Если предполагаемое время неизвестно (например, батарея не разрядится, а AtRate равна нулю), возвращается BATTERY_UNKNOWN_TIME . Обратите внимание, что это значение не очень точно в некоторых системах батареи. Значение может сильно отличаться в зависимости от текущего энергопотребления, на которое может повлиять активность диска и другие факторы. Механизм уведомления об изменениях в этом значении отсутствует.
BatteryGranularityInformation	Массив BATTERY_REPORTING_SCALE структур переменной длины, содержащий степень детализации отчетов для емкости аккумулятора, возвращаемой из IOCTL_BATTERY_QUERY_STATUS. Если степень детализации зависит от текущей емкости батареи, возвращается несколько записей. Интерпретацию массива записей см. в BATTERY_REPORTING_SCALE . Количество записей определяется размером возвращаемого буфера и может вычисляться как (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE)). Максимальное количество возвращаемых записей — четыре.
BatteryInformation	Структура BATTERY_INFORMATION .
BatteryManufactureDate	Структура BATTERY_MANUFACTURE_DATE .
BatteryManufactureName	Строка Юникода, завершающаяся null, которая содержит имя изготовителя батареи.
BatterySerialNumber	Строка Юникода, завершающаяся null, которая содержит серийный номер батареи.
BatteryTemperature	ULONG, содержащий текущую температуру батареи, в 10-х градусах Кельвина.
BatteryUniqueID	Строка Юникода, завершающаяся null, которая однозначно идентифицирует аккумулятор. Это значение можно использовать для отслеживания конкретной батареи. В случае смарт-батарей этот идентификатор будет представлять собой объединение названия изготовителя, имени устройства, даты производства и печатного представления серийного номера. Это значение не предназначено для отображения пользователю.

nOutBufferSize

Размер выходного буфера в байтах. В зависимости от уровня информации запрашиваемых данных это может быть буфер с разными размерами.

lpBytesReturned

Указатель на переменную, которая получает размер данных, возвращаемых в буфере lpOutBuffer , в байтах.

Если выходной буфер слишком мал для возврата каких-либо данных, вызов завершается ошибкой, GetLastError возвращает код ошибки ERROR_INSUFFICIENT_BUFFER, а возвращенное число байтов равно нулю.

Если lpOverlapped имеет значение NULL (неперекрывающийся ввод-вывод), lpBytesReturned не может иметь значение NULL.

Если значение lpOverlapped не равно NULL (перекрывающееся ввод-вывод), lpBytesReturned может иметь значение NULL. Если это перекрываемая операция, можно получить количество возвращаемых байтов, вызвав функцию GetOverlappedResult . Если hDevice связан с портом завершения ввода-вывода, вы можете получить количество возвращаемых байтов, вызвав функцию GetQueuedCompletionStatus .

lpOverlapped

Указатель на структуру OVERLAPPED .

Если hDevice был открыт с флагом FILE_FLAG_OVERLAPPED , lpOverlapped должен указывать на допустимую структуру OVERLAPPED . В этом случае DeviceIoControl выполняется как перекрываемая (асинхронная) операция. Если устройство было открыто с флагом FILE_FLAG_OVERLAPPED , а lpOverlapped имеет значение NULL, функция завершается сбоем непредсказуемым образом.

Если hDevice был открыт без указания флага FILE_FLAG_OVERLAPPED , lpOverlapped игнорируется, а функция DeviceIoControl не возвращается до завершения операции или до возникновения ошибки.

Возвращаемое значение

Если операция завершается успешно, DeviceIoControl возвращает ненулевое значение.

Если операция завершается сбоем или находится в состоянии ожидания, DeviceIoControl возвращает ноль. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Некоторые сведения об батареях являются необязательными или могут быть бессмысленными для некоторых батарей. Если определенный тип запрошенных данных недоступен для текущего аккумулятора, возвращается ERROR_INVALID_FUNCTION .

Все запросы сведений об батарее будут завершаться состоянием ERROR_NO_SUCH_DEVICE (или ERROR_FILE_NOT_FOUND в Windows 10 версии 1809 и более ранних версиях), если элемент BatteryTag запроса не совпадает с текущим тегом батареи. Это гарантирует, что возвращенная информация о батарее совпадает с информацией о запрошенной батарее (дополнительные сведения см. в разделе Теги батареи ).

Этот IOCTL батареи извлекает различные сведения для батареи. Структура входных параметров , BATTERY_QUERY_INFORMATION, указывает тип возвращаемых сведений и время возврата сведений об батарее. Тип данных и содержимое выходного буфера зависят от запрошенных данных.

Сведения о последствиях перекрывающихся операций ввода-вывода для этой операции см. в разделе Примечания статьи DeviceIoControl .

Примеры

Пример см. в разделе Перечисление устройств батареи.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Заголовок	Poclass.h; BatClass.h в Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP

См. также раздел

Сведения об батарее
Коды управления питанием
DeviceIoControl
BATTERY_QUERY_INFORMATION
BATTERY_REPORTING_SCALE
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION