inc/FSysPowerManager.h

   1
   2 //
   3 // Open Service Platform
   4 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   5 //
   6 // Licensed under the Apache License, Version 2.0 (the License);
   7 // you may not use this file except in compliance with the License.
   8 // You may obtain a copy of the License at
   9 //
  10 //     http://www.apache.org/licenses/LICENSE-2.0
  11 //
  12 // Unless required by applicable law or agreed to in writing, software
  13 // distributed under the License is distributed on an "AS IS" BASIS,
  14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 // See the License for the specific language governing permissions and
  16 // limitations under the License.
  17 //
  18
  19 /**
  20  * @file        FSysPowerManager.h
  21  * @brief       This is the header file for the %PowerManager class.
  22  *
  23  * This header file contains the declarations of the %PowerManager class.
  24  */
  25
  26 #ifndef _FSYS_POWER_MANAGER_H_
  27 #define _FSYS_POWER_MANAGER_H_
  28
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace System
  32 {
  33
  34 class IScreenEventListener;
  35 class IChargingEventListener;
  36 class IBatteryEventListener;
  37 class IBootEventListener;
  38
  39 /**
  40  * @enum        BatteryLevel
  41  *
  42  * Defines the representation of the remaining charge in the battery.
  43  *
  44  * @since       2.0
  45  */
  46 enum BatteryLevel
  47 {
  48         BATTERY_FULL,           // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_FULL.
  49         BATTERY_HIGH,           // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_HIGH.
  50         BATTERY_LOW,            // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_LOW.
  51         BATTERY_CRITICAL,       // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_CRITICAL.
  52         BATTERY_EMPTY,          // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_EMPTY.
  53         BATTERY_LEVEL_FULL = BATTERY_FULL,/**< The battery is fully charged */
  54         BATTERY_LEVEL_HIGH = BATTERY_HIGH,/**< The battery has plenty of charge */
  55         BATTERY_LEVEL_LOW = BATTERY_LOW,/**< The battery has little charge */
  56         BATTERY_LEVEL_CRITICAL = BATTERY_CRITICAL,/**< The battery charge is at a critical state @n It is strongly recommended to stop using all multimedia features because they are not guaranteed to work correctly at this level. */
  57         BATTERY_LEVEL_EMPTY = BATTERY_EMPTY,    /**< The battery is empty @n It is strongly recommended to prepare for the safe termination of the application because the device will start a shutdown process soon after entering this level.  */
  58 };
  59
  60 /**
  61  * @enum        PowerMode
  62  *
  63  * Defines the representation of the charge remaining in the battery.
  64  *
  65  * @since       2.0
  66  */
  67 enum PowerMode
  68 {
  69         POWER_STANDBY,                          // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_STANDBY.
  70         POWER_SLEEP,                            // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_SLEEP.
  71         POWER_MODE_STANDBY = POWER_STANDBY,     /**< The battery is fully charged */
  72         POWER_MODE_SLEEP = POWER_SLEEP,         /**< The battery has plenty of charge */
  73 };
  74
  75 /**
  76  * @class       PowerManager
  77  * @brief       This class provides methods for power management.
  78  *
  79  * @since       2.0
  80  *
  81  * @final       This class is not intended for extension.
  82  *
  83  * The %PowerManager class provides methods for managing the device power state.
  84  *
  85  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/screen_power_mgmt.htm">Screen Power Management</a>.
  86
  87  */
  88
  89 class _OSP_EXPORT_ PowerManager
  90         : public Tizen::Base::Object
  91 {
  92
  93 public:
  94         /**
  95          * Changes the policy of the screen power management.
  96          *
  97          * @since       2.0
  98          *
  99          * @privlevel   public
 100          * @privilege   %http://tizen.org/privilege/power
 101          *
 102          * @return      An error code
 103          * @param[in]   keepOn  Set to @c true if the screen remains in the 'ON' state until the application goes to the background(inactivated), @n
 104          *                      else @c false if the state of the screen is controlled by the default power control policy of the system
 105          * @param[in]   dimming Set to @c true if the screen is dimmed when there is no user input for a certain amount of time, @n
 106          *                      else @c false if the screen is not dimmed
 107          * @exception   E_SUCCESS               The method is successful.
 108          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 109          * @exception   E_SYSTEM                A system error has occurred.
 110          * @remarks     The application should explicitly call this method again on foreground(activated) state, if the screen is to be kept 'ON' after coming back from the background(inactivated) state.
 111          */
 112         static result KeepScreenOnState(bool keepOn, bool dimming = true);
 113
 114         /**
 115          * Restores the screen brightness control.
 116          *
 117          * @since 2.0
 118          *
 119          * @return An error code
 120          * @exception   E_SUCCESS The method is successful.
 121          * @exception   E_INVALID_STATE The brightness is never changed.
 122          * @exception   E_SYSTEM The method cannot proceed due to a severe system error.
 123          * @see         SetScreenBrightness()
 124          */
 125         static result RestoreScreenBrightness(void);
 126
 127         /**
 128          * Sets the screen brightness level for an application.
 129          *
 130          * @since       2.0
 131          *
 132          * @privlevel   public
 133          * @privilege   %http://tizen.org/privilege/power
 134          *
 135          * @return      An error code
 136          * @param[in]   brightness              The brightness level to set @n
 137                 *                               The parameter value can range between @c 1 (minimum) and @c 10 (maximum).
 138          * @exception   E_SUCCESS               The method is successful.
 139          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 140          * @exception   E_OUT_OF_RANGE          The specified @c brightness is out of range.
 141          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 142          * @remarks     This brightness level is only available when an application is running on the foreground(activated). Even if the brightness is set to level 1, a black screen is not displayed. Level 1 is the minimum brightness level that can be set for an application. For screen off, Please refer TurnScreenOff method.
 143          * @see         RestoreScreenBrightness(), TurnScreenOff()
 144          */
 145
 146         static result SetScreenBrightness(int brightness);
 147         /**
 148          * Gets the screen brightness level of an application.
 149          *
 150          * @since       2.0
 151          *
 152          * @return      The brightness level of the current application
 153          * @exception   E_SUCCESS             The method is successful.
 154          * @exception   E_SYSTEM         A system error has occurred.
 155          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 156          * @remarks     This method returns the screen brightness level set for an application. If the brightness level is not set, it will return the default system brightness level. @n
 157          *              In case of error, this method returns @c -1.
 158          */
 159         static int GetScreenBrightness(void);
 160
 161         /**
 162          * Checks whether the screen is on.
 163          *
 164          * @since       2.0
 165          *
 166          * @return      @c true if the screen is on, @n
 167          *              else @c false
 168          * @exception   E_SUCCESS       The method is successful.
 169          * @exception   E_SYSTEM        A system error has occurred.
 170          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 171          * @remarks     This method returns @c true when the screen is in the dimming state, and @c false in case of an error.
 172          */
 173         static bool IsScreenOn(void);
 174
 175         /**
 176          * Turns on the screen.
 177          *
 178          * @since       2.0
 179          *
 180          * @privlevel   public
 181          * @privilege   %http://tizen.org/privilege/power
 182          *
 183          * @return      An error code
 184          * @exception   E_SUCCESS               The method is successful.
 185          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 186          * @exception   E_SYSTEM                A system error has occurred.
 187          */
 188         static result TurnScreenOn(void);
 189
 190         /**
 191          * Turns off the screen.
 192          *
 193          * @since       2.0
 194          *
 195          * @privlevel   public
 196          * @privilege   %http://tizen.org/privilege/power
 197          *
 198          * @return      An error code
 199          * @exception   E_SUCCESS               The method is successful.
 200          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 201          * @exception   E_SYSTEM                A system error has occurred.
 202          */
 203         static result TurnScreenOff(void);
 204
 205         /**
 206          * Changes the policy of the CPU (Central Processing Unit) power management.
 207          *
 208          * @since       2.0
 209          *
 210          * @privlevel   public
 211          * @privilege   %http://tizen.org/privilege/power
 212          *
 213          * @return      An error code
 214          * @param[in]   enable  Set to @c true to prevent the CPU from going into sleep mode, @n
 215          *              else @c false to let the state of the CPU follow the system default power management policy
 216          * @exception   E_SUCCESS               The method is successful.
 217          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 218          * @exception   E_SYSTEM                A system error has occurred.
 219          * @remark      This method keeps CPU power state only. Screen state or lock screen is not managed by this method.
 220          */
 221         static result KeepCpuAwake(bool enable);
 222
 223         /**
 224          * Sets the screen event listener.
 225          *
 226          * @since       2.0
 227          *
 228          * @deprecated This method is deprecated. @n
 229          *              Instead of using this method, please use AddScreenEventListener and RemoveScreenEventListener.
 230          *
 231          * @param[in]   listener                The screen event listener
 232          * @remarks     This method always overwrites the first element of internal IScreenEventListener list.
 233          *              The first element added by AddScreentEventListener may be overwritten by this method,
 234          *              which may not be an expected behavior by API users. So, it is not recommended to use this method.
 235          */
 236         static void SetScreenEventListener(IScreenEventListener& listener);
 237
 238
 239         /**
 240          * Adds the screen event listener.
 241          *
 242          * @since       2.1
 243          *
 244          * @param[in]   listener                The screen event listener
 245          * @exception E_SUCCESS               The method is successful.
 246          * @exception E_OBJ_ALREADY_EXIST   The listener has already been added.
 247          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 248          * @see         IScreenEventListener, RemoveScreenEventListener
 249          */
 250         static result AddScreenEventListener(IScreenEventListener& listener);
 251
 252         /**
 253          * Removes the screen event listener.
 254          *
 255          * @since       2.1
 256          *
 257          * @param[in]   listener                The screen event listener
 258          * @exception E_SUCCESS               The method is successful.
 259          * @exception E_OBJ_NOT_FOUND     The specified listener cannot be found.
 260          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 261          * @see         IScreenEventListener, AddScreenEventListener
 262          */
 263         static result RemoveScreenEventListener(IScreenEventListener& listener);
 264
 265
 266         /**
 267          * Sets the charging event listener.
 268          *
 269          * @since       2.0
 270          *
 271          * @deprecated This method is deprecated. @n
 272          *               Instead of using this method, please use AddChargingEventListener and RemoveChargingEventListener.
 273          *
 274          * @param[in]   listener        The charging event listener
 275          * @remarks     This method always overwrites the first element of internal IChargingEventListener list.
 276          *              The first element added by AddChargingEventListener may be overwritten by this method,
 277          *              which may not be an expected behavior by API users. So, it is not recommended to use this method.
 278          */
 279         static void SetChargingEventListener(IChargingEventListener& listener);
 280
 281         /**
 282          * Adds the charging event listener.
 283          *
 284          * @since       2.1
 285          *
 286          * @param[in]   listener                The charging event listener
 287          * @exception E_SUCCESS               The method is successful.
 288          * @exception E_OBJ_ALREADY_EXIST   The listener has already been added.
 289          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 290          * @see IChargingEventListener, RemoveChargingEventListener
 291          */
 292         static result AddChargingEventListener(IChargingEventListener& listener);
 293
 294         /**
 295          * Removes the charging event listener.
 296          *
 297          * @since       2.1
 298          *
 299          * @param[in]   listener                The charging event listener
 300          * @exception E_SUCCESS               The method is successful.
 301          * @exception E_OBJ_NOT_FOUND     The specified listener cannot be found.
 302          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 303          * @see IChargingEventListener, AddChargingEventListener
 304          */
 305         static result RemoveChargingEventListener(IChargingEventListener& listener);
 306
 307         /**
 308          * Sets the battery event listener.
 309          *
 310          * @since       2.0
 311          *
 312          * @return      An error code
 313          * @param[in]   pListener       The battery event listener
 314          * @exception   E_SUCCESS       The method is successful.
 315          * @exception   E_SYSTEM        A system error has occurred.
 316          * @remarks     If @c pListener is set to @c null, the pre-registered listener is unregistered.
 317          */
 318         static result SetBatteryEventListener(IBatteryEventListener* pListener);
 319
 320         /**
 321          * Gets the current charge remaining in the battery as a percentage.
 322          *
 323          * @since 2.0
 324          *
 325          * @return      The percentage of the charge remaining in the battery.
 326          * @exception   E_SUCCESS               The method is successful.
 327          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 328          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 329          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 330          * @remarks     The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
 331          */
 332         static int GetCurrentBatteryLevelInPercentage(void);
 333
 334         /**
 335          * Gets the current charging level of the battery.
 336          *
 337          * @since 2.0
 338          *
 339          * @return      A value from the enumerator BatteryLevel indicating the current charging level
 340          * @exception   E_SUCCESS               The method is successful.
 341          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 342          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 343          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 344          */
 345         static BatteryLevel GetCurrentBatteryLevel(void);
 346
 347         /**
 348          * Checks whether the battery is currently charging.
 349          *
 350          * @since 2.0
 351          *
 352          * @return      @c true if the charging cable is connected to the phone, @n
 353          *              else @c false
 354          * @exception   E_SUCCESS               The method is successful.
 355          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 356          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 357          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 358          */
 359         static bool IsCharging(void);
 360
 361         /**
 362          * Adds the boot event listener.
 363          *
 364          * @since       2.1
 365          *
 366          * @return      An error code
 367          * @param[in]   listener        The boot event listener
 368          * @exception   E_SUCCESS       The method is successful.
 369          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 370          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 371          */
 372         static result AddBootEventListener(IBootEventListener& listener);
 373
 374         /**
 375          * Removes the boot event listener.
 376          *
 377          * @since       2.1
 378          *
 379          * @return      An error code
 380          * @param[in]   listener        The boot event listener
 381          * @exception   E_SUCCESS       The method is successful.
 382          * @exception   E_OBJ_ALREADY_EXIST     The listener is not added.
 383          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 384          */
 385         static result RemoveBootEventListener(IBootEventListener& listener);
 386
 387 private:
 388         /**
 389          * This is the default constructor for this class. This default constructor is intentionally declared as private so that only the platform can create an instance.
 390          */
 391         PowerManager(void);
 392         /**
 393          * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
 394          */
 395         virtual ~PowerManager(void);
 396
 397         /**
 398          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 399          */
 400         PowerManager(const PowerManager& value);
 401
 402         /**
 403          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 404          */
 405         PowerManager& operator = (const PowerManager& value);
 406
 407 private:
 408         friend class _PowerManagerImpl;
 409         class _PowerManagerImpl* __pPowerManagerImpl;
 410 }; // PowerManager
 411
 412 } } // Tizen::System
 413
 414 #endif // _FSYS_POWER_MANAGER_H_