IOCTL_BATTERY_QUERY_TAG código de controle
Recupera a marca atual da 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_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
Parâmetros
-
hDevice
-
Um identificador para a bateria da qual a marca deve ser recuperada. Para recuperar um identificador de dispositivo, chame a função CreateFile .
-
Dwiocontrolcode
-
O código de controle para a 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_TAG para esta operação.
-
lpInBuffer
-
Um ponteiro para um buffer de entrada ULONG . O valor indica o número de milissegundos a aguardar se não houver bateria. Um valor de -1 indica que a solicitação aguardará indefinidamente (ou até que seja cancelada por algum outro evento).
-
nInBufferSize
-
O tamanho do buffer de entrada, em bytes.
-
Lpoutbuffer
-
Um ponteiro para um buffer de saída ULONG . Com êxito, esse buffer contém a marca de bateria atual, que pode ser qualquer valor, exceto BATTERY_TAG_INVALID. Em caso de falha, se GetLastError retornar o código de erro ERROR_FILE_NOT_FOUND, esse buffer conterá o valor BATTERY_TAG_INVALID.
-
nOutBufferSize
-
O tamanho do buffer de saída em bytes.
-
Lpbytesreturned
-
Um ponteiro para uma variável que recebe o tamanho dos dados armazenados 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 foi 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 foi 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.
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
Essa bateria IOCTL recupera a marca atual da bateria. A marca de bateria é um valor diferente de zero exclusivo que muda quando a bateria física é reinserida, substituída ou passa por alterações características. Consulte a seção Marcas de Bateria no tópico Visão geral de Informações da Bateria para obter mais detalhes sobre quando uma marca de bateria é alterada, como detectar a alteração e como um aplicativo deve continuar após a alteração de uma marca de bateria. Quando uma bateria não estiver presente, essa solicitação aguardará o tempo indicado e, se ainda não houver bateria presente, ela retornará ERROR_FILE_NOT_FOUND e definirá a marca da bateria como BATTERY_TAG_INVALID. (Consulte Informações sobre bateria para obter mais informações.)
Todas as solicitações de outras informações de bateria exigem que o chamador forneça a marca de bateria correspondente. Isso garante que o chamador esteja recebendo informações para a mesma bateria para cada solicitação e garante que o chamador esteja ciente das alterações de bateria sem sondagem constante.
Para obter as implicações de E/S sobrepostas nessa 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 |
|