API Tip

Obtain Battery Information

 Programs that run on the laptops depend on the battery life. Let's say a program performs some crucial operation that requires some time to complete and battery fully dischargers or enters a critical stage and the system shuts down. What happens to your program and its data? Program might still be there, but data more than likely gets lost. To prevent that kind of situations, it becomes quite useful to be able to determine battery parameters right from your application. I'll show you how to do jsut that in this api tip.

Well first of all let's look at the API calls you have to make. The function i'm using is GetSystemPowerStatus. Here is the declaration (public):

Public Declare Function GetSystemPowerStatus Lib "kernel32" (lpSystemPowerStatus As SYSTEM_POWER_STATUS) As Long

As you can see, this function uses SYSTEM_POWER_STATUS structure which has to be declared like this:

Public Type SYSTEM_POWER_STATUS
    ACLineStatus As Byte
    BatteryFlag As Byte
    BatteryLifePercent As Byte
    Reserved1 As Byte
    BatteryLifeTime As Long
    BatteryFullLifeTime As Long
End Type

That's all API declarations you need. 

Now let's see how to obtain all this battery information. Start a new Visual Basic EXE Project. Add a command button and name it cmdPowerStatus. Also add a text box and name it txtStatus. Change Mutliline property of txtStatus text box to True. txtStatus text box will be our information output screen. All the statistics of your battery will go into this text box after you click cmdPowerStatus. Here is all the code of the main form, including API function and structure declarations:

Private Declare Function GetSystemPowerStatus Lib "kernel32" (lpSystemPowerStatus As SYSTEM_POWER_STATUS) As Long

Private Type SYSTEM_POWER_STATUS
    ACLineStatus As Byte
    BatteryFlag As Byte
    BatteryLifePercent As Byte
    Reserved1 As Byte
    BatteryLifeTime As Long
    BatteryFullLifeTime As Long
End Type

Private Sub cmdPowerStatus_Click()

   Dim rc As Long
   Dim sps As SYSTEM_POWER_STATUS
   Dim strOutput As String

   rc = GetSystemPowerStatus(sps) 'loads the info into sps structure

   If rc <> 0 Then ' if api function was succesful

   'determine AC Line Status
       Select Case sps.ACLineStatus
           Case 0:
               strOutput = " ACLineStatus: Offline" & vbCrLf
           Case 1:
               strOutput = " ACLineStatus: Online" & vbCrLf
           Case 255:
               strOutput = " ACLineStatus: Unknown" & vbCrLf
      End Select

      txtStatus.Text = txtStatus.Text & strOutput 'update the text box with info

     'determine Battery level
     Select Case sps.BatteryFlag
           Case 1:
                strOutput = " Battery charge status: High" & vbCrLf
           Case 2:
                strOutput = " Battery charge status: Low" & vbCrLf
           Case 4:
                strOutput = " Battery charge status: Critical" & vbCrLf
           Case 8: Case 9:
                strOutput = " Battery charge status: Charging" & vbCrLf
           Case 128:
                strOutput = " Battery charge status: No Battery" & vbCrLf
           Case 255:
                strOutput = " Battery charge status: Unknown" & vbCrLf
           Case Else:
                strOutput = " Battery charge (default): " & sps.BatteryFlag & vbCrLf
      End Select

      txtStatus.Text = txtStatus.Text & strOutput ' again update the info

      'determine percentage of power left
      If sps.BatteryLifePercent <> 255 Then
          strOutput = " Percentage: " & sps.BatteryLifePercent & "%" & vbCrLf
      Else
          strOutput = " Percentage: Unknown & vbCrLf"
      End If

      txtStatus.Text = txtStatus.Text & strOutput 'update

      'full battery capacity
      If sps.BatteryFullLifeTime <> -1 Then
           strOutput = " Full charge life time: " & sps.BatteryFullLifeTime & vbCrLf
      Else
           strOutput = " Full charge life time: Unknown" & vbCrLf
      End If

       txtStatus.Text = txtStatus.Text & strOutput

      'current battery charge remaining
      If sps.BatteryLifeTime <> -1 Then
            strOutput = " Current charge life time: "
            strOutput = strOutput & sps.BatteryLifeTime \ 3600 & ":" 'calculate the time
            strOutput = strOutput & (sps.BatteryLifeTime - (sps.BatteryLifeTime \ 3600) * 3600) \ 60
      Else
            strOutput = " Current charge life time: Unknown" & vbCrLf
      End If
      txtStatus.Text = txtStatus.Text & strOutput

Else ' if api function was unsuccesful
       MsgBox "Battery information couldn't be obtained!", vbCritical, "Error"
End If

End Sub

The main code is inside Sub cmdPowerStatus_Click(). To describe it in a short way, you call a GetSystemPowerStatus functiontion and pass SYSTEM_POWER_STATUS structure to it so it can be filled with battery stats. Once the function returns, you check each member of SYSTEM_POWER_STATUS for different information by using Select Case statements.  

Good luck and be sure to save your work before you mess around with Windows (r) API.