IOCTL _ BATTERY _ QUERY _ INFORMATION-Steuerungscode

Ruft eine Vielzahl von Informationen für den Akku 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_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

hDevice

Ein Handle für den Akku, über den Informationen zurückgegeben werden sollen. 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 _ _ INFORMATION für diesen Vorgang.

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 somit die Größe) des Rückgabepuffers hängt von den Informationen ab, die im BATTERY _ QUERY INFORMATION _ _ LEVEL-Member der INPUT BATTERY QUERY _ _ INFORMATION-Struktur angefordert werden.

Die folgende Tabelle zeigt die Von einer bestimmten Informationsebene zurückgegebenen Daten.

Informationsebene Zurückgegebene Daten
BatteryDeviceName Mit NULL beendete Unicode-Zeichenfolge, die den Namen des Akkus angibt.
BatteryEstimatedTime Ein ULONG-Wert, der die geschätzte Akkulaufzeit in Sekunden angibt. Wenn die im AtRate-Member der BATTERY _ QUERY _ INFORMATION-Struktur bereitgestellte Entleerungsrate 0 (null) ist, basiert diese Berechnung auf der aktuellen Entleerungsrate. Wenn AtRate ungleich 0 (null) ist, ist die zurückgegebene Zeit die erwartete Laufzeit für die gegebene Rate. Wenn die geschätzte Zeit unbekannt ist (z. B. wird der Akku nicht entladen, und AtRate ist 0 (null) ), wird BATTERY UNKNOWN _ _ TIME zurückgegeben. Beachten Sie, dass dieser Wert bei einigen Akkusystemen nicht sehr genau ist. Der Wert kann je nach aktuellem Energieverbrauch stark variieren, was von der Datenträgeraktivität und anderen Faktoren beeinflusst werden kann. Es gibt keinen Benachrichtigungsmechanismus für Änderungen an diesem Wert.
BatteryGranularityInformation Ein Array variabler Länge von BATTERY _ REPORTING _ SCALE-Strukturen, das die Berichterstellungsgranularität für die Akkukapazitä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 von Einträgen, die zurückgegeben werden, beträgt vier.
BatteryInformation Eine BATTERY _ INFORMATION-Struktur.
BatteryManufactureDate EINE _ DATUMSSTRUKTUR FÜR _ DIE HERSTELLUNG VON AKKUS.
BatteryManufactureName Mit NULL beendete Unicode-Zeichenfolge, die den Namen des Herstellers des Akkus enthält.
BatterySerialNumber Mit NULL beendete Unicode-Zeichenfolge, die die Seriennummer des Akkus enthält.
BatteryTemperature Ein ULONG,das die aktuelle Temperatur des Akkus in 10-Grad-Grad-Kelvin enthält.
BatteryUniqueID Mit NULL beendete Unicode-Zeichenfolge, die den Akku eindeutig identifiziert. Dieser Wert kann zum Nachverfolgen eines bestimmten Akkus verwendet werden. Bei intelligenten Akkus ist diese ID die Verkettung des Herstellernamens, des Gerätenamens, des Herstellungsdatums und einer druckbaren Darstellung der Seriennummer. Dieser Wert soll dem Benutzer nicht angezeigt werden.

nOutBufferSize

Die Größe des Ausgabepuffers in Bytes. Abhängig von der angeforderten Informationsebene der Daten kann dies ein Puffer mit unterschiedlicher Größe sein.

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ü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.

Einige Informationen zu Akkus sind optional oder für einige Akkus bedeutungslos. Wenn der angeforderte Datentyp für den aktuellen Akku nicht verfügbar ist, wird ERROR _ INVALID _ FUNCTION zurückgegeben.

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.

Bemerkungen

Diese Akku-IOCTL ruft eine Vielzahl von Informationen für den Akku ab. Die Eingabeparameterstruktur BATTERY _ QUERY _ INFORMATIONgibt an, welche Art von Informationen zurückgegeben werden sollen und wann die Akkuinformationen zurückgegeben werden sollen. Der Datentyp und der Inhalt des Ausgabepuffers variieren basierend auf den angeforderten Daten.

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

Weitere Informationen

Akkuinformationen

Steuerungscodes für die Energieverwaltung

Deviceiocontrol

_ _ AKKUABFRAGEINFORMATIONEN

_ _ AKKUBERICHTSSKALIEREN

IOCTL _ BATTERY _ QUERY _ STATUS

IOCTL _ BATTERY _ QUERY _ TAG

_IOCTL-AKKUSATZINFORMATIONEN _ _