код элемента управления 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_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 [только классические приложения] |
| Заголовок |
|