IOCTL _ BATTERY _ QUERY _ STATUS-Steuerungscode
Ruft den aktuellen Status des Akkus ab.
Rufen Sie zum Ausführen dieses Vorgangs die DeviceIoControl-Funktion mit den folgenden Parametern auf.
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
);
Parameter
-
hDevice
-
Ein Handle für den Akku, aus dem Informationen zurückgegeben werden sollen. Um ein Gerätehandle abzurufen, rufen Sie die CreateFile-Funktion auf.
-
dwIoControlCode
-
Der Steuerelementcode für den Vorgang. Dieser Wert gibt den bestimmten auszuführenden Vorgang und den Gerätetyp an, auf dem er ausgeführt werden soll. Verwenden Sie IOCTL _ BATTERY _ QUERY _ STATUS für diesen Vorgang.
-
lpInBuffer
-
Ein Zeiger auf eine BATTERY _ WAIT _ STATUS-Struktur.
-
nInBufferSize
-
Die Größe des Eingabepuffers in Bytes.
-
lpOutBuffer
-
Ein Zeiger auf eine BATTERY _ STATUS-Struktur.
-
nOutBufferSize
-
Die Größe des Ausgabepuffers in Bytes.
-
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 (null).
Wenn lpOverlapped NULL ist (nicht überlagerte E/A), darf lpBytesReturned nicht NULL sein.
Wenn lpOverlapped nicht NULL ist (überlappende E/A), kann lpBytesReturned NULL 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-Abschlussport zugeordnet ist, können Sie die Anzahl der zurückgegebenen Bytes abrufen, indem Sie die GetQueuedCompletionStatus-Funktion aufrufen.
-
lpOverlapped
-
Ein Zeiger auf eine OVERLAPPED-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 lpOverlapped NULL 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, nachdem der Vorgang abgeschlossen wurde oder bis ein Fehler auftritt.
Rückgabewert
Wenn der Vorgang erfolgreich abgeschlossen wurde, gibt DeviceIoControl einen Wert ungleich 0 (null) zurück.
Wenn der Vorgang fehlschlägt oder aussteht, gibt DeviceIoControl 0 (null) zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
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).
Hinweise
Diese Akku-IOCTL ruft den Status des Akkus zum Zeitpunkt der Rückkehr des Vorgangs ab. Die Eingabeparameterstruktur BATTERY _ WAIT _ STATUSgibt an, wann der Akkustatus verarbeitet und zurückgegeben werden soll.
Anforderungen für den Akkustatus können für die sofortige Rückgabe oder festgelegt werden, um auf eine bestimmte Bedingung zu warten, bevor sie abgeschlossen werden. Beispielsweise kann eine Anforderung für Akkuinformationen erfolgen, die wartet, bis die Akkukapazität einen bestimmten Punkt erreicht oder sich der Akkuzustand ändert.
Alle Anforderungen für Akkuinformationen werden mit dem Status ERROR _ FILE NOT _ _ FOUND abgeschlossen, wenn das BatteryTag-Element der Anforderung nicht mit dem des aktuellen Akkutags übereinstimmt. (Weitere Informationen finden Sie unter Akkutags.) Dadurch wird sichergestellt, dass die zurückgegebenen Akkuinformationen mit denen des angeforderten Akkus übereinstimmen.
Informationen zu den Auswirkungen überlappender E/A-Vorgänge für diesen Vorgang finden Sie im Abschnitt "Hinweise" des Themas DeviceIoControl.
Beispiele
Ein Beispiel finden Sie unter Aufzählen von Akkugeräten.
Requirements (Anforderungen)
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) |
nur Windows [ XP-Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
nur Windows Server [ 2003-Desktop-Apps] |
| Header |
|