IOCTL_BATTERY_QUERY_TAG Steuerungscode

Ruft das aktuelle Tag des Akkus 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_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

hGeräte

Ein Handle für den Akku, aus dem das Tag abgerufen werden soll. 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_TAG .

lpInBuffer

Ein Zeiger auf einen ULONG-Eingabepuffer . Der Wert gibt die Anzahl von Millisekunden an, die gewartet werden sollen, wenn kein Akku vorhanden ist. Der Wert -1 gibt an, dass die Anforderung auf unbestimmte Zeit 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 Erfolgreicher Ausführung enthält dieser Puffer das aktuelle Akkutag, das einen beliebigen Wert mit Ausnahme 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ü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.

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 das aktuelle Tag des Akkus ab. Das Akku-Tag ist ein eindeutiger nonzero-Wert, der sich ändert, wenn die physische Batterie wieder ein- oder ausgetauscht wird oder charakteristische Änderungen durchläuft. Weitere Informationen dazu, wann sich ein Akkutag ändert, wie Sie die Änderung erkennen und wie eine Anwendung nach einem Wechsel des Akkutags vorgehen soll, finden Sie im Abschnitt Akkutagsübersicht. Wenn kein Akku vorhanden ist, wartet diese Anforderung die angegebene Zeit, und wenn noch kein Akku vorhanden ist, wird ERROR_FILE_NOT_FOUND zurückgegeben und das Akkutag auf BATTERY_TAG_INVALID festgelegt. (Weitere Informationen finden Sie unter Akkuinformationen.)

Alle Anforderungen für andere Akkuinformationen erfordern, dass der Aufrufer das entsprechende Batterietag liefert. Dadurch wird sichergestellt, dass der Aufrufer für jede Anforderung Informationen für denselben Akku erhält und dass der Aufrufer die Akkuwechsel ohne ständige Abrufe kennt.

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	Poclass.h; BatClass.h unter Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP

Siehe auch

Akkuinformationen

Steuerungscodes für die Energieverwaltung

Deviceiocontrol

IOCTL_BATTERY_QUERY_INFORMATION

IOCTL_BATTERY_QUERY_STATUS

IOCTL_BATTERY_SET_INFORMATION