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

Статья
06/12/2023

Извлекает текущий тег батареи.

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

Параметры

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 (неперекрывающийся ввод-вывод), 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 батареи извлекает текущий тег батареи. Тег батареи — это уникальное ненулевое значение, которое изменяется при повторной установке, замене или изменении характеристик физического аккумулятора. Дополнительные сведения о том, когда меняется тег батареи, как обнаружить это изменение и как приложение должно работать после изменения тега батареи, см. в разделе "Теги батареи" статьи Обзор сведений о батарее. Если батарея отсутствует, этот запрос будет ожидать указанное время, а если батареи по-прежнему нет, он вернет ERROR_FILE_NOT_FOUND и установит тег батареи BATTERY_TAG_INVALID. (Дополнительные сведения см. в разделе Сведения о батарее.)

Все запросы других сведений об батарее требуют, чтобы вызывающий объект предоставлял соответствующий тег батареи. Это гарантирует, что вызывающий объект получает сведения об одном и том же аккумуляторе для каждого запроса, и гарантирует, что вызывающий объект будет получать сведения об изменениях батареи без постоянного опроса.

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

Поделиться через