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

 // All rights reserved.

 // This component and the accompanying materials are made available

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

 // which accompanies this distribution, and is available

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

 //

 // Initial Contributors:

 // Nokia Corporation - initial contribution.

 //

 // Contributors:

 //

 // Description:

 //

 #ifndef HWRMPOWER_H_

 #define HWRMPOWER_H_

 // INCLUDES

 #include <e32base.h>

 #include <e32cmn.h> 

 // CONSTANTS

 // FORWARD DECLARATIONS

 class CHWRMPowerImpl;

 class MHWRMBatteryPowerObserver;

 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

 class MHWRMBatteryChargingStatusObserver;

 class MHWRMBatteryChargingCurrentObserver;

 class MHWRMBatteryFullChargingTimeObserver;

 #endif //SYMBIAN_HWRM_EXTPOWERINFO

 /**

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

 * ability to request detailed information regarding the battery 

 * capacity, voltage and current consumption.

 *

 * The API consists of the classes CHWRMPower, MHWRMBatteryConsumptionObserver

 * and MHWRMBatteryVoltageObserver. If the client requires periodical measurements

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

 * of the MHWRMBatteryConsumptionObserver and/or MHWRMBatteryVoltageObserver

 * implementing class for the NewL() method.

 *

 * Usage:

 *

 * @code

 * #include <hwrmpower.h> 

 *

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

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

 * // the calling object implements  both interfaces.

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

 *

 * // Get battery info.

 * TRequestStatus& status;

 * TBatteryConsumptionData batteryConsumptionData;

 * power->GetBatteryInfo(status, batteryConsumptionData); 

 * 

 * User::WaitForRequest(status);

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

 * 

 * // Start receiving periodical voltage measurements.

 * TRequestStatus& statusStart;

 * TIntervalMultiple intervalMultiple = EThreeTimesBaseTimeInterval;

 * power->StartAverageVoltageReporting(statusStart, intervalMultiple);

 *  

 * User::WaitForRequest(statusStart);

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

 * 

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

 * // of the MHWRMBatteryVoltageObserver interface is called.

 *  

 * // Stop receiving measurements when done

 * power->StopAverageVoltageReportingL(); 

 *

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

 * delete power;

 * @endcode

 *

 * @publishedAll

 * @released

 */

 NONSHARABLE_CLASS(CHWRMPower) : public CBase

     {            

 public:

 	/**

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

 	*/ 

 	struct TBatteryVoltageData 

 		{

 		TInt iRemainingVoltage;

 		TInt iMaximumVoltage;

 		TInt iMinimumVoltage;

 		};

 	/**

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

 	*/ 

     struct TBatteryConsumptionData 

 	 	{

 	 	TInt iNominalCapacity;

 	 	TInt iRemainingCapacity;

 	 	TInt iRemainingPercentageCapacity;

 	 	};

     /**

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

     	*/

     struct TBatteryPowerMeasurementData 

         {

         TInt iAverageVoltage;

         TInt iAverageCurrent;

         };  

 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

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

     enum TBatteryChargerType 

         { 

         EBatteryChargerUnKnown = 0, 

         EBatteryChargerDedicated = 1, 

         EBatteryChargerUsbDedicated = 2,

         EBatteryChargerUsbHost = 3 

         };

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

     enum TBatteryChargingStatus

         {

         EChargingStatusError              = -1, 

         EChargingStatusNotConnected       = 0,  

         EChargingStatusCharging           = 1,  

         EChargingStatusNotCharging        = 2,  

         EChargingStatusAlmostComplete     = 3,  

         EChargingStatusChargingComplete   = 4,  

         EChargingStatusChargingContinued  = 5  

         };

     /* Used to stop the ongoing charging notification. 

      * EChargingNotifierAll used to stop charging current and charging 

      * time notifications. */

     enum TBatteryChargingNotifier

         {

         EChargingNotifierAll = 0,

         EChargingNotifierChargingCurrent = 1,

         EChargingNotifierBatteryFullChargingTime = 2

         };

 #endif //SYMBIAN_HWRM_EXTPOWERINFO

 public:	

     IMPORT_C ~CHWRMPower();

     IMPORT_C static CHWRMPower* NewL();

     IMPORT_C static CHWRMPower* NewLC();

 public: // New functions

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

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

     IMPORT_C void GetBaseTimeIntervalL(TInt &aBaseTimeInterval);

     IMPORT_C TInt SetPowerReportObserver(MHWRMBatteryPowerObserver* aPowerReportCallback);

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

     IMPORT_C void StopAveragePowerReportingL(); 

 #ifdef SYMBIAN_HWRM_EXTPOWERINFO 

     IMPORT_C TInt GetBatteryChargerType(TBatteryChargerType& aChargerType);

     IMPORT_C TInt GetBatteryChargingStatus(TBatteryChargingStatus& aChargingStatus);

     IMPORT_C TInt SetBatteryChargingObserver(

              MHWRMBatteryChargingStatusObserver*   aChargingStatusCallback,

              MHWRMBatteryChargingCurrentObserver*     aChrgCurrentCallback,

              MHWRMBatteryFullChargingTimeObserver* aChrgTimeCallback);

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

     IMPORT_C TInt NotifyBatteryFullChargingTime(TRequestStatus& aStatus);

     IMPORT_C void StopChargingNotificationL(TBatteryChargingNotifier aNotifier);

 #endif //SYMBIAN_HWRM_EXTPOWERINFO

 private:

 	void ConstructL();

 private:

 	CHWRMPowerImpl* iPowerImpl;	

     };

 /**

 * A callback interface for power measurements reporting.

 *

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

 * it needs to derive a class from the MHWRMBatteryPowerObserver interface

 * and implement the PowerMeasurement() method. 

 * 

 * A callback object header example:

 *

 * @code 

 * // INCLUDES

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

 *

 * class CTest : public CBase, 

 *               public MHWRMBatteryPowerObserver    

 *    {

 *    public:

 *        CTest();

 *        ~CTest();

 *                       

 *        void ConstructL();

 *        static CTest* NewL();

 *                

 *        // from MHWRMBatteryPowerObserver

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

 *

 *    private:

 *        CHWRMPower* iPower;

 *    };

 * @endcode

 *

 * A callback method implementation example:

 *

 * @code

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

 *    {

 *  	 if (aErrorCode == KErrNone)

 *	 	{

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

 *		}

 *	 else

 *		{

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

 *		}

 *    }

 * @endcode

 *

 * @publishedAll

 * @released

 */

 class MHWRMBatteryPowerObserver

     {

 public:

     /** 

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

     *

     * @param aErr Error code. 

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

     */

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

     };

 #ifdef SYMBIAN_HWRM_EXTPOWERINFO

 /**

 * A callback interface for charging status change.

 *

 * If the client requires charging status change notofication,

 * it needs to derive a class from the MHWRMBatteryChargingStatusObserver interface

 * and implement the ChargingStatusChange() method. 

 * 

 * A callback object header example:

 *

 * @code 

 * // INCLUDES

 class CTest : public CBase, 

               public MHWRMBatteryChargingStatusObserver

    {

     public:

         CTest();

         ~CTest();

         void ConstructL();

         static CTest* NewL();

         // from MHWRMBatteryChargingStatusObserver

         virtual void ChargingStatusChange( Tint aErrCode,

                    CHWRMPower::TBatteryChargingStatus aChrgStatus);

    };

 * @endcode   

 * A callback method implementation example:

 *

 * @code

 void CTest:: ChargingStatusChange(TInt aErrorCode,

                           CHWRMPower::TBatteryChargingStatus aChrgStatus);

    {

       if (aErrorCode == KErrNone)

       {

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

       }

      else

       {

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

       }

    }

 * @endcode  

 *

 * @publishedAll

 * @released

 */

 class MHWRMBatteryChargingStatusObserver

     {

 public:

     /** 

     * Called when a charging status is changed.

     *

     * @param aErrCode Error code. 

     * @param aChrgStatus Charging status.

     */

     virtual void ChargingStatusChange( TInt aErrCode,

                                       CHWRMPower::TBatteryChargingStatus aChrgStatus)=0;

 };

 /**

 * A callback interface for charging current measurements reporting.

 *

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

 * it needs to derive a class from the MHWRMBatteryChargingCurrentObserver interface

 * and implement the AverageChargingCurrentChange() method. 

 * 

 * A callback object header example:

 *

 * @code 

 * // INCLUDES

 class CTest : public CBase, 

               public MHWRMBatteryChargingStatusObserver

    {

     public:

         CTest();

         ~CTest();

         void ConstructL();

         static CTest* NewL();

         // from MHWRMBatteryChargingStatusObserver

         virtual void AverageChargingCurrentRateChange(

                            TInt aErrCode, TInt aMeasurement);

    };

 * @endcode   

 * A callback method implementation example:

 *

 * @code

 // Notification handler

 void CTest::ChargingCurrentChange(

                            TInt aErrorCode, TInt aMeasurement)

   {

       if (aErrorCode == KErrNone)

       {

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

       }

      else

       {

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

       }

    }

 * @endcode  

 *

 * @publishedAll

 * @released

 */

 class MHWRMBatteryChargingCurrentObserver

     {

    /** 

     * Called when a charging current measurement value is received.

     *

     * @param aErrCode Error code. 

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

              Valid only when aErr == KErrNone.

     */

     public:

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

     };

 /**

 * A callback interface for remaining charging time notification.

 *

 * If the client requires remaining charging time notification,

 * it needs to derive a class from the MHWRMBatteryFullChargingTimeObserver interface

 * and implement the BatteryFullChargingTimeChange() method. 

 * 

 * A callback object header example:

 *

 * @code 

 * // INCLUDES

 class CTest : public CBase, 

               public MHWRMBatteryFullChargingTimeObserver

    {

     public:

         CTest();

         ~CTest();

         void ConstructL();

         static CTest* NewL();

         // from MHWRMBatteryChargingStatusObserver

         virtual void BatteryFullChargingTimeChange(

                            TInt aErrCode, TInt aMeasurement);

    };

 * @endcode   

 * A callback method implementation example:

 *

 * @code

 // Notification handler

 void CTest::BatteryFullChargingTimeChange(

                               TInt aErrorCode, TUint aTime)

    {

       if (aErrorCode == KErrNone)

       {

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

       }

      else

       {

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

       }

    }

 * @endcode  

 *

 * @publishedAll

 * @released

 */

 class MHWRMBatteryFullChargingTimeObserver

     {

    /** 

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

     *

     * @param aErrCode Error code. 

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

              Valid only when aErrCode == KErrNone.

     */

     public:

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

     };

 #endif //SYMBIAN_HWRM_EXTPOWERINFO

 #endif /*HWRMPOWER_H_*/

 // End of File