S60_Platform_Power_and_Resource_Management_Example_v2_1_en.zip

S60 Platform: Power and Resource Management Example v2.1 -------------------------------------------------------- This updated C++ example application demonstrates the APIs that are available for figuring out the battery, charger, and network status. The application also demonstrates how to implement some of the power and resource management principles that have been discussed in the document S60 Platform: Effective Power and Resource Management (available at http://www.forum.nokia.com/). It is recommended that you read the document before studying the application. The updated example application has been tested to support S60 5th Edition and touch UI. ------------------------------------------------------------------------------------------ IMPLEMENTATION NOTES Some of the resource management concepts, such as the correct scoping of automatic variables, are demonstrated in the CResManagement class. Note that the functions within this class do not serve any real purpose other than providing sample coding for techniques described in the document S60 Platform: Effective Power and Resource Management. Various methods of using Active Objects to perform a long-running task are implemented in the example application to carry out a calculation. The calculation is to add together the first n numbers. Obviously, this could have been done using the formula n(n+1)/2 but, for the sake of this demonstration, the numbers are added sequentially to make it a long task. The classes of interest are CIntegerSummation and CIntegerSummationIdle. Each class uses the concept of Active Objects to gain processor time to complete a long-running task. The enumeration, SummationObserver::TSummationStage, is used to keep track of the stage the calculation has reached, that is, which integer should be added next. For this particular example, a state machine is not really necessary, but as they are commonly used in long-running tasks, the idea is demonstrated. The same task is implemented using threads in the CIntegerSummationThread class. Changes in battery strength are provided for the application using the observer class CStateVarObserver that receives the notifications. The dialog class, CSystemAgentDialog, can then display updates. In addition to battery strength, the application also monitors battery charger status and network strength. The battery charger status is obviously relevant to how much battery power is available. The reason for monitoring the network strength may not be so obvious, but it is included because at times of low network strength, the device will have to 'work harder' to complete certain tasks, such as making a phone call. One of the causes of power drainage is the mobile device�s backlight. The example contains a menu option to keep the backlight on. It is there as an exercise for developers to monitor the backlight�s effect on battery consumption. Notes on the usage of System Agent and CTelephony: -------------------------------------------------- In the original example, developed for S60 2nd Edition, the System Agent was used in retrieving the information. From S60 3rd Edition onwards, CTelephony is used. The CStateVarObserver interface of the engine class has been changed as little as possible. For example, the System Agent UIDs are still used in AppUi when constructing the CStateVarObserver objects. The values given by the System Agent are mapped to textual representations. For example, the battery status �Almost full� is used instead of showing the value 6. In S60 3rd Edition, some of the values have changed, so the mapping does not work directly. The mapping is implemented in CPowerResManContainer::ProcessStateVarChangeL. The values are: 1) Battery strength: - The first version of this example used KUidBatteryStrength where the battery strength was given as TSABatteryStrength with 3 possible values. The battery strength given by CTelephony is given as a percentage with steps of approximately 14 percentage units, meaning that the possible values are 0,14,28,...,100. In the example, these percentage units are scaled back to 0-7 in the container with the following simple code: aNewState = aNewState/14; 2) Charger status: - In S60 3rd Edition, CTelephony (CTelephony::TIndicatorV1) is used to check the charger status in StateVarObserver_3rd.cpp: if(iIndicatorV1.iIndicator & CTelephony::KIndChargerConnected) iCharger = 1; //Charger on else iCharger = 0; //Charger off 3) Network strength: - In S60 3rd Edition, the values are retrieved using CTelephony::TSignalStrengthV1 which gives the values from the range 0-7. ------------------------------------------------------------------------------------------ PREREQUISITES Symbian/C++ basics and Symbian OS key concepts. ------------------------------------------------------------------------------------------ IMPORTANT FILES/CLASSES src\StateVarObserver_3rd.cpp - The implementation of CStateVarObserver for S60 3rd Edition uses CTelephony to get the required status information. Note that the code is not bullet proof and contains a couple of TODOs for error handling. src\PowerResManContainer.cpp - Provides the simple GUI container for displaying battery, charger, and network status. src/IntegerSummationThread.cpp - Manages the creation and destruction of new threads. Thread usage is demonstrated with integer summation. src/IntegerSummationIdle.cpp - CIdle is used in integer summation. src/integerSummation.cpp - Active objects are used in integer summation. Classes: CTelephony, RSystemAgent, TSysAgentEvent, CIdle, CActive. ------------------------------------------------------------------------------------------ KNOWN ISSUES Testing on a real device is preferred since some application functionalities (such as battery status and network status) do not work in a similar way in the emulator and on a real device. ------------------------------------------------------------------------------------------ RUNNING THE EXAMPLE The application is accessed through the Options menu. The following menu items can be selected: * Change bklight mode Sets the backlight to be on all the time. * Summations > Integer Sum/Integer Sum Idle/Integer Sum Thread These three commands execute the integer summation in three different ways. * Scoping > Implemented/Not Implemented These two commands execute the same functionality which is implemented in two different ways. It demontrates the simple technique of scoping to save memory. Scoping is discussed in the document S60 Platform: Effective Power and Resource Management. * Use of TParsePtrC Executes the TParsePtrC demonstration. -------------------------------------------------------------------------------- BUILD & INSTALLATION INSTRUCTIONS The steps for building and installing the application on a device depend on the S60 platform version: --Mobile device (S60 3rd Edition) Go to /PowerResMan/group. bldmake bldfiles abld build gcce urel Go to /PowerResMan/sis. Edit the paths in PowerResMan_s60.pkg to match those in your development environment. makesis PowerResMan_s60.pkg Sign the SIS package: - See the SDK Help for information about self-signed .sis packages, or http://www.symbiansigned.com/ for information about Developer Certificates. Install the signed .sis file on an S60 3rd Edition device. - If you get a "Certificate error" during the installation of a self-signed package, check that App.Manager > Settings > Software Installation is set to All. --Emulator (WINSCW) Go to /