IOCTL_BATTERY_QUERY_INFORMATION Steuerungscode
Ruft eine Vielzahl von Informationen für den Akku ab.
Um diesen Vorgang auszuführen, rufen Sie die DeviceIoControl-Funktion mit den folgenden Parametern auf.
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
);
Parameter
-
hGeräte
-
Ein Ziehpunkt für den Akku, über den Informationen zurückgegeben werden sollen. Um ein Gerätehandle abzurufen, rufen Sie die Funktion CreateFile auf.
-
dwIoControlCode
-
Der Steuerelementcode für den Vorgang. Dieser Wert gibt den spezifischen Vorgang an, der ausgeführt werden soll, und den Typ des Geräts, auf dem er ausgeführt werden soll. Verwenden Sie für diesen Vorgang IOCTL_BATTERY_QUERY_INFORMATION .
-
lpInBuffer
-
Ein Zeiger auf eine BATTERY_QUERY_INFORMATION-Struktur .
-
nInBufferSize
-
Die Größe des Eingabepuffers in Bytes.
-
lpOutBuffer
-
Ein Zeiger auf den Rückgabepuffer. Der Datentyp (und damit die Größe) des Rückgabepuffers hängt von den informationen ab, die im BATTERY_QUERY_INFORMATION_LEVEL Member der Eingabe BATTERY_QUERY_INFORMATION Struktur angefordert werden.
Die folgende Tabelle zeigt die von einer bestimmten Informationsebene zurückgegebenen Daten.
Informationsebene Zurückgegebene Daten BatteryDeviceName Unicode-Zeichenfolge mit Null-Endung, die den Namen des Akkus angibt. BatteryEstimatedTime Eine ULONG , die die geschätzte Akkulaufzeit in Sekunden angibt. Wenn die im AtRate-Element der BATTERY_QUERY_INFORMATION-Struktur angegebene Entwässerungsrate null ist, basiert diese Berechnung auf der aktuellen Entwässerungsrate. Wenn AtRate nonzero ist, ist die zurückgegebene Zeit die erwartete Laufzeit für die angegebene Rate. Wenn die geschätzte Zeit unbekannt ist (z. B. wird der Akku nicht entladen und AtRate ist null), wird BATTERY_UNKNOWN_TIME zurückgegeben. Beachten Sie, dass dieser Wert bei einigen Batteriesystemen nicht sehr genau ist. Der Wert kann je nach derzeitigem Energieverbrauch stark variieren, was durch die Datenträgeraktivität und andere Faktoren beeinflusst werden kann. Es gibt keinen Benachrichtigungsmechanismus für Änderungen an diesem Wert. BatteryGranularityInformation Ein Array mit BATTERY_REPORTING_SCALE Strukturen mit variabler Länge, das die Granularität der Berichterstellung für die Batteriekapazität enthält, die von IOCTL_BATTERY_QUERY_STATUS zurückgegeben wird. Mehrere Einträge werden zurückgegeben, wenn die Granularität von der aktuellen Kapazität des Akkus abhängt. Informationen zur Interpretation des Arrays von Einträgen finden Sie unter BATTERY_REPORTING_SCALE . Die Anzahl der Einträge wird durch die Größe des zurückgegebenen Puffers angegeben und kann als (lpBytesReturned / sizeof (BATTERY_REPORTING_SCALE)) berechnet werden. Die maximale Anzahl der zurückgegebenen Einträge beträgt vier. BatteryInformation Eine BATTERY_INFORMATION-Struktur . BatteryManufactureDate Eine BATTERY_MANUFACTURE_DATE-Struktur . BatteryManufactureName Unicode-Zeichenfolge mit Null-Endung, die den Namen des Herstellers des Akkus enthält. BatterySerialNumber Unicode-Zeichenfolge mit Null-Endung, die die Seriennummer des Akkus enthält. BatteryTemperature Ein ULONG , der die aktuelle Temperatur der Batterie in 10 Grad Kelvin enthält. BatteryUniqueID Unicode-Zeichenfolge mit Null-Endung, die den Akku eindeutig identifiziert. Dieser Wert kann verwendet werden, um eine bestimmte Batterie nachzuverfolgen. Bei smarten Batterien ist diese ID die Verkettung des Herstellernamens, Gerätenamens, Herstellungsdatums und druckbarer Darstellung der Seriennummer. Dieser Wert soll dem Benutzer nicht angezeigt werden. -
nOutBufferSize
-
Die Größe des Ausgabepuffers in Bytes. Je nach Informationsebene der angeforderten Daten kann es sich hierbei um einen Puffer mit unterschiedlicher Größe handelt.
-
lpBytesReturned
-
Ein Zeiger auf eine Variable, die die Größe der im lpOutBuffer-Puffer zurückgegebenen Daten in Bytes empfängt.
Wenn der Ausgabepuffer zu klein ist, um Daten zurückzugeben, schlägt der Aufruf fehl, GetLastError gibt den Fehlercode ERROR_INSUFFICIENT_BUFFER zurück, und die zurückgegebene Byteanzahl ist 0.
Wenn lpOverlappedNULL (nicht überlappende E/A) ist, kann lpBytesReturned nicht NULL sein.
Wenn lpOverlapped nicht NULL (überlappende E/A) ist, kann lpBytesReturnedNULL sein. Wenn es sich um einen überlappenden Vorgang handelt, können Sie die Anzahl der zurückgegebenen Bytes abrufen, indem Sie die GetOverlappedResult-Funktion aufrufen. Wenn hDevice einem E/A-Vervollständigungsport zugeordnet ist, können Sie die Anzahl der zurückgegebenen Bytes abrufen, indem Sie die GetQueuedCompletionStatus-Funktion aufrufen.
-
lpOverlapped
-
Ein Zeiger auf eine ÜBERLAPPENDE Struktur.
Wenn hDevice mit dem flag FILE_FLAG_OVERLAPPED geöffnet wurde, muss lpOverlapped auf eine gültige OVERLAPPED-Struktur verweisen. In diesem Fall wird DeviceIoControl als überlappender (asynchroner) Vorgang ausgeführt. Wenn das Gerät mit dem flag FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlappedNULL ist, schlägt die Funktion auf unvorhersehbare Weise fehl.
Wenn hDevice geöffnet wurde, ohne das flag FILE_FLAG_OVERLAPPED anzugeben, wird lpOverlapped ignoriert, und die DeviceIoControl-Funktion wird erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder bis ein Fehler auftritt.
Rückgabewert
Wenn der Vorgang erfolgreich abgeschlossen wurde, gibt DeviceIoControl einen wert ohne Zero zurück.
Wenn der Vorgang fehlschlägt oder aussteht, gibt DeviceIoControl null zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Einige Informationen zu Batterien sind optional oder für einige Batterien bedeutungslos. Wenn der bestimmte Typ der angeforderten Daten für den aktuellen Akku nicht verfügbar ist, wird ERROR_INVALID_FUNCTION zurückgegeben.
Alle Anforderungen für Akkuinformationen werden mit dem status von ERROR_NO_SUCH_DEVICE (oder ERROR_FILE_NOT_FOUND in Windows 10 Version 1809 und früher) abgeschlossen, wenn das BatteryTag-Element der Anforderung nicht mit dem des aktuellen Akkutags übereinstimmt. Dadurch wird sichergestellt, dass die zurückgegebenen Akkuinformationen mit denen des angeforderten Akkus übereinstimmen (weitere Informationen finden Sie unter Akkutags ).
Bemerkungen
Diese Akku-IOCTL ruft eine Vielzahl von Informationen für den Akku ab. Die Eingabeparameterstruktur BATTERY_QUERY_INFORMATION gibt den Typ der zurückzugebenden Informationen an und wann die Akkuinformationen zurückgegeben werden sollen. Der Datentyp und der Inhalt des Ausgabepuffers variieren je nach den angeforderten Daten.
Die Auswirkungen von überlappenden E/A-Vorgängen auf diesen Vorgang finden Sie im Abschnitt Hinweise des Themas DeviceIoControl .
Beispiele
Ein Beispiel finden Sie unter Aufzählen von Akkugeräten.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) |
Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
Windows Server 2003 [nur Desktop-Apps] |
| Header |
|