IOCTL_BATTERY_QUERY_STATUS codice di controllo

Articolo
06/12/2023

Recupera lo stato corrente della batteria.

Per eseguire questa operazione, chiamare la funzione DeviceIoControl con i parametri seguenti.

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
);

Parametri

hDevice

Handle alla batteria da cui restituire le informazioni. Per recuperare un handle del dispositivo, chiamare la funzione CreateFile .

dwIoControlCode

Codice di controllo per l'operazione. Questo valore identifica l'operazione specifica da eseguire e il tipo di dispositivo su cui eseguirlo. Usare IOCTL_BATTERY_QUERY_STATUS per questa operazione.

lpInBuffer

Puntatore a una struttura BATTERY_WAIT_STATUS .

nInBufferSize

Dimensioni del buffer di input, in byte.

lpOutBuffer

Puntatore a una struttura BATTERY_STATUS .

nOutBufferSize

Dimensioni in byte del buffer di output.

lpBytesReturned

Puntatore a una variabile che riceve le dimensioni dei dati restituiti nel buffer lpOutBuffer , in byte.

Se il buffer di output è troppo piccolo per restituire i dati, la chiamata ha esito negativo, GetLastError restituisce il codice di errore ERROR_INSUFFICIENT_BUFFER e il conteggio dei byte restituito è zero.

Se lpOverlapped è NULL (I/O non sovrapposto), lpBytesReturned non può essere NULL.

Se lpOverlapped non è NULL (sovrapposto I/O), lpBytesReturned può essere NULL. Se si tratta di un'operazione sovrapposta, è possibile recuperare il numero di byte restituiti chiamando la funzione GetOverlappedResult . Se hDevice è associato a una porta di completamento di I/O, è possibile ottenere il numero di byte restituiti chiamando la funzione GetQueuedCompletionStatus .

lpOverlapped

Puntatore a una struttura OVERLAPPED .

Se hDevice è stato aperto con il flag FILE_FLAG_OVERLAPPED , lpOverlapped deve puntare a una struttura OVERLAPPED valida. In questo caso, DeviceIoControl viene eseguito come operazione sovrapposta (asincrona). Se il dispositivo è stato aperto con il flag FILE_FLAG_OVERLAPPED e lpOverlapped è NULL, la funzione non riesce in modi imprevedibili.

Se hDevice è stato aperto senza specificare il flag FILE_FLAG_OVERLAPPED , lpOverlapped viene ignorato e la funzione DeviceIoControl non restituisce fino al completamento dell'operazione o fino a quando non si verifica un errore.

Valore restituito

Se l'operazione viene completata correttamente, DeviceIoControl restituisce un valore diverso da zero.

Se l'operazione ha esito negativo o è in sospeso, DeviceIoControl restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Tutte le richieste di informazioni sulla batteria verranno completate con lo stato di ERROR_NO_SUCH_DEVICE (o ERROR_FILE_NOT_FOUND in Windows 10 versione 1809 e versioni precedenti) ogni volta che l'elemento BatteryTag della richiesta non corrisponde a quello del tag della batteria corrente. Ciò garantisce che le informazioni sulla batteria restituite corrispondano a quella della batteria richiesta (vedere Tag batteria per altre informazioni).

Commenti

Questa batteria IOCTL recupera lo stato della batteria al momento del ritorno dell'operazione. La struttura dei parametri di input, BATTERY_WAIT_STATUS, indica quando lo stato della batteria deve essere elaborato e restituito.

Le richieste di stato della batteria possono essere per la restituzione immediata o possono essere impostate per attendere una determinata condizione prima del completamento. Ad esempio, una richiesta di informazioni sulla batteria può essere effettuata che attende fino a quando la capacità della batteria raggiunge un punto specificato o lo stato della batteria cambia.

Tutte le richieste per le informazioni sulla batteria verranno completate con lo stato di ERROR_FILE_NOT_FOUND ogni volta che l'elemento BatteryTag della richiesta non corrisponde a quello del tag della batteria corrente. Per altre informazioni, vedere Tag batteria . Questo viene usato per assicurarsi che le informazioni sulla batteria restituite corrispondano a quella della batteria richiesta.

Per le implicazioni dell'I/O sovrapposta in questa operazione, vedere la sezione Osservazioni dell'argomento DeviceIoControl .

Esempio

Per un esempio, vedere Enumerazione dei dispositivi batteria.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	Poclass.h; BatClass.h in Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP

Vedi anche

Informazioni sulla batteria
Codici di controllo di Gestione energia
Deviceiocontrol
BATTERY_STATUS
BATTERY_WAIT_STATUS
IOCTL_BATTERY_QUERY_INFORMATION
IOCTL_BATTERY_QUERY_TAG
IOCTL_BATTERY_SET_INFORMATION

Condividi tramite