1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #ifndef HWRMPOWER_H_

    17 #define HWRMPOWER_H_

    18 

    19 // INCLUDES

    20 #include <e32base.h>

    21 #include <e32cmn.h> 

    22 

    23 // CONSTANTS

    24 

    25 // FORWARD DECLARATIONS

    26 

    27 class CHWRMPowerImpl;

    28 class MHWRMBatteryPowerObserver;

    29 

    30 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

    31 class MHWRMBatteryChargingStatusObserver;

    32 class MHWRMBatteryChargingCurrentObserver;

    33 class MHWRMBatteryFullChargingTimeObserver;

    34 #endif //SYMBIAN_HWRM_EXTPOWERINFO

    35 

    36 /**

    37 * HW Resource Manager Power API is a library API providing the 

    38 * ability to request detailed information regarding the battery 

    39 * capacity, voltage and current consumption.

    40 *

    41 * The API consists of the classes CHWRMPower, MHWRMBatteryConsumptionObserver

    42 * and MHWRMBatteryVoltageObserver. If the client requires periodical measurements

    43 * of the Average Voltage and/or Average Consumption, it should also provide callback pointer

    44 * of the MHWRMBatteryConsumptionObserver and/or MHWRMBatteryVoltageObserver

    45 * implementing class for the NewL() method.

    46 *

    47 * Usage:

    48 *

    49 * @code

    50 * #include <hwrmpower.h> 

    51 *

    52 * // A CHWRMPower instance can be created by using NewL() or NewLC() methods. 

    53 * // Periodical measurements are required so callbacks are provided. Assume 

    54 * // the calling object implements  both interfaces.

    55 * CHWRMPower* power = CHWRMPower::NewL(this, this);

    56 *

    57 * // Get battery info.

    58 * TRequestStatus& status;

    59 * TBatteryConsumptionData batteryConsumptionData;

    60 * power->GetBatteryInfo(status, batteryConsumptionData); 

    61 * 

    62 * User::WaitForRequest(status);

    63 * User::LeaveIfError(status.Int());

    64 * 

    65 * // Start receiving periodical voltage measurements.

    66 * TRequestStatus& statusStart;

    67 * TIntervalMultiple intervalMultiple = EThreeTimesBaseTimeInterval;

    68 * power->StartAverageVoltageReporting(statusStart, intervalMultiple);

    69 *  

    70 * User::WaitForRequest(statusStart);

    71 * User::LeaveIfError(statusStart.Int());

    72 * 

    73 * // Measurements are being when the ProcessVoltageMeasurement() method 

    74 * // of the MHWRMBatteryVoltageObserver interface is called.

    75 *  

    76 * // Stop receiving measurements when done

    77 * power->StopAverageVoltageReportingL(); 

    78 *

    79 * // To clean up, delete the created object:

    80 * delete power;

    81 * @endcode

    82 *

    83 * @publishedAll

    84 * @released

    85 */

    86 NONSHARABLE_CLASS(CHWRMPower) : public CBase

    87     {            

    88 public:

    89 	

    90 	/**

    91 	* Data structure used to retreive data from a call to GetBatteryVoltageInfo

    92 	*/ 

    93 	struct TBatteryVoltageData 

    94 		{

    95 		TInt iRemainingVoltage;

    96 		TInt iMaximumVoltage;

    97 		TInt iMinimumVoltage;

    98 		};

    99 		

   100 	/**

   101 	* Data structure used to retreive data from a call to GetBatteryInfo

   102 	*/ 

   103     struct TBatteryConsumptionData 

   104 	 	{

   105 	 	TInt iNominalCapacity;

   106 	 	TInt iRemainingCapacity;

   107 	 	TInt iRemainingPercentageCapacity;

   108 	 	};

   109     

   110     /**

   111     	* Data structure used to retreive data from a call to GetBatteryInfo

   112     	*/

   113     struct TBatteryPowerMeasurementData 

   114         {

   115         TInt iAverageVoltage;

   116         TInt iAverageCurrent;

   117         };  

   118 

   119 

   120 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

   121 

   122     /* The type of charger connected to the device.*/

   123     enum TBatteryChargerType 

   124         { 

   125         EBatteryChargerUnKnown = 0, 

   126         EBatteryChargerDedicated = 1, 

   127         EBatteryChargerUsbDedicated = 2,

   128         EBatteryChargerUsbHost = 3 

   129         };

   130 

   131     /* The current charging status of the device. */

   132     enum TBatteryChargingStatus

   133         {

   134         EChargingStatusError              = -1, 

   135         EChargingStatusNotConnected       = 0,  

   136         EChargingStatusCharging           = 1,  

   137         EChargingStatusNotCharging        = 2,  

   138         EChargingStatusAlmostComplete     = 3,  

   139         EChargingStatusChargingComplete   = 4,  

   140         EChargingStatusChargingContinued  = 5  

   141         };

   142 

   143     /* Used to stop the ongoing charging notification. 

   144      * EChargingNotifierAll used to stop charging current and charging 

   145      * time notifications. */

   146      

   147     enum TBatteryChargingNotifier

   148         {

   149         EChargingNotifierAll = 0,

   150         EChargingNotifierChargingCurrent = 1,

   151         EChargingNotifierBatteryFullChargingTime = 2

   152         };

   153 

   154 #endif //SYMBIAN_HWRM_EXTPOWERINFO

   155 

   156 public:	

   157 

   158     IMPORT_C ~CHWRMPower();

   159     IMPORT_C static CHWRMPower* NewL();

   160     IMPORT_C static CHWRMPower* NewLC();

   161      

   162 public: // New functions

   163 

   164 	IMPORT_C void GetBatteryInfo(TRequestStatus& aStatus, TBatteryConsumptionData& aBatteryConsumptionData);

   165     IMPORT_C void GetBatteryVoltageInfo(TRequestStatus& aStatus, TBatteryVoltageData& aBatteryVoltageData);

   166     IMPORT_C void GetBaseTimeIntervalL(TInt &aBaseTimeInterval);

   167     IMPORT_C TInt SetPowerReportObserver(MHWRMBatteryPowerObserver* aPowerReportCallback);

   168     IMPORT_C TInt StartAveragePowerReporting(TRequestStatus& aStatus, const TUint& aInterval);

   169     IMPORT_C void StopAveragePowerReportingL(); 

   170     

   171 #ifdef SYMBIAN_HWRM_EXTPOWERINFO 

   172     

   173     IMPORT_C TInt GetBatteryChargerType(TBatteryChargerType& aChargerType);

   174     IMPORT_C TInt GetBatteryChargingStatus(TBatteryChargingStatus& aChargingStatus);

   175     IMPORT_C TInt SetBatteryChargingObserver(

   176              MHWRMBatteryChargingStatusObserver*   aChargingStatusCallback,

   177              MHWRMBatteryChargingCurrentObserver*     aChrgCurrentCallback,

   178              MHWRMBatteryFullChargingTimeObserver* aChrgTimeCallback);

   179     IMPORT_C TInt NotifyAverageChargingCurrent(TRequestStatus& aStatus, const TUint& aInterval);

   180     IMPORT_C TInt NotifyBatteryFullChargingTime(TRequestStatus& aStatus);

   181     IMPORT_C void StopChargingNotificationL(TBatteryChargingNotifier aNotifier);

   182 #endif //SYMBIAN_HWRM_EXTPOWERINFO

   183     

   184 private:

   185 

   186 	void ConstructL();

   187 	

   188 private:

   189 

   190 	CHWRMPowerImpl* iPowerImpl;	

   191     };

   192 

   193 /**

   194 * A callback interface for power measurements reporting.

   195 *

   196 * If the client requires periodical measurements of the Average Power,

   197 * it needs to derive a class from the MHWRMBatteryPowerObserver interface

   198 * and implement the PowerMeasurement() method. 

   199 * 

   200 * A callback object header example:

   201 *

   202 * @code 

   203 * // INCLUDES

   204 * #include <hwrmpower.h> // Link against HWRMPowerClient.lib.

   205 *

   206 * class CTest : public CBase, 

   207 *               public MHWRMBatteryPowerObserver    

   208 *    {

   209 *    public:

   210 *        CTest();

   211 *        ~CTest();

   212 *                       

   213 *        void ConstructL();

   214 *        static CTest* NewL();

   215 *                

   216 *        // from MHWRMBatteryPowerObserver

   217 *        virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);

   218 *

   219 *    private:

   220 *        CHWRMPower* iPower;

   221 *    };

   222 * @endcode

   223 *

   224 * A callback method implementation example:

   225 *

   226 * @code

   227 * void CTest::PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);

   228 *    {

   229 *  	 if (aErrorCode == KErrNone)

   230 *	 	{

   231 *		INFO_PRINTF2(_L("INFO: Power Measurement Received, averageVolatge=%d, averageCurrent=%d"),aMeasurement.iAverageVoltage, aMeasurement.iAverageCurrent);

   232 *		}

   233 *	 else

   234 *		{

   235 *		INFO_PRINTF2(_L("INFO: Power Measurement Measurement Error, error=%d"),aErr);

   236 *		}

   237 *    }

   238 * @endcode

   239 *

   240 * @publishedAll

   241 * @released

   242 */

   243 

   244 class MHWRMBatteryPowerObserver

   245     {

   246 public:

   247     /** 

   248     * Called when a Power(Voltage and Current) consumption measurement value is received.

   249     *

   250     * @param aErr Error code. 

   251     * @param aMeasurement The Average Power value calculated by the plugin. Valid only when aErr == KErrNone.

   252     */

   253 

   254     virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement)=0;   

   255     };

   256 

   257 

   258 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

   259 /**

   260 * A callback interface for charging status change.

   261 *

   262 * If the client requires charging status change notofication,

   263 * it needs to derive a class from the MHWRMBatteryChargingStatusObserver interface

   264 * and implement the ChargingStatusChange() method. 

   265 * 

   266 * A callback object header example:

   267 *

   268 * @code 

   269 * // INCLUDES

   270 class CTest : public CBase, 

   271               public MHWRMBatteryChargingStatusObserver

   272    {

   273     public:

   274         CTest();

   275         ~CTest();

   276                        

   277         void ConstructL();

   278         static CTest* NewL();

   279                 

   280         // from MHWRMBatteryChargingStatusObserver

   281         virtual void ChargingStatusChange( Tint aErrCode,

   282                    CHWRMPower::TBatteryChargingStatus aChrgStatus);

   283    };

   284 * @endcode   

   285 * A callback method implementation example:

   286 *

   287 * @code

   288 

   289 void CTest:: ChargingStatusChange(TInt aErrorCode,

   290                           CHWRMPower::TBatteryChargingStatus aChrgStatus);

   291    {

   292       if (aErrorCode == KErrNone)

   293       {

   294       INFO_PRINTF2(_L("Charging status = %d"), aChrgStatus);

   295       }

   296      else

   297       {

   298       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);

   299       }

   300    }

   301 * @endcode  

   302 *

   303 * @publishedAll

   304 * @released

   305 */

   306 class MHWRMBatteryChargingStatusObserver

   307     {

   308 public:

   309     /** 

   310     * Called when a charging status is changed.

   311     *

   312     * @param aErrCode Error code. 

   313     * @param aChrgStatus Charging status.

   314     */

   315 

   316     virtual void ChargingStatusChange( TInt aErrCode,

   317                                       CHWRMPower::TBatteryChargingStatus aChrgStatus)=0;

   318 };

   319 

   320 /**

   321 * A callback interface for charging current measurements reporting.

   322 *

   323 * If the client requires periodical measurements of the charging current measurements,

   324 * it needs to derive a class from the MHWRMBatteryChargingCurrentObserver interface

   325 * and implement the AverageChargingCurrentChange() method. 

   326 * 

   327 * A callback object header example:

   328 *

   329 * @code 

   330 * // INCLUDES

   331 class CTest : public CBase, 

   332               public MHWRMBatteryChargingStatusObserver

   333    {

   334     public:

   335         CTest();

   336         ~CTest();

   337                        

   338         void ConstructL();

   339         static CTest* NewL();

   340                 

   341         // from MHWRMBatteryChargingStatusObserver

   342         virtual void AverageChargingCurrentRateChange(

   343                            TInt aErrCode, TInt aMeasurement);

   344 

   345    };

   346 * @endcode   

   347 * A callback method implementation example:

   348 *

   349 * @code

   350 

   351 // Notification handler

   352 void CTest::ChargingCurrentChange(

   353                            TInt aErrorCode, TInt aMeasurement)

   354   {

   355       if (aErrorCode == KErrNone)

   356       {

   357       INFO_PRINTF2(_L("Charging current = %d"), aMeasurement);

   358       }

   359      else

   360       {

   361       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);

   362       }

   363    }

   364 

   365 

   366 * @endcode  

   367 *

   368 * @publishedAll

   369 * @released

   370 */

   371 

   372 class MHWRMBatteryChargingCurrentObserver

   373     {

   374    /** 

   375     * Called when a charging current measurement value is received.

   376     *

   377     * @param aErrCode Error code. 

   378     * @param aMeasurement The Average Charging current value calculated by the plugin.

   379              Valid only when aErr == KErrNone.

   380     */

   381     public:

   382         virtual void AverageChargingCurrentChange(TInt aErrCode, TInt aMeasurement)=0;

   383     };

   384 

   385 /**

   386 * A callback interface for remaining charging time notification.

   387 *

   388 * If the client requires remaining charging time notification,

   389 * it needs to derive a class from the MHWRMBatteryFullChargingTimeObserver interface

   390 * and implement the BatteryFullChargingTimeChange() method. 

   391 * 

   392 * A callback object header example:

   393 *

   394 * @code 

   395 * // INCLUDES

   396 class CTest : public CBase, 

   397               public MHWRMBatteryFullChargingTimeObserver

   398    {

   399     public:

   400         CTest();

   401         ~CTest();

   402                        

   403         void ConstructL();

   404         static CTest* NewL();

   405                 

   406         // from MHWRMBatteryChargingStatusObserver

   407         virtual void BatteryFullChargingTimeChange(

   408                            TInt aErrCode, TInt aMeasurement);

   409 

   410    };

   411 * @endcode   

   412 * A callback method implementation example:

   413 *

   414 * @code

   415 

   416 // Notification handler

   417 void CTest::BatteryFullChargingTimeChange(

   418                               TInt aErrorCode, TUint aTime)

   419    {

   420       if (aErrorCode == KErrNone)

   421       {

   422       INFO_PRINTF2(_L("Remaining charging time = %d"), aTime);

   423       }

   424      else

   425       {

   426       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);

   427       }

   428    }

   429 

   430 

   431 * @endcode  

   432 *

   433 * @publishedAll

   434 * @released

   435 */

   436 

   437 class MHWRMBatteryFullChargingTimeObserver

   438     {

   439    /** 

   440     * Called when a full charging current time measurement value is received.

   441     *

   442     * @param aErrCode Error code. 

   443     * @param aTime Time required for full charging of Battery.

   444              Valid only when aErrCode == KErrNone.

   445     */

   446 

   447     public:

   448         virtual void BatteryFullChargingTimeChange(TInt aErrCode, TUint aTime)=0;

   449     };

   450 #endif //SYMBIAN_HWRM_EXTPOWERINFO

   451 

   452 #endif /*HWRMPOWER_H_*/

   453 // End of File