IOCTL_BATTERY_QUERY_INFORMATION codice di controllo
Recupera un'ampia gamma di informazioni per la batteria.
Per eseguire questa operazione, chiamare la funzione DeviceIoControl con i parametri seguenti.
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
);
Parametri
-
hDevice
-
Handle alla batteria su 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_INFORMATION per questa operazione.
-
lpInBuffer
-
Puntatore a una struttura BATTERY_QUERY_INFORMATION .
-
nInBufferSize
-
Dimensioni del buffer di input, in byte.
-
lpOutBuffer
-
Puntatore al buffer restituito. Il tipo di dati (e, di conseguenza, le dimensioni) del buffer restituito dipende dalle informazioni richieste nel membro BATTERY_QUERY_INFORMATION_LEVEL della struttura di input BATTERY_QUERY_INFORMATION .
La tabella seguente mostra i dati restituiti da un determinato livello di informazioni.
Livello informazioni Dati restituiti BatteryDeviceName Stringa Unicode con terminazione null che specifica il nome della batteria. BatteryEstimatedTime ULONG che specifica il tempo di esecuzione stimato della batteria, in secondi. Se il tasso di svuotamento fornito nel membro AtRate della struttura BATTERY_QUERY_INFORMATION è zero, questo calcolo si basa sulla frequenza di svuotamento attuale. Se AtRate è diverso da zero, il tempo restituito è il tempo di esecuzione previsto per la frequenza specificata. Se il tempo stimato è sconosciuto (ad esempio, la batteria non viene scaricata e AtRate è zero), BATTERY_UNKNOWN_TIME viene restituito. Si noti che questo valore non è molto accurato su alcuni sistemi di batteria. Il valore può variare ampiamente a seconda dell'utilizzo dell'alimentazione presente, che potrebbe essere influenzato dall'attività del disco e da altri fattori. Non esiste alcun meccanismo di notifica per le modifiche apportate a questo valore. BatteryGranularityInformation Matrice a lunghezza variabile di strutture BATTERY_REPORTING_SCALE che contiene la granularità di report per la capacità della batteria restituita da IOCTL_BATTERY_QUERY_STATUS. Più voci vengono restituite quando la granularità dipende dalla capacità presente della batteria. Vedere BATTERY_REPORTING_SCALE per l'interpretazione della matrice di voci. Il numero di voci è indicato dalle dimensioni del buffer restituito e può essere calcolato come (lpBytesReturned /sizeof (BATTERY_REPORTING_SCALE)). Il numero massimo di voci restituite è quattro. BatteryInformation Struttura BATTERY_INFORMATION . BatteryManufactureDate Struttura BATTERY_MANUFACTURE_DATE . BatteryManufactureName Stringa Unicode con terminazione null contenente il nome del produttore della batteria. BatterySerialNumber Stringa Unicode con terminazione null contenente il numero di serie della batteria. BatteryTemperature ULONG che contiene la temperatura corrente della batteria, in 10th di un grado Kelvin. BatteryUniqueID Stringa Unicode con terminazione null che identifica in modo univoco la batteria. Questo valore può essere usato per tenere traccia di una batteria specifica. Nel caso di batterie intelligenti, questo ID sarà la concatenazione del nome del produttore, il nome del dispositivo, la data di produzione e una rappresentazione stampabile del numero di serie. Questo valore non deve essere visualizzato all'utente. -
nOutBufferSize
-
Dimensioni in byte del buffer di output. A seconda del livello di informazioni richiesto, questo può essere un buffer di dimensioni variabile.
-
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.
Alcune informazioni sulle batterie sono facoltative o possono essere senza senso per alcune batterie. Se il tipo specifico di dati richiesto non è disponibile per la batteria corrente, ERROR_INVALID_FUNCTION viene restituito.
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 un'ampia gamma di informazioni per la batteria. La struttura dei parametri di input, BATTERY_QUERY_INFORMATION, indica il tipo di informazioni da restituire e quando devono essere restituite le informazioni sulla batteria. Il tipo di dati e il contenuto del buffer di output variano in base ai dati richiesti.
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 |
|
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per