CodePPC - Programmez votre Pocket PC

Le premier site francophone dédié au développement Pocket PC

Comment lire les informations concernant les batteries de votre machine ?

Auteur

Stéphane Sibué

Date

12 septembre 2004

Lorsqu'on développe pour une machine mobile, comme un Pocket PC ou un Smartphone par exemple, il peut être parfois judiciueux de connaître l'état de la batterie de l'appareil. Cet état peut vous permettre de faire des choix. Si par exemple vous ne devez exécuter une opération QUE lorsque l'appareil est connecté à une source d'alimentation il vous faut un moyen pour obtenir cette information.

Dans le Compact Framework, rien concernant la batterie

Inutile de chercher dans les classes du Compact Framework, il n'y a rien qui parle de près ou de loin de la batterie. Donc, comme toujours dans ces cas là, il faut aller chercher les outils plus profondément dans les API du système....

Le système connaît cette info, allons la lui demander grâce à la bonne API

La fonction "GetSystemPowerStatusEx" du système permet de récupérer les informations dont nous avons besoin pour tout connaître de l'état de nos si précieuses batteries. Je dis bien NOS précieuses batteries car le système sait gérer ce qu'il appelle la batterie principale et aussi la batterie de sauvegarde, celle qui est mise à contribution quand justement on change la batterie principale afin de ne pas perdre de données.

Voici ce que nous dit l'aide de eVC++ concernant la fonction "GetSystemPowerStatusEx" :

GetSystemPowerStatusEx

This function retrieves the power status of the system. The status indicates whether the system is running on AC or DC power, whether or not the batteries are currently charging, and the remaining life of main and backup batteries.

BOOL GetSystemPowerStatusEx(
PSYSTEM_POWER_STATUS_EX pstatus,
BOOL fUpdate );

Parameters

pstatus
[out] Pointer to the SYSTEM_POWER_STATUS_EX structure receiving the power status information.

fUpdate
[in] If this Boolean is set to TRUE, GetSystemPowerStatusEx gets the latest information from the device driver, otherwise it retrieves cached information that may be out-of-date by several seconds.
Return Values
This function returns TRUE if successful; otherwise, it returns FALSE.

Remarks
The GetSystemPowerStatusEx function is not supported for emulation.

Requirements
Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later Winbase.h
Pocket PC 2002 Windows CE OS 3.0 Winbase.h Winbase.h coredll.lib
Pocket PC Windows CE OS 3.0 Winbase.h Header Link to

Note This information applies to the version of the operating system as provided by Microsoft. Actual implementation is determined by the original equipment manufacturer (OEM) and some devices may not support this function.

On se rend toute de suite compte que cette fonction stocke les informations dans la structure SYSTEM_POWER_STATUS_EXE, dont voici le descriptif :

SYSTEM_POWER_STATUS_EX
This structure contains information about the power status of the system.

typedef struct _SYSTEM_POWER_STATUS_EX {
BYTE ACLineStatus;
BYTE BatteryFlag;
BYTE BatteryLifePercent;
BYTE Reserved1;
DWORD BatteryLifeTime;
DWORD BatteryFullLifeTime;
BYTE Reserved2;
BYTE BackupBatteryFlag;
BYTE BackupBatteryLifePercent;
BYTE Reserved3;
DWORD BackupBatteryLifeTime;
DWORD BackupBatteryFullLifeTime;
} SYSTEM_POWER_STATUS_EX, *PSYSTEM_POWER_STATUS_EX, *LPSYSTEM_POWER_STATUS_EX;

Members

ACLineStatus
AC power status. It is one of the following values: Value Description
0 Offline
1 Online
255 Unknown status

All other values are reserved.

BatteryFlag
Battery charge status. It can be a combination of the following values: Value Description
1 High
2 Low
4 Critical
8 Charging
128 No system battery
255 Unknown status

All other values are reserved.

BatteryLifePercent
Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if status is unknown. All other values are reserved.

Reserved1
Reserved; set to zero.

BatteryLifeTime
Number of seconds of battery life remaining, or 0xFFFFFFFF if remaining seconds are unknown.

BatteryFullLifeTime
Number of seconds of battery life when at full charge, or 0xFFFFFFFF if full lifetime is unknown.

Reserved2
Reserved; set to zero.

BackupBatteryFlag
Backup battery charge status. It is one of the following values: BATTERY_FLAG_HIGH
BATTERY_FLAG_CRITICAL
BATTERY_FLAG_CHARGING
BATTERY_FLAG_NO_BATTERY
BATTERY_FLAG_UNKNOWN
BATTERY_FLAG_LOW

BackupBatteryLifePercent
Percentage of full backup battery charge remaining. Must be in the range 0 to 100, or BATTERY_PERCENTAGE_UNKNOWN.

Reserved3
Reserved; set to zero

BackupBatteryLifeTime
Number of seconds of backup battery life remaining, or BATTERY_LIFE_UNKNOWN if remaining seconds are unknown.

BackupBatteryFullLifeTime
Number of seconds of backup battery life when at full charge, or BATTERY_LIFE_UNKNOWN if full lifetime is unknown.

Etape n°1, traduire la structure C en structure VB.NET

Dans le cas de cette structure il n'y a rien de bien compliqué, il faut juste utiliser les bons types :

<StructLayout(LayoutKind.Sequential)> Private Structure SYSTEM_POWER_STATUS_EX

Public ACLineStatus As Byte
Public BatteryFlag As Byte
Public BatteryLifePercent As Byte
Public Reserved1 As Byte
Public BatteryLifeTime As Int32
Public BatteryFullLifeTime As Int32
Public Reserved2 As Byte
Public BackupBatteryFlag As Byte
Public BackupBatteryLifePercent As Byte
Public Reserved3 As Byte
Public BackupBatteryLifeTime As Int32
Public BackupBatteryFullLifeTime As Int32

End Structure

Etape n°2, déclarer les différentes constantes

Il y a toute une série de constantes à déclarer qui vont rendre notre code bien plus simple à écrire :

Private Const ACLineStatus_Offline = 0
Private Const ACLineStatus_Online = 1
Private Const ACLineStatus_UnknownStatus = 255

Private Const BatteryFlag_High = 1
Private Const BatteryFlag_Low = 2
Private Const BatteryFlag_Critical = 4
Private Const BatteryFlag_Charging = 8
Private Const BatteryFlag_NoSystemBattery = 128
Private Const BatteryFlag_UnknownStatus = 255

Etape n°3, déclarer la fonction magique !

Là aussi, rien de bien sorcier, il faut bien avoir à l'esprit que l'on passe en paramètre l'adresse d'une structure pour que la fonction y stocke les informations concernant les batteries.... donc le mot clé ByVal doit être remplacé par ByRef pour ce paramètre, c'est le seul piège.

Private Declare Function GetSystemPowerStatusEx Lib "coredll.dll" (ByRef pstatus As SYSTEM_POWER_STATUS_EX) As Boolean

La fonction nous retournera la valeur booléenne TRUE si elle réussit, et FALSE (vous l'aviez deviné) en cas d'échec. Si vous l'utilisez avec l'émulateur vous obtiendrez toujours FALSE car elle ne veut rien dire dans ce contexte.

Exemple d'utilisation

Voici un petit code qui illustre l'utilisation de cette fonction. Le rôle de ce petit bout de code est d'afficher à intervalle régulier (c'est en fait du code qui est appellé par l'événement "Ticks" d'un Timer) dans une Listbox les différentes valeurs retournées par la fonction "GetSystemPowerStatusEx" :

LST_Infos.Items.Clear()

Dim wStatus As SYSTEM_POWER_STATUS_EX

If GetSystemPowerStatusEx(wStatus) Then
 
 With LST_Infos.Items
 
  Select Case wStatus.ACLineStatus

    Case ACLineStatus_Offline
     .Add("ACLineStatus=Offline")

    Case ACLineStatus_Online
     .Add("ACLineStatus=Online")

    Case ACLineStatus_UnknownStatus
     .Add("ACLineStatus=UnknowStatus")

   End Select

   .Add("")

   Select Case wStatus.BatteryFlag

     Case BatteryFlag_Charging
      .Add("BatteryFlag=Charging")

     Case BatteryFlag_Critical
      .Add("BatteryFlag=Critical")

     Case BatteryFlag_High
      .Add("BatteryFlag=High")

     Case BatteryFlag_Low
      .Add("BatteryFlag=Low")

     Case BatteryFlag_NoSystemBattery
      .Add("BatteryFlag=NoSystemBattery")

     Case BatteryFlag_UnknownStatus
      .Add("BatteryFlag=UnknownStatus")

    End Select

    .Add("BatteryLifePercent=" & wStatus.BatteryLifePercent)
    .Add("BatteryLifeTime=" & wStatus.BatteryLifeTime)
    .Add("BatteryFullLifeTime=" & wStatus.BatteryFullLifeTime)


  End With

End If

Vous pouvez télécharger le projet VB.NET correspondant à cet article si vous le souhaitez

Sources VB.NET de cet article

Conclusion

Une fois de plus, une certaine connaissance du système Windows CE est nécessaire pour profiter de certaines fonctions qui, pour le moment, ne sont pas incluses d'office dans le Compact Framework. Pour les plus réfractaires aux API et autres gentillesses du système, CodePPC est là !

Pour info, le code présenté dans cet article fonctionne aussi pour Smartphone 2003.

Stéphane Sibué