inc/FSysPowerManager.h

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