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