IOCTL_BATTERY_QUERY_TAG codice di controllo

Articolo
06/12/2023

Recupera il tag 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_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

Parametri

hDevice

Handle alla batteria da cui recuperare il tag. 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_TAG per questa operazione.

lpInBuffer

Puntatore a un buffer di input ULONG . Il valore indica il numero di millisecondi da attendere se non è presente alcuna batteria. Un valore di -1 indica che la richiesta attenderà in modo indefinito (o fino a quando non viene annullata da un altro evento).

nInBufferSize

Dimensioni del buffer di input, in byte.

lpOutBuffer

Puntatore a un buffer di output ULONG . In caso di esito positivo, questo buffer contiene il tag della batteria corrente, che può essere qualsiasi valore tranne BATTERY_TAG_INVALID. In caso di errore, se GetLastError restituisce il codice di errore ERROR_FILE_NOT_FOUND, questo buffer contiene il valore BATTERY_TAG_INVALID.

nOutBufferSize

Dimensioni in byte del buffer di output.

lpBytesReturned

Puntatore a una variabile che riceve le dimensioni dei dati archiviati 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 il tag corrente della batteria. Il tag della batteria è un valore diverso da zero univoco che cambia quando la batteria fisica viene reinsertata, sostituita o subisce modifiche caratteristiche. Vedere la sezione Tag batteria nell'argomento Informazioni sulla batteria per altri dettagli su quando cambia un tag di batteria, su come rilevare la modifica e su come un'applicazione deve procedere dopo una modifica del tag della batteria. Quando una batteria non è presente, questa richiesta attenderà il tempo indicato e, se non esiste ancora una batteria presente, restituirà ERROR_FILE_NOT_FOUND e imposta il tag della batteria su BATTERY_TAG_INVALID. Per altre informazioni, vedere Informazioni sulla batteria.

Tutte le richieste per altre informazioni sulla batteria richiedono al chiamante di specificare il tag della batteria corrispondente. Ciò garantisce che il chiamante riceva informazioni per la stessa batteria per ogni richiesta e garantisce che il chiamante sia consapevole delle modifiche della batteria senza polling costante.

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
IOCTL_BATTERY_QUERY_INFORMATION
IOCTL_BATTERY_QUERY_STATUS
IOCTL_BATTERY_SET_INFORMATION

Condividi tramite