Код элемента управления IOCTL_BATTERY_QUERY_STATUS

Статья
06/12/2023

Извлекает текущее состояние батареи.

Для выполнения этой операции вызовите функцию DeviceIoControl со следующими параметрами.

BOOL DeviceIoControl(
  (HANDLE) hDevice,           // handle to battery
  IOCTL_BATTERY_QUERY_STATUS, // 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_STATUS .

lpInBuffer

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

nInBufferSize

Размер входного буфера в байтах.

lpOutBuffer

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

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_NO_SUCH_DEVICE (или ERROR_FILE_NOT_FOUND в Windows 10 версии 1809 и более ранних версиях), если элемент BatteryTag запроса не соответствует элементу текущего тега батареи. Это гарантирует, что возвращенные сведения о батарее совпадают с сведениями о запрошенной батарее (дополнительные сведения см. в разделе Теги батареи ).

Этот IOCTL батареи извлекает состояние батареи на момент возврата операции. Структура входных параметров , BATTERY_WAIT_STATUS, указывает, когда необходимо обработать и вернуть состояние батареи.

Запросы на состояние батареи могут быть немедленно возвращены или настроены на ожидание определенного условия перед завершением. Например, можно выполнить запрос на получение сведений об батарее, который ожидает, пока емкость батареи достигнет указанной точки или не изменится состояние батареи.

Все запросы сведений о батарее завершатся состоянием ERROR_FILE_NOT_FOUND всякий раз, когда элемент BatteryTag запроса не совпадает с текущим тегом батареи. (Дополнительные сведения см. в разделе Теги батареи .) Это позволяет убедиться, что возвращаемые сведения об аккумуляторе соответствуют сведениям о запрошенной батарее.

Сведения о последствиях перекрывающихся операций ввода-вывода для этой операции см. в разделе Примечания статьи 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_STATUS
BATTERY_WAIT_STATUS
IOCTL_BATTERY_QUERY_INFORMATION
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION