Programmierung > Delphi > Batterie > Status

Status der Batterie

  • Beschreibung
  • Control Code IOCTL_BATTERY_QUERY_STATUS
  • BATTERY_WAIT_STATUS
  • BATTERY_STATUS
  • Funktion in Delphi 7
  • Download
  • Links
  • Beschreibung

    Mit dem Controlcode IOCTL_BATTERY_QUERY_STATUS erhält man den aktuellen Zustand der Batterie.

    Control Code IOCTL_BATTERY_QUERY_STATUS

    Die c++-Definition im NSDN Windows Dev Center:

    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
    );
    
    

    hDevice: Das Handle, welches im Kapitel Handle ermittelt wurde.

    dwIoControlCode: Der Controlcode für die Operation.

    lpInBuffer: Ein Zeiger auf den Speicher mit der Datenstuktur BATTERY_WAIT_STATUS, welche die Bedingungen, unter denen der Batteriestatus abgerufen werden soll, enthält.

    nInBufferSize: Die Größe der Datenstruktur in Byte.

    lpOutBuffer: Der Zeiger auf den Rückgabepuffer, welcher die Datenstruktur BATTERY_STATUS enthält.

    nOutBufferSize: Die Größe des Rückgabepuffers.

    lpBytesReturned: Ein Zeiger auf einen Wert, der angibt, wieviel Daten zurückgegben wurden. War der Rückgaberpuffer zu klein ist der Wert 0 und GetLastError gibt den Fehlerwert ERROR_INSUFFICIENT_BUFFER zurück. Wenn die Overlapped Struktur nicht verwendet wird, darf dieser nicht 0 sein.

    lpOverlapped: Ein Zeiger auf die Overlapped Struktur. Sie kann nur vorhanden sein, wenn das Gerät mit dem Flag FILE_FLAG_OVERLAPPED geöffnet wurde. Dies ist hier nicht der Fall.

    Wurde die Operation fehlerfrei durchgeführt ist der Rückgabewert 0.

    Die Funktion ist in Delphi in der Unit Windows deklariert.

    Der Controlcode IOCTL_BATTERY_QUERY_STATUS ist in der batclass.h definiert:

    #define FILE_DEVICE_BATTERY   0x00000029
     
    #define IOCTL_BATTERY_QUERY_STATUS \
        CTL_CODE(FILE_DEVICE_BATTERY,0x13,METHOD_BUFFERED,FILE_READ_ACCESS)
    
    const
      FILE_DEVICE_BATTERY = $00000029;
      FILE_READ_ACCESS    = $0001;
      METHOD_BUFFERED     = $0000;
    
    const
      IOCTL_BATTERY_QUERY_STATUS = (FILE_DEVICE_BATTERY shl 16 or
                                    FILE_READ_ACCESS shl 14 or
                                    $13 shl 2 or
                                    METHOD_BUFFERED);
    

    BATTERY_WAIT_STATUS

    Die Struktur enthält die Batterieinformationen und die c++-Definition im NSDN Windows Dev Center lautet:

    typedef struct _BATTERY_WAIT_STATUS {
      ULONG BatteryTag;
      ULONG Timeout;
      ULONG PowerState;
      ULONG LowCapacity;
      ULONG HighCapacity;
    } BATTERY_WAIT_STATUS, *PBATTERY_WAIT_STATUS;
    

    BatteryTag: Der aktuelle Batterie-Tag für die Batterie, welcher im Kapitel Tag ermittelt wurde. Wenn dieser Wert nicht mit dem aktuellen Tag der Batterie übereinstimmt, wird die Anfrage mit ERROR_FILE_NOT_FOUND abgeschlossen.

    Timeout: Die Zeit in Millisekunden, welche gewartet wird. Ein Wert von -1 gibt an, dass auf unbestimmte Zeit gewartet wird, damit die Bedingungen erfüllt sind. Ein Wert von 0 gibt an, dass die angeforderte Batterieinformation sofort zurückgegeben werden soll, unabhängig von den anderen Bedingungen.

    PowerState: Statusbits, welche den Zustand der Batterie angeben. Identisch mit dem PowerState der BATTERY_STATUS-Struktur.

    Konstante Wert Beschreibung
    BATTERY_CHARGING 0x00000004 Indicates that the battery is currently charging.
    BATTERY_CRITICAL 0x00000008 Indicates that battery failure is imminent. See the Remarks section for more information.
    BATTERY_DISCHARGING 0x00000002 Indicates that the battery is currently discharging.
    BATTERY_POWER_ON_LINE 0x00000001 Indicates that the battery has access to AC power..

    LowCapacity: Die gegenwärtige Batteriekapazität. Der Wert ist identisch mit Capacity in der Datenstruktur BATTERY_STATUS.

    HighCapacity: Die gegenwärtige Batteriekapazität. Der Wert ist identisch mit Capacity in der Datenstruktur BATTERY_STATUS.

    Die Struktur in Delphi:

    type
      _BATTERY_WAIT_STATUS =
      record
        BatteryTag   : ULONG;
        Timeout      : ULONG;
        PowerState   : ULONG;
        LowCapacity  : ULONG;
        HighCapacity : ULONG;
      end;
      TBATTERY_WAIT_STATUS = _BATTERY_WAIT_STATUS;
      PBATTERY_WAIT_STATUS = ^_BATTERY_WAIT_STATUS;
    

    BATTERY_STATUS

    Die Struktur enthält die Batterieinformationen und die c++-Definition im NSDN Windows Dev Center lautet:

    typedef struct _BATTERY_STATUS {
      ULONG PowerState;
      ULONG Capacity;
      ULONG Voltage;
      LONG  Rate;
    } BATTERY_STATUS, *PBATTERY_STATUS;
    

    PowerState: Statusbits, welche den Zustand der Batterie angeben. Identisch mit dem PowerState der BATTERY_STATUS-Struktur.

    Konstante Wert Beschreibung
    BATTERY_CHARGING 0x00000004 Zeigt an, dass die Batterie gerade geladen wird.
    BATTERY_CRITICAL 0x00000008 Zeigt an, dass ein Batteriefehler unmittelbar bevorsteht.
    BATTERY_DISCHARGING 0x00000002 Zeigt an, dass die Batterie gerade entladen wird.
    BATTERY_POWER_ON_LINE 0x00000001 Zeigt an, dass die Batterie am Netz angeschlossen ist.

    Capacity: Die aktuelle Batteriekapazität. Wenn man diese in Relation mit FullChargedCapacity aus der Struktur BATTERY_INFORMATION setzt, kann sie für eine Füllstandsanzeige nutzten. Wenn die Kapazität nicht verfügbar ist, ist der Wert BATTERY_UNKNOWN_CAPACITY.

    Voltage: Die aktuelle Batteriespannung in Millivolt (mv). Wenn die Spannung nicht verfügbar ist, ist der Wert BATTERY_UNKNOWN_VOLTAGE.

    Rate: Die aktuelle Auf- oder Entladung Milliwatt oder Einheiten pro Stunde. Dies richtet sich nach dem BATTERY_CAPACITY_RELATIVE-Flag von Capability der BATTERY_INFORMATION-Struktur. Eine ungleiche, positive Rate zeigt die Aufladung an. Eine negative Rate zeigt die Entladung an. Einige Batterien melden nur Entladungsraten. Wenn die Rate nicht verfügbar ist, ist der Wert BATTERY_UNKNOWN_RATE.

    Die Definition der Konstanten:

    #define BATTERY_POWER_ON_LINE             0x00000001
    #define BATTERY_DISCHARGING               0x00000002
    #define BATTERY_CHARGING                  0x00000004
    #define BATTERY_CRITICAL                  0x00000008
     
    #define BATTERY_UNKNOWN_CAPACITY          0xFFFFFFFF
     
    #define BATTERY_UNKNOWN_VOLTAGE           0xFFFFFFFF
     
    #define BATTERY_UNKNOWN_RATE              0x80000000
    

    Die Struktur und die Konstanten in Delphi

    const
      BATTERY_POWER_ON_LINE    = $00000001;
      BATTERY_DISCHARGING      = $00000002;
      BATTERY_CHARGING         = $00000004;
      BATTERY_CRITICAL         = $00000008;
     
      BATTERY_UNKNOWN_CAPACITY = $FFFFFFFF;
     
      BATTERY_UNKNOWN_VOLTAGE  = $FFFFFFFF;
     
      BATTERY_UNKNOWN_RATE     = $80000000;
     
    type
      _BATTERY_STATUS =
      record
        PowerState : ULONG;
        Capacity   : ULONG;
        Voltage    : ULONG;
        Rate       : Int64;
      end;
      TBATTERY_STATUS = _BATTERY_STATUS;
      PBATTERY_STATUS = ^_BATTERY_STATUS;
    

    Funktion in Delphi 7

    Die Abfrage ist ähnlich wie bei den Batterie-Informationen. Es kommt noch eine Auswertung hinzu. Hier nur eine kleine Demo. Es geht sicher noch schöner. Das trifft auch auf die GUI zu.

    function GetBatteryStatus(hBattery: THandle; aTag: Cardinal; out rBatStatus: TBATTERY_STATUS): Boolean;
    var
      rBatWaitStatus : TBATTERY_WAIT_STATUS;
      dwReturned     : Cardinal;
    begin
      ZeroMemory(@rBatStatus, SizeOf(TBATTERY_STATUS));
     
      ZeroMemory(@rBatWaitStatus, SizeOf(TBATTERY_WAIT_STATUS));
      rBatWaitStatus.BatteryTag := aTag;
      rBatWaitStatus.Timeout    := 1;
     
      dwReturned := 0;
     
      Result := (DeviceIoControl(hBattery,
                                 IOCTL_BATTERY_QUERY_STATUS,
                                 @rBatWaitStatus,
                                 SizeOf(TBATTERY_WAIT_STATUS),
                                 @rBatStatus,
                                 SizeOf(TBATTERY_STATUS),
                                 dwReturned,
                                 nil));
    end;
     
    ...
     
          if GetBatteryStatus(hBattery, tBattery, rBatStatus)
          then begin
            chkBQSPower.Checked     := rBatStatus.PowerState and BATTERY_POWER_ON_LINE > 0;
            chkBQSCharge.Checked    := rBatStatus.PowerState and BATTERY_CHARGING > 0;
            chkBQSDischarge.Checked := rBatStatus.PowerState and BATTERY_DISCHARGING > 0;
            chkBQSCritical.Checked  := rBatStatus.PowerState and BATTERY_CRITICAL > 0;
     
            if rBatStatus.Capacity = BATTERY_UNKNOWN_CAPACITY
            then edtBQSCapacity.Text := rsUnknown
            else edtBQSCapacity.Text := IntToStr(rBatStatus.Capacity);
     
            if rBatStatus.Voltage = BATTERY_UNKNOWN_VOLTAGE
            then edtBQSVoltage.Text := rsUnknown
            else edtBQSVoltage.Text := IntToStr(rBatStatus.Voltage);
     
            if rBatStatus.Rate = BATTERY_UNKNOWN_RATE
            then edtBQSRate.Text := rsUnknown
            else edtBQSRate.Text := IntToStr(rBatStatus.Rate);
          end;
     
    ...
    

    Download

    Demo mit Delphi 7 compiliert
    battery_status_exe.7z (155 kB) - MD5 (1kB)

    Source der Demo
    battery_status_src.7z (6 kB) - MD5 (1kB)