williamr@4: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: // All rights reserved.
williamr@4: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@4: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: //
williamr@4: // Initial Contributors:
williamr@4: // Nokia Corporation - initial contribution.
williamr@4: //
williamr@4: // Contributors:
williamr@4: //
williamr@4: // Description:
williamr@4: //
williamr@4: 
williamr@4: #ifndef HWRMPOWER_H_
williamr@4: #define HWRMPOWER_H_
williamr@4: 
williamr@4: // INCLUDES
williamr@4: #include <e32base.h>
williamr@4: #include <e32cmn.h> 
williamr@4: 
williamr@4: // CONSTANTS
williamr@4: 
williamr@4: // FORWARD DECLARATIONS
williamr@4: 
williamr@4: class CHWRMPowerImpl;
williamr@4: class MHWRMBatteryPowerObserver;
williamr@4: 
williamr@4: #ifdef SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: class MHWRMBatteryChargingStatusObserver;
williamr@4: class MHWRMBatteryChargingCurrentObserver;
williamr@4: class MHWRMBatteryFullChargingTimeObserver;
williamr@4: #endif //SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: 
williamr@4: /**
williamr@4: * HW Resource Manager Power API is a library API providing the 
williamr@4: * ability to request detailed information regarding the battery 
williamr@4: * capacity, voltage and current consumption.
williamr@4: *
williamr@4: * The API consists of the classes CHWRMPower, MHWRMBatteryConsumptionObserver
williamr@4: * and MHWRMBatteryVoltageObserver. If the client requires periodical measurements
williamr@4: * of the Average Voltage and/or Average Consumption, it should also provide callback pointer
williamr@4: * of the MHWRMBatteryConsumptionObserver and/or MHWRMBatteryVoltageObserver
williamr@4: * implementing class for the NewL() method.
williamr@4: *
williamr@4: * Usage:
williamr@4: *
williamr@4: * @code
williamr@4: * #include <hwrmpower.h> 
williamr@4: *
williamr@4: * // A CHWRMPower instance can be created by using NewL() or NewLC() methods. 
williamr@4: * // Periodical measurements are required so callbacks are provided. Assume 
williamr@4: * // the calling object implements  both interfaces.
williamr@4: * CHWRMPower* power = CHWRMPower::NewL(this, this);
williamr@4: *
williamr@4: * // Get battery info.
williamr@4: * TRequestStatus& status;
williamr@4: * TBatteryConsumptionData batteryConsumptionData;
williamr@4: * power->GetBatteryInfo(status, batteryConsumptionData); 
williamr@4: * 
williamr@4: * User::WaitForRequest(status);
williamr@4: * User::LeaveIfError(status.Int());
williamr@4: * 
williamr@4: * // Start receiving periodical voltage measurements.
williamr@4: * TRequestStatus& statusStart;
williamr@4: * TIntervalMultiple intervalMultiple = EThreeTimesBaseTimeInterval;
williamr@4: * power->StartAverageVoltageReporting(statusStart, intervalMultiple);
williamr@4: *  
williamr@4: * User::WaitForRequest(statusStart);
williamr@4: * User::LeaveIfError(statusStart.Int());
williamr@4: * 
williamr@4: * // Measurements are being when the ProcessVoltageMeasurement() method 
williamr@4: * // of the MHWRMBatteryVoltageObserver interface is called.
williamr@4: *  
williamr@4: * // Stop receiving measurements when done
williamr@4: * power->StopAverageVoltageReportingL(); 
williamr@4: *
williamr@4: * // To clean up, delete the created object:
williamr@4: * delete power;
williamr@4: * @endcode
williamr@4: *
williamr@4: * @publishedAll
williamr@4: * @released
williamr@4: */
williamr@4: NONSHARABLE_CLASS(CHWRMPower) : public CBase
williamr@4:     {            
williamr@4: public:
williamr@4: 	
williamr@4: 	/**
williamr@4: 	* Data structure used to retreive data from a call to GetBatteryVoltageInfo
williamr@4: 	*/ 
williamr@4: 	struct TBatteryVoltageData 
williamr@4: 		{
williamr@4: 		TInt iRemainingVoltage;
williamr@4: 		TInt iMaximumVoltage;
williamr@4: 		TInt iMinimumVoltage;
williamr@4: 		};
williamr@4: 		
williamr@4: 	/**
williamr@4: 	* Data structure used to retreive data from a call to GetBatteryInfo
williamr@4: 	*/ 
williamr@4:     struct TBatteryConsumptionData 
williamr@4: 	 	{
williamr@4: 	 	TInt iNominalCapacity;
williamr@4: 	 	TInt iRemainingCapacity;
williamr@4: 	 	TInt iRemainingPercentageCapacity;
williamr@4: 	 	};
williamr@4:     
williamr@4:     /**
williamr@4:     	* Data structure used to retreive data from a call to GetBatteryInfo
williamr@4:     	*/
williamr@4:     struct TBatteryPowerMeasurementData 
williamr@4:         {
williamr@4:         TInt iAverageVoltage;
williamr@4:         TInt iAverageCurrent;
williamr@4:         };  
williamr@4: 
williamr@4: 
williamr@4: #ifdef SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: 
williamr@4:     /* The type of charger connected to the device.*/
williamr@4:     enum TBatteryChargerType 
williamr@4:         { 
williamr@4:         EBatteryChargerUnKnown = 0, 
williamr@4:         EBatteryChargerDedicated = 1, 
williamr@4:         EBatteryChargerUsbDedicated = 2,
williamr@4:         EBatteryChargerUsbHost = 3 
williamr@4:         };
williamr@4: 
williamr@4:     /* The current charging status of the device. */
williamr@4:     enum TBatteryChargingStatus
williamr@4:         {
williamr@4:         EChargingStatusError              = -1, 
williamr@4:         EChargingStatusNotConnected       = 0,  
williamr@4:         EChargingStatusCharging           = 1,  
williamr@4:         EChargingStatusNotCharging        = 2,  
williamr@4:         EChargingStatusAlmostComplete     = 3,  
williamr@4:         EChargingStatusChargingComplete   = 4,  
williamr@4:         EChargingStatusChargingContinued  = 5  
williamr@4:         };
williamr@4: 
williamr@4:     /* Used to stop the ongoing charging notification. 
williamr@4:      * EChargingNotifierAll used to stop charging current and charging 
williamr@4:      * time notifications. */
williamr@4:      
williamr@4:     enum TBatteryChargingNotifier
williamr@4:         {
williamr@4:         EChargingNotifierAll = 0,
williamr@4:         EChargingNotifierChargingCurrent = 1,
williamr@4:         EChargingNotifierBatteryFullChargingTime = 2
williamr@4:         };
williamr@4: 
williamr@4: #endif //SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: 
williamr@4: public:	
williamr@4: 
williamr@4:     IMPORT_C ~CHWRMPower();
williamr@4:     IMPORT_C static CHWRMPower* NewL();
williamr@4:     IMPORT_C static CHWRMPower* NewLC();
williamr@4:      
williamr@4: public: // New functions
williamr@4: 
williamr@4: 	IMPORT_C void GetBatteryInfo(TRequestStatus& aStatus, TBatteryConsumptionData& aBatteryConsumptionData);
williamr@4:     IMPORT_C void GetBatteryVoltageInfo(TRequestStatus& aStatus, TBatteryVoltageData& aBatteryVoltageData);
williamr@4:     IMPORT_C void GetBaseTimeIntervalL(TInt &aBaseTimeInterval);
williamr@4:     IMPORT_C TInt SetPowerReportObserver(MHWRMBatteryPowerObserver* aPowerReportCallback);
williamr@4:     IMPORT_C TInt StartAveragePowerReporting(TRequestStatus& aStatus, const TUint& aInterval);
williamr@4:     IMPORT_C void StopAveragePowerReportingL(); 
williamr@4:     
williamr@4: #ifdef SYMBIAN_HWRM_EXTPOWERINFO 
williamr@4:     
williamr@4:     IMPORT_C TInt GetBatteryChargerType(TBatteryChargerType& aChargerType);
williamr@4:     IMPORT_C TInt GetBatteryChargingStatus(TBatteryChargingStatus& aChargingStatus);
williamr@4:     IMPORT_C TInt SetBatteryChargingObserver(
williamr@4:              MHWRMBatteryChargingStatusObserver*   aChargingStatusCallback,
williamr@4:              MHWRMBatteryChargingCurrentObserver*     aChrgCurrentCallback,
williamr@4:              MHWRMBatteryFullChargingTimeObserver* aChrgTimeCallback);
williamr@4:     IMPORT_C TInt NotifyAverageChargingCurrent(TRequestStatus& aStatus, const TUint& aInterval);
williamr@4:     IMPORT_C TInt NotifyBatteryFullChargingTime(TRequestStatus& aStatus);
williamr@4:     IMPORT_C void StopChargingNotificationL(TBatteryChargingNotifier aNotifier);
williamr@4: #endif //SYMBIAN_HWRM_EXTPOWERINFO
williamr@4:     
williamr@4: private:
williamr@4: 
williamr@4: 	void ConstructL();
williamr@4: 	
williamr@4: private:
williamr@4: 
williamr@4: 	CHWRMPowerImpl* iPowerImpl;	
williamr@4:     };
williamr@4: 
williamr@4: /**
williamr@4: * A callback interface for power measurements reporting.
williamr@4: *
williamr@4: * If the client requires periodical measurements of the Average Power,
williamr@4: * it needs to derive a class from the MHWRMBatteryPowerObserver interface
williamr@4: * and implement the PowerMeasurement() method. 
williamr@4: * 
williamr@4: * A callback object header example:
williamr@4: *
williamr@4: * @code 
williamr@4: * // INCLUDES
williamr@4: * #include <hwrmpower.h> // Link against HWRMPowerClient.lib.
williamr@4: *
williamr@4: * class CTest : public CBase, 
williamr@4: *               public MHWRMBatteryPowerObserver    
williamr@4: *    {
williamr@4: *    public:
williamr@4: *        CTest();
williamr@4: *        ~CTest();
williamr@4: *                       
williamr@4: *        void ConstructL();
williamr@4: *        static CTest* NewL();
williamr@4: *                
williamr@4: *        // from MHWRMBatteryPowerObserver
williamr@4: *        virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);
williamr@4: *
williamr@4: *    private:
williamr@4: *        CHWRMPower* iPower;
williamr@4: *    };
williamr@4: * @endcode
williamr@4: *
williamr@4: * A callback method implementation example:
williamr@4: *
williamr@4: * @code
williamr@4: * void CTest::PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);
williamr@4: *    {
williamr@4: *  	 if (aErrorCode == KErrNone)
williamr@4: *	 	{
williamr@4: *		INFO_PRINTF2(_L("INFO: Power Measurement Received, averageVolatge=%d, averageCurrent=%d"),aMeasurement.iAverageVoltage, aMeasurement.iAverageCurrent);
williamr@4: *		}
williamr@4: *	 else
williamr@4: *		{
williamr@4: *		INFO_PRINTF2(_L("INFO: Power Measurement Measurement Error, error=%d"),aErr);
williamr@4: *		}
williamr@4: *    }
williamr@4: * @endcode
williamr@4: *
williamr@4: * @publishedAll
williamr@4: * @released
williamr@4: */
williamr@4: 
williamr@4: class MHWRMBatteryPowerObserver
williamr@4:     {
williamr@4: public:
williamr@4:     /** 
williamr@4:     * Called when a Power(Voltage and Current) consumption measurement value is received.
williamr@4:     *
williamr@4:     * @param aErr Error code. 
williamr@4:     * @param aMeasurement The Average Power value calculated by the plugin. Valid only when aErr == KErrNone.
williamr@4:     */
williamr@4: 
williamr@4:     virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement)=0;   
williamr@4:     };
williamr@4: 
williamr@4: 
williamr@4: #ifdef SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: /**
williamr@4: * A callback interface for charging status change.
williamr@4: *
williamr@4: * If the client requires charging status change notofication,
williamr@4: * it needs to derive a class from the MHWRMBatteryChargingStatusObserver interface
williamr@4: * and implement the ChargingStatusChange() method. 
williamr@4: * 
williamr@4: * A callback object header example:
williamr@4: *
williamr@4: * @code 
williamr@4: * // INCLUDES
williamr@4: class CTest : public CBase, 
williamr@4:               public MHWRMBatteryChargingStatusObserver
williamr@4:    {
williamr@4:     public:
williamr@4:         CTest();
williamr@4:         ~CTest();
williamr@4:                        
williamr@4:         void ConstructL();
williamr@4:         static CTest* NewL();
williamr@4:                 
williamr@4:         // from MHWRMBatteryChargingStatusObserver
williamr@4:         virtual void ChargingStatusChange( Tint aErrCode,
williamr@4:                    CHWRMPower::TBatteryChargingStatus aChrgStatus);
williamr@4:    };
williamr@4: * @endcode   
williamr@4: * A callback method implementation example:
williamr@4: *
williamr@4: * @code
williamr@4: 
williamr@4: void CTest:: ChargingStatusChange(TInt aErrorCode,
williamr@4:                           CHWRMPower::TBatteryChargingStatus aChrgStatus);
williamr@4:    {
williamr@4:       if (aErrorCode == KErrNone)
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Charging status = %d"), aChrgStatus);
williamr@4:       }
williamr@4:      else
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
williamr@4:       }
williamr@4:    }
williamr@4: * @endcode  
williamr@4: *
williamr@4: * @publishedAll
williamr@4: * @released
williamr@4: */
williamr@4: class MHWRMBatteryChargingStatusObserver
williamr@4:     {
williamr@4: public:
williamr@4:     /** 
williamr@4:     * Called when a charging status is changed.
williamr@4:     *
williamr@4:     * @param aErrCode Error code. 
williamr@4:     * @param aChrgStatus Charging status.
williamr@4:     */
williamr@4: 
williamr@4:     virtual void ChargingStatusChange( TInt aErrCode,
williamr@4:                                       CHWRMPower::TBatteryChargingStatus aChrgStatus)=0;
williamr@4: };
williamr@4: 
williamr@4: /**
williamr@4: * A callback interface for charging current measurements reporting.
williamr@4: *
williamr@4: * If the client requires periodical measurements of the charging current measurements,
williamr@4: * it needs to derive a class from the MHWRMBatteryChargingCurrentObserver interface
williamr@4: * and implement the AverageChargingCurrentChange() method. 
williamr@4: * 
williamr@4: * A callback object header example:
williamr@4: *
williamr@4: * @code 
williamr@4: * // INCLUDES
williamr@4: class CTest : public CBase, 
williamr@4:               public MHWRMBatteryChargingStatusObserver
williamr@4:    {
williamr@4:     public:
williamr@4:         CTest();
williamr@4:         ~CTest();
williamr@4:                        
williamr@4:         void ConstructL();
williamr@4:         static CTest* NewL();
williamr@4:                 
williamr@4:         // from MHWRMBatteryChargingStatusObserver
williamr@4:         virtual void AverageChargingCurrentRateChange(
williamr@4:                            TInt aErrCode, TInt aMeasurement);
williamr@4: 
williamr@4:    };
williamr@4: * @endcode   
williamr@4: * A callback method implementation example:
williamr@4: *
williamr@4: * @code
williamr@4: 
williamr@4: // Notification handler
williamr@4: void CTest::ChargingCurrentChange(
williamr@4:                            TInt aErrorCode, TInt aMeasurement)
williamr@4:   {
williamr@4:       if (aErrorCode == KErrNone)
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Charging current = %d"), aMeasurement);
williamr@4:       }
williamr@4:      else
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
williamr@4:       }
williamr@4:    }
williamr@4: 
williamr@4: 
williamr@4: * @endcode  
williamr@4: *
williamr@4: * @publishedAll
williamr@4: * @released
williamr@4: */
williamr@4: 
williamr@4: class MHWRMBatteryChargingCurrentObserver
williamr@4:     {
williamr@4:    /** 
williamr@4:     * Called when a charging current measurement value is received.
williamr@4:     *
williamr@4:     * @param aErrCode Error code. 
williamr@4:     * @param aMeasurement The Average Charging current value calculated by the plugin.
williamr@4:              Valid only when aErr == KErrNone.
williamr@4:     */
williamr@4:     public:
williamr@4:         virtual void AverageChargingCurrentChange(TInt aErrCode, TInt aMeasurement)=0;
williamr@4:     };
williamr@4: 
williamr@4: /**
williamr@4: * A callback interface for remaining charging time notification.
williamr@4: *
williamr@4: * If the client requires remaining charging time notification,
williamr@4: * it needs to derive a class from the MHWRMBatteryFullChargingTimeObserver interface
williamr@4: * and implement the BatteryFullChargingTimeChange() method. 
williamr@4: * 
williamr@4: * A callback object header example:
williamr@4: *
williamr@4: * @code 
williamr@4: * // INCLUDES
williamr@4: class CTest : public CBase, 
williamr@4:               public MHWRMBatteryFullChargingTimeObserver
williamr@4:    {
williamr@4:     public:
williamr@4:         CTest();
williamr@4:         ~CTest();
williamr@4:                        
williamr@4:         void ConstructL();
williamr@4:         static CTest* NewL();
williamr@4:                 
williamr@4:         // from MHWRMBatteryChargingStatusObserver
williamr@4:         virtual void BatteryFullChargingTimeChange(
williamr@4:                            TInt aErrCode, TInt aMeasurement);
williamr@4: 
williamr@4:    };
williamr@4: * @endcode   
williamr@4: * A callback method implementation example:
williamr@4: *
williamr@4: * @code
williamr@4: 
williamr@4: // Notification handler
williamr@4: void CTest::BatteryFullChargingTimeChange(
williamr@4:                               TInt aErrorCode, TUint aTime)
williamr@4:    {
williamr@4:       if (aErrorCode == KErrNone)
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Remaining charging time = %d"), aTime);
williamr@4:       }
williamr@4:      else
williamr@4:       {
williamr@4:       INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
williamr@4:       }
williamr@4:    }
williamr@4: 
williamr@4: 
williamr@4: * @endcode  
williamr@4: *
williamr@4: * @publishedAll
williamr@4: * @released
williamr@4: */
williamr@4: 
williamr@4: class MHWRMBatteryFullChargingTimeObserver
williamr@4:     {
williamr@4:    /** 
williamr@4:     * Called when a full charging current time measurement value is received.
williamr@4:     *
williamr@4:     * @param aErrCode Error code. 
williamr@4:     * @param aTime Time required for full charging of Battery.
williamr@4:              Valid only when aErrCode == KErrNone.
williamr@4:     */
williamr@4: 
williamr@4:     public:
williamr@4:         virtual void BatteryFullChargingTimeChange(TInt aErrCode, TUint aTime)=0;
williamr@4:     };
williamr@4: #endif //SYMBIAN_HWRM_EXTPOWERINFO
williamr@4: 
williamr@4: #endif /*HWRMPOWER_H_*/
williamr@4: // End of File