IOCTL _ BATTERY _ QUERY _ TAG-Steuerungscode
Ruft das aktuelle Tag des Akkus ab.
Um diesen Vorgang durchzuführen, rufen Sie die DeviceIoControl-Funktion mit den folgenden Parametern auf.
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
Parameter
-
hDevice
-
Ein Handle für den Akku, aus dem das Tag abgerufen werden soll. Um ein Gerätehand handle abzurufen, rufen Sie die CreateFile-Funktion auf.
-
dwIoControlCode
-
Der Steuerungscode für den Vorgang. Dieser Wert identifiziert den spezifischen Vorgang, der ausgeführt werden soll, und den Typ des Geräts, auf dem er ausgeführt werden soll. Verwenden Sie IOCTL _ BATTERY QUERY _ _ TAG für diesen Vorgang.
-
lpInBuffer
-
Ein Zeiger auf einen ULONG-Eingabepuffer. Der Wert gibt die Anzahl der Millisekunden an, die gewartet werden soll, wenn kein Akku vor sich geht. Der Wert -1 gibt an, dass die Anforderung unbegrenzt wartet (oder bis sie von einem anderen Ereignis abgebrochen wird).
-
nInBufferSize
-
Die Größe des Eingabepuffers in Bytes.
-
lpOutBuffer
-
Ein Zeiger auf einen ULONG-Ausgabepuffer. Bei Erfolg enthält dieser Puffer das aktuelle Akkutag, das ein beliebiger Wert außer BATTERY _ TAG INVALID sein _ kann. Wenn getLastError bei einem Fehler den Fehlercode ERROR FILE _ NOT _ _ FOUND zurückgibt, enthält dieser Puffer den Wert BATTERY TAG _ _ INVALID.
-
nOutBufferSize
-
Die Größe des Ausgabepuffers in Bytes.
-
lpBytesReturned
-
Ein Zeiger auf eine Variable, die die Größe der im lpOutBuffer-Puffer gespeicherten Daten in Bytes empfängt.
Wenn der Ausgabepuffer zu klein ist, um Daten zurückgibt, 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 übersprungene E/A), kann lpBytesReturned nicht NULL sein.
Wenn lpOverlapped nicht NULL (überlappende E/A) ist, 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 überlappende (asynchrone) Operation 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 gibt erst dann zurück, wenn der Vorgang abgeschlossen ist oder 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 an Akkuinformationen werden mit dem Status 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 übereinstimmen. Dadurch wird sichergestellt, dass die zurückgegebenen Akkuinformationen mit denen des angeforderten Akkus (weitere Informationen finden Sie unter Akkutags) entspricht.
Hinweise
Diese Akku-IOCTL ruft das aktuelle Tag des Akkus ab. Das Akkutag ist ein eindeutiger Wert ungleich 0 (null), der sich ändert, wenn der physische Akku erneut ein- oder ausgetauscht wird oder charakteristische Änderungen vorgenommen werden. Im Abschnitt Akkutags des Themas Übersicht über Akkuinformationen finden Sie weitere Details dazu, wann sich ein Akkutag ändert, wie die Änderung erkannt wird und wie eine Anwendung nach einer Änderung des Akkutags fortgesetzt werden sollte. Wenn kein Akku vorhanden ist, wartet diese Anforderung die angegebene Zeit, und wenn immer noch kein Akku vorhanden ist, wird FEHLERDATEI _ NICHT _ _ GEFUNDEN zurückgegeben, und das Akkutag wird auf BATTERY TAG _ _ INVALID festgelegt. (Weitere Informationen finden Sie unter Akkuinformationen.)
Alle Anforderungen für andere Akkuinformationen erfordern, dass der Aufrufer das entsprechende Akkutag anpasst. Dadurch wird sichergestellt, dass der Aufrufer für jede Anforderung Informationen für denselben Akku erhält, und stellt sicher, dass der Aufrufer Akkuänderungen ohne konstanten Abruf kennt.
Informationen zu den Auswirkungen von überlappenden E/A-Daten auf 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) |
Windows [ XP-Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
Windows Server [ 2003-Desktop-Apps] |
| Header |
|