IOCTL_BATTERY_QUERY_INFORMATION código de controle
Recupera uma variedade de informações para a bateria.
Para executar essa operação, chame a função DeviceIoControl com os parâmetros a seguir.
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
);
Parâmetros
-
hDevice
-
Um identificador para a bateria na qual as informações devem ser retornadas. Para recuperar um identificador de dispositivo, chame a função CreateFile .
-
Dwiocontrolcode
-
O código de controle da operação. Esse valor identifica a operação específica a ser executada e o tipo de dispositivo no qual executá-la. Use IOCTL_BATTERY_QUERY_INFORMATION para esta operação.
-
lpInBuffer
-
Um ponteiro para uma estrutura BATTERY_QUERY_INFORMATION .
-
nInBufferSize
-
O tamanho do buffer de entrada, em bytes.
-
Lpoutbuffer
-
Um ponteiro para o buffer de retorno. O tipo de dados (e, portanto, o tamanho) do buffer de retorno depende das informações solicitadas no membro BATTERY_QUERY_INFORMATION_LEVEL da estrutura de BATTERY_QUERY_INFORMATION de entrada.
A tabela a seguir mostra os dados retornados por um determinado nível de informação.
Nível de informações Dados retornados BatteryDeviceName Cadeia de caracteres Unicode terminada em nulo que especifica o nome da bateria. BatteryEstimatedTime Um ULONG que especifica o tempo de execução estimado da bateria, em segundos. Se a taxa de drenagem fornecida no membro AtRate da estrutura BATTERY_QUERY_INFORMATION for zero, esse cálculo será baseado na taxa atual de drenagem. Se AtRate for diferente de zero, o tempo retornado será o tempo de execução esperado para a taxa fornecida. Se o tempo estimado for desconhecido (por exemplo, a bateria não está descarregando e AtRate é zero), BATTERY_UNKNOWN_TIME é retornado. Observe que esse valor não é muito preciso em alguns sistemas de bateria. O valor pode variar muito dependendo do uso de energia atual, que pode ser afetado pela atividade do disco e outros fatores. Não há nenhum mecanismo de notificação para alterações nesse valor. BatteryGranularityInformation Uma matriz de comprimento variável de estruturas BATTERY_REPORTING_SCALE que contém a granularidade de relatório para a capacidade da bateria retornada de IOCTL_BATTERY_QUERY_STATUS. Várias entradas são retornadas quando a granularidade depende da capacidade atual da bateria. Consulte BATTERY_REPORTING_SCALE para obter a interpretação da matriz de entradas. O número de entradas é indicado pelo tamanho do buffer retornado e pode ser calculado como (lpBytesReturned /sizeof (BATTERY_REPORTING_SCALE)). O número máximo de entradas que serão retornadas é quatro. BatteryInformation Uma estrutura BATTERY_INFORMATION . BatteryManufactureDate Uma estrutura BATTERY_MANUFACTURE_DATE . BatteryManufactureName Cadeia de caracteres Unicode terminada em nulo que contém o nome do fabricante da bateria. BatterySerialNumber Cadeia de caracteres Unicode terminada em nulo que contém o número de série da bateria. BatteryTemperature Um ULONG que contém a temperatura atual da bateria, em 10º grau Kelvin. BatteryUniqueID Cadeia de caracteres Unicode terminada em nulo que identifica exclusivamente a bateria. Esse valor pode ser usado para rastrear uma bateria específica. No caso de baterias inteligentes, essa ID será a concatenação do nome do fabricante, nome do dispositivo, data de fabricação e uma representação imprimível do número de série. Esse valor não se destina a ser exibido ao usuário. -
nOutBufferSize
-
O tamanho do buffer de saída em bytes. Dependendo do nível de informações dos dados solicitados, esse pode ser um buffer de tamanho variably.
-
Lpbytesreturned
-
Um ponteiro para uma variável que recebe o tamanho dos dados retornados no buffer lpOutBuffer , em bytes.
Se o buffer de saída for muito pequeno para retornar dados, a chamada falhará, GetLastError retornará o código de erro ERROR_INSUFFICIENT_BUFFER e a contagem de bytes retornada será zero.
Se lpOverlapped for NULL (E/S não sobreposta), lpBytesReturned não poderá ser NULL.
Se lpOverlapped não for NULL (E/S sobreposta), lpBytesReturned poderá ser NULL. Se essa for uma operação sobreposta, você poderá recuperar o número de bytes retornados chamando a função GetOverlappedResult . Se hDevice estiver associado a uma porta de conclusão de E/S, você poderá obter o número de bytes retornados chamando a função GetQueuedCompletionStatus .
-
Lpoverlapped
-
Um ponteiro para uma estrutura OVERLAPPED .
Se hDevice tiver sido aberto com o sinalizador FILE_FLAG_OVERLAPPED , lpOverlapped deverá apontar para uma estrutura OVERLAPPED válida. Nesse caso, DeviceIoControl é executado como uma operação sobreposta (assíncrona). Se o dispositivo tiver sido aberto com o sinalizador FILE_FLAG_OVERLAPPED e lpOverlapped for NULL, a função falhará de maneiras imprevisíveis.
Se hDevice foi aberto sem especificar o sinalizador FILE_FLAG_OVERLAPPED , lpOverlapped será ignorado e a função DeviceIoControl não retornará até que a operação seja concluída ou até que ocorra um erro.
Valor retornado
Se a operação for concluída com êxito, DeviceIoControl retornará um valor diferente de zero.
Se a operação falhar ou estiver pendente, DeviceIoControl retornará zero. Para obter informações de erro estendidas, chame GetLastError.
Algumas informações sobre baterias são opcionais ou podem não ter sentido para algumas baterias. Se o tipo específico de dados solicitado não estiver disponível para a bateria atual, ERROR_INVALID_FUNCTION será retornado.
Todas as solicitações de informações de bateria serão concluídas com o status de ERROR_NO_SUCH_DEVICE (ou ERROR_FILE_NOT_FOUND no Windows 10 versão 1809 e anterior) sempre que o elemento BatteryTag da solicitação não corresponder ao da marca de bateria atual. Isso garante que as informações de bateria retornadas correspondam à da bateria solicitada (consulte Marcas de bateria para obter mais informações).
Comentários
Esta ioctl de bateria recupera uma variedade de informações para a bateria. A estrutura do parâmetro de entrada, BATTERY_QUERY_INFORMATION, indica o tipo de informação a ser retornado e quando as informações da bateria devem ser retornadas. O tipo de dados e o conteúdo do buffer de saída variam de acordo com os dados solicitados.
Para obter as implicações de E/S sobreposta nesta operação, consulte a seção Comentários do tópico DeviceIoControl .
Exemplos
Para obter um exemplo, consulte Enumerando dispositivos de bateria.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte |
Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte |
Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho |
|