1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/hwrmpower.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,453 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef HWRMPOWER_H_
1.20 +#define HWRMPOWER_H_
1.21 +
1.22 +// INCLUDES
1.23 +#include <e32base.h>
1.24 +#include <e32cmn.h>
1.25 +
1.26 +// CONSTANTS
1.27 +
1.28 +// FORWARD DECLARATIONS
1.29 +
1.30 +class CHWRMPowerImpl;
1.31 +class MHWRMBatteryPowerObserver;
1.32 +
1.33 +#ifdef SYMBIAN_HWRM_EXTPOWERINFO
1.34 +class MHWRMBatteryChargingStatusObserver;
1.35 +class MHWRMBatteryChargingCurrentObserver;
1.36 +class MHWRMBatteryFullChargingTimeObserver;
1.37 +#endif //SYMBIAN_HWRM_EXTPOWERINFO
1.38 +
1.39 +/**
1.40 +* HW Resource Manager Power API is a library API providing the
1.41 +* ability to request detailed information regarding the battery
1.42 +* capacity, voltage and current consumption.
1.43 +*
1.44 +* The API consists of the classes CHWRMPower, MHWRMBatteryConsumptionObserver
1.45 +* and MHWRMBatteryVoltageObserver. If the client requires periodical measurements
1.46 +* of the Average Voltage and/or Average Consumption, it should also provide callback pointer
1.47 +* of the MHWRMBatteryConsumptionObserver and/or MHWRMBatteryVoltageObserver
1.48 +* implementing class for the NewL() method.
1.49 +*
1.50 +* Usage:
1.51 +*
1.52 +* @code
1.53 +* #include <hwrmpower.h>
1.54 +*
1.55 +* // A CHWRMPower instance can be created by using NewL() or NewLC() methods.
1.56 +* // Periodical measurements are required so callbacks are provided. Assume
1.57 +* // the calling object implements both interfaces.
1.58 +* CHWRMPower* power = CHWRMPower::NewL(this, this);
1.59 +*
1.60 +* // Get battery info.
1.61 +* TRequestStatus& status;
1.62 +* TBatteryConsumptionData batteryConsumptionData;
1.63 +* power->GetBatteryInfo(status, batteryConsumptionData);
1.64 +*
1.65 +* User::WaitForRequest(status);
1.66 +* User::LeaveIfError(status.Int());
1.67 +*
1.68 +* // Start receiving periodical voltage measurements.
1.69 +* TRequestStatus& statusStart;
1.70 +* TIntervalMultiple intervalMultiple = EThreeTimesBaseTimeInterval;
1.71 +* power->StartAverageVoltageReporting(statusStart, intervalMultiple);
1.72 +*
1.73 +* User::WaitForRequest(statusStart);
1.74 +* User::LeaveIfError(statusStart.Int());
1.75 +*
1.76 +* // Measurements are being when the ProcessVoltageMeasurement() method
1.77 +* // of the MHWRMBatteryVoltageObserver interface is called.
1.78 +*
1.79 +* // Stop receiving measurements when done
1.80 +* power->StopAverageVoltageReportingL();
1.81 +*
1.82 +* // To clean up, delete the created object:
1.83 +* delete power;
1.84 +* @endcode
1.85 +*
1.86 +* @publishedAll
1.87 +* @released
1.88 +*/
1.89 +NONSHARABLE_CLASS(CHWRMPower) : public CBase
1.90 + {
1.91 +public:
1.92 +
1.93 + /**
1.94 + * Data structure used to retreive data from a call to GetBatteryVoltageInfo
1.95 + */
1.96 + struct TBatteryVoltageData
1.97 + {
1.98 + TInt iRemainingVoltage;
1.99 + TInt iMaximumVoltage;
1.100 + TInt iMinimumVoltage;
1.101 + };
1.102 +
1.103 + /**
1.104 + * Data structure used to retreive data from a call to GetBatteryInfo
1.105 + */
1.106 + struct TBatteryConsumptionData
1.107 + {
1.108 + TInt iNominalCapacity;
1.109 + TInt iRemainingCapacity;
1.110 + TInt iRemainingPercentageCapacity;
1.111 + };
1.112 +
1.113 + /**
1.114 + * Data structure used to retreive data from a call to GetBatteryInfo
1.115 + */
1.116 + struct TBatteryPowerMeasurementData
1.117 + {
1.118 + TInt iAverageVoltage;
1.119 + TInt iAverageCurrent;
1.120 + };
1.121 +
1.122 +
1.123 +#ifdef SYMBIAN_HWRM_EXTPOWERINFO
1.124 +
1.125 + /* The type of charger connected to the device.*/
1.126 + enum TBatteryChargerType
1.127 + {
1.128 + EBatteryChargerUnKnown = 0,
1.129 + EBatteryChargerDedicated = 1,
1.130 + EBatteryChargerUsbDedicated = 2,
1.131 + EBatteryChargerUsbHost = 3
1.132 + };
1.133 +
1.134 + /* The current charging status of the device. */
1.135 + enum TBatteryChargingStatus
1.136 + {
1.137 + EChargingStatusError = -1,
1.138 + EChargingStatusNotConnected = 0,
1.139 + EChargingStatusCharging = 1,
1.140 + EChargingStatusNotCharging = 2,
1.141 + EChargingStatusAlmostComplete = 3,
1.142 + EChargingStatusChargingComplete = 4,
1.143 + EChargingStatusChargingContinued = 5
1.144 + };
1.145 +
1.146 + /* Used to stop the ongoing charging notification.
1.147 + * EChargingNotifierAll used to stop charging current and charging
1.148 + * time notifications. */
1.149 +
1.150 + enum TBatteryChargingNotifier
1.151 + {
1.152 + EChargingNotifierAll = 0,
1.153 + EChargingNotifierChargingCurrent = 1,
1.154 + EChargingNotifierBatteryFullChargingTime = 2
1.155 + };
1.156 +
1.157 +#endif //SYMBIAN_HWRM_EXTPOWERINFO
1.158 +
1.159 +public:
1.160 +
1.161 + IMPORT_C ~CHWRMPower();
1.162 + IMPORT_C static CHWRMPower* NewL();
1.163 + IMPORT_C static CHWRMPower* NewLC();
1.164 +
1.165 +public: // New functions
1.166 +
1.167 + IMPORT_C void GetBatteryInfo(TRequestStatus& aStatus, TBatteryConsumptionData& aBatteryConsumptionData);
1.168 + IMPORT_C void GetBatteryVoltageInfo(TRequestStatus& aStatus, TBatteryVoltageData& aBatteryVoltageData);
1.169 + IMPORT_C void GetBaseTimeIntervalL(TInt &aBaseTimeInterval);
1.170 + IMPORT_C TInt SetPowerReportObserver(MHWRMBatteryPowerObserver* aPowerReportCallback);
1.171 + IMPORT_C TInt StartAveragePowerReporting(TRequestStatus& aStatus, const TUint& aInterval);
1.172 + IMPORT_C void StopAveragePowerReportingL();
1.173 +
1.174 +#ifdef SYMBIAN_HWRM_EXTPOWERINFO
1.175 +
1.176 + IMPORT_C TInt GetBatteryChargerType(TBatteryChargerType& aChargerType);
1.177 + IMPORT_C TInt GetBatteryChargingStatus(TBatteryChargingStatus& aChargingStatus);
1.178 + IMPORT_C TInt SetBatteryChargingObserver(
1.179 + MHWRMBatteryChargingStatusObserver* aChargingStatusCallback,
1.180 + MHWRMBatteryChargingCurrentObserver* aChrgCurrentCallback,
1.181 + MHWRMBatteryFullChargingTimeObserver* aChrgTimeCallback);
1.182 + IMPORT_C TInt NotifyAverageChargingCurrent(TRequestStatus& aStatus, const TUint& aInterval);
1.183 + IMPORT_C TInt NotifyBatteryFullChargingTime(TRequestStatus& aStatus);
1.184 + IMPORT_C void StopChargingNotificationL(TBatteryChargingNotifier aNotifier);
1.185 +#endif //SYMBIAN_HWRM_EXTPOWERINFO
1.186 +
1.187 +private:
1.188 +
1.189 + void ConstructL();
1.190 +
1.191 +private:
1.192 +
1.193 + CHWRMPowerImpl* iPowerImpl;
1.194 + };
1.195 +
1.196 +/**
1.197 +* A callback interface for power measurements reporting.
1.198 +*
1.199 +* If the client requires periodical measurements of the Average Power,
1.200 +* it needs to derive a class from the MHWRMBatteryPowerObserver interface
1.201 +* and implement the PowerMeasurement() method.
1.202 +*
1.203 +* A callback object header example:
1.204 +*
1.205 +* @code
1.206 +* // INCLUDES
1.207 +* #include <hwrmpower.h> // Link against HWRMPowerClient.lib.
1.208 +*
1.209 +* class CTest : public CBase,
1.210 +* public MHWRMBatteryPowerObserver
1.211 +* {
1.212 +* public:
1.213 +* CTest();
1.214 +* ~CTest();
1.215 +*
1.216 +* void ConstructL();
1.217 +* static CTest* NewL();
1.218 +*
1.219 +* // from MHWRMBatteryPowerObserver
1.220 +* virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);
1.221 +*
1.222 +* private:
1.223 +* CHWRMPower* iPower;
1.224 +* };
1.225 +* @endcode
1.226 +*
1.227 +* A callback method implementation example:
1.228 +*
1.229 +* @code
1.230 +* void CTest::PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement);
1.231 +* {
1.232 +* if (aErrorCode == KErrNone)
1.233 +* {
1.234 +* INFO_PRINTF2(_L("INFO: Power Measurement Received, averageVolatge=%d, averageCurrent=%d"),aMeasurement.iAverageVoltage, aMeasurement.iAverageCurrent);
1.235 +* }
1.236 +* else
1.237 +* {
1.238 +* INFO_PRINTF2(_L("INFO: Power Measurement Measurement Error, error=%d"),aErr);
1.239 +* }
1.240 +* }
1.241 +* @endcode
1.242 +*
1.243 +* @publishedAll
1.244 +* @released
1.245 +*/
1.246 +
1.247 +class MHWRMBatteryPowerObserver
1.248 + {
1.249 +public:
1.250 + /**
1.251 + * Called when a Power(Voltage and Current) consumption measurement value is received.
1.252 + *
1.253 + * @param aErr Error code.
1.254 + * @param aMeasurement The Average Power value calculated by the plugin. Valid only when aErr == KErrNone.
1.255 + */
1.256 +
1.257 + virtual void PowerMeasurement(TInt aErr, CHWRMPower::TBatteryPowerMeasurementData& aMeasurement)=0;
1.258 + };
1.259 +
1.260 +
1.261 +#ifdef SYMBIAN_HWRM_EXTPOWERINFO
1.262 +/**
1.263 +* A callback interface for charging status change.
1.264 +*
1.265 +* If the client requires charging status change notofication,
1.266 +* it needs to derive a class from the MHWRMBatteryChargingStatusObserver interface
1.267 +* and implement the ChargingStatusChange() method.
1.268 +*
1.269 +* A callback object header example:
1.270 +*
1.271 +* @code
1.272 +* // INCLUDES
1.273 +class CTest : public CBase,
1.274 + public MHWRMBatteryChargingStatusObserver
1.275 + {
1.276 + public:
1.277 + CTest();
1.278 + ~CTest();
1.279 +
1.280 + void ConstructL();
1.281 + static CTest* NewL();
1.282 +
1.283 + // from MHWRMBatteryChargingStatusObserver
1.284 + virtual void ChargingStatusChange( Tint aErrCode,
1.285 + CHWRMPower::TBatteryChargingStatus aChrgStatus);
1.286 + };
1.287 +* @endcode
1.288 +* A callback method implementation example:
1.289 +*
1.290 +* @code
1.291 +
1.292 +void CTest:: ChargingStatusChange(TInt aErrorCode,
1.293 + CHWRMPower::TBatteryChargingStatus aChrgStatus);
1.294 + {
1.295 + if (aErrorCode == KErrNone)
1.296 + {
1.297 + INFO_PRINTF2(_L("Charging status = %d"), aChrgStatus);
1.298 + }
1.299 + else
1.300 + {
1.301 + INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
1.302 + }
1.303 + }
1.304 +* @endcode
1.305 +*
1.306 +* @publishedAll
1.307 +* @released
1.308 +*/
1.309 +class MHWRMBatteryChargingStatusObserver
1.310 + {
1.311 +public:
1.312 + /**
1.313 + * Called when a charging status is changed.
1.314 + *
1.315 + * @param aErrCode Error code.
1.316 + * @param aChrgStatus Charging status.
1.317 + */
1.318 +
1.319 + virtual void ChargingStatusChange( TInt aErrCode,
1.320 + CHWRMPower::TBatteryChargingStatus aChrgStatus)=0;
1.321 +};
1.322 +
1.323 +/**
1.324 +* A callback interface for charging current measurements reporting.
1.325 +*
1.326 +* If the client requires periodical measurements of the charging current measurements,
1.327 +* it needs to derive a class from the MHWRMBatteryChargingCurrentObserver interface
1.328 +* and implement the AverageChargingCurrentChange() method.
1.329 +*
1.330 +* A callback object header example:
1.331 +*
1.332 +* @code
1.333 +* // INCLUDES
1.334 +class CTest : public CBase,
1.335 + public MHWRMBatteryChargingStatusObserver
1.336 + {
1.337 + public:
1.338 + CTest();
1.339 + ~CTest();
1.340 +
1.341 + void ConstructL();
1.342 + static CTest* NewL();
1.343 +
1.344 + // from MHWRMBatteryChargingStatusObserver
1.345 + virtual void AverageChargingCurrentRateChange(
1.346 + TInt aErrCode, TInt aMeasurement);
1.347 +
1.348 + };
1.349 +* @endcode
1.350 +* A callback method implementation example:
1.351 +*
1.352 +* @code
1.353 +
1.354 +// Notification handler
1.355 +void CTest::ChargingCurrentChange(
1.356 + TInt aErrorCode, TInt aMeasurement)
1.357 + {
1.358 + if (aErrorCode == KErrNone)
1.359 + {
1.360 + INFO_PRINTF2(_L("Charging current = %d"), aMeasurement);
1.361 + }
1.362 + else
1.363 + {
1.364 + INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
1.365 + }
1.366 + }
1.367 +
1.368 +
1.369 +* @endcode
1.370 +*
1.371 +* @publishedAll
1.372 +* @released
1.373 +*/
1.374 +
1.375 +class MHWRMBatteryChargingCurrentObserver
1.376 + {
1.377 + /**
1.378 + * Called when a charging current measurement value is received.
1.379 + *
1.380 + * @param aErrCode Error code.
1.381 + * @param aMeasurement The Average Charging current value calculated by the plugin.
1.382 + Valid only when aErr == KErrNone.
1.383 + */
1.384 + public:
1.385 + virtual void AverageChargingCurrentChange(TInt aErrCode, TInt aMeasurement)=0;
1.386 + };
1.387 +
1.388 +/**
1.389 +* A callback interface for remaining charging time notification.
1.390 +*
1.391 +* If the client requires remaining charging time notification,
1.392 +* it needs to derive a class from the MHWRMBatteryFullChargingTimeObserver interface
1.393 +* and implement the BatteryFullChargingTimeChange() method.
1.394 +*
1.395 +* A callback object header example:
1.396 +*
1.397 +* @code
1.398 +* // INCLUDES
1.399 +class CTest : public CBase,
1.400 + public MHWRMBatteryFullChargingTimeObserver
1.401 + {
1.402 + public:
1.403 + CTest();
1.404 + ~CTest();
1.405 +
1.406 + void ConstructL();
1.407 + static CTest* NewL();
1.408 +
1.409 + // from MHWRMBatteryChargingStatusObserver
1.410 + virtual void BatteryFullChargingTimeChange(
1.411 + TInt aErrCode, TInt aMeasurement);
1.412 +
1.413 + };
1.414 +* @endcode
1.415 +* A callback method implementation example:
1.416 +*
1.417 +* @code
1.418 +
1.419 +// Notification handler
1.420 +void CTest::BatteryFullChargingTimeChange(
1.421 + TInt aErrorCode, TUint aTime)
1.422 + {
1.423 + if (aErrorCode == KErrNone)
1.424 + {
1.425 + INFO_PRINTF2(_L("Remaining charging time = %d"), aTime);
1.426 + }
1.427 + else
1.428 + {
1.429 + INFO_PRINTF2(_L("Error, error=%d"),aErrorCode);
1.430 + }
1.431 + }
1.432 +
1.433 +
1.434 +* @endcode
1.435 +*
1.436 +* @publishedAll
1.437 +* @released
1.438 +*/
1.439 +
1.440 +class MHWRMBatteryFullChargingTimeObserver
1.441 + {
1.442 + /**
1.443 + * Called when a full charging current time measurement value is received.
1.444 + *
1.445 + * @param aErrCode Error code.
1.446 + * @param aTime Time required for full charging of Battery.
1.447 + Valid only when aErrCode == KErrNone.
1.448 + */
1.449 +
1.450 + public:
1.451 + virtual void BatteryFullChargingTimeChange(TInt aErrCode, TUint aTime)=0;
1.452 + };
1.453 +#endif //SYMBIAN_HWRM_EXTPOWERINFO
1.454 +
1.455 +#endif /*HWRMPOWER_H_*/
1.456 +// End of File