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     This screen power control is available only when an application is active. To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method.
 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 between @c 1 (minimum) and @c 10 (maximum).
 136          * @exception   E_SUCCESS               The method is successful.
 137          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 138          * @exception   E_OUT_OF_RANGE          The specified @c brightness is out of range.
 139          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 140          * @remarks     This brightness level change is available only when an application is active. To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method. 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. To know more about screen off, see the TurnScreenOff() method.
 141          * @see         RestoreScreenBrightness()
 142          * @see         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          * @remarks     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          * @brief       <i>[Deprecated]</i>
 226          * @deprecated  This method is deprecated. @n
 227          * Instead of using this method, use AddScreenEventListener() and RemoveScreenEventListener().
 228          * @since       2.0
 229          *
 230          * @param[in]   listener                The screen event listener
 231          * @remarks     This method always overwrites the first element of internal IScreenEventListener list.
 232          *              The first element added by AddScreenEventListener() may be overwritten by this method,
 233          *              which may not be an expected behavior by API users. So, it is not recommended to use this method.
 234          */
 235         static void SetScreenEventListener(IScreenEventListener& listener);
 236
 237
 238         /**
 239          * Adds the screen event listener.
 240          *
 241          * @since       2.1
 242          *
 243          * @param[in]   listener                The screen event listener
 244          * @exception E_SUCCESS               The method is successful.
 245          * @exception E_OBJ_ALREADY_EXIST   The listener has already been added.
 246          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 247          * @see         IScreenEventListener
 248          * @see         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
 262          * @see         AddScreenEventListener()
 263          */
 264         static result RemoveScreenEventListener(IScreenEventListener& listener);
 265
 266
 267         /**
 268          * Sets the charging event listener.
 269          *
 270          * @brief       <i>[Deprecated]</i>
 271          * @deprecated  This method is deprecated. @n
 272          *               Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
 273          * @since       2.0
 274          *
 275          * @param[in]   listener        The charging event listener
 276          * @remarks     This method always overwrites the first element of internal IChargingEventListener list.
 277          *              The first element added by AddChargingEventListener() may be overwritten by this method,
 278          *              which may not be an expected behavior by API users. So, it is not recommended to use this method.
 279          */
 280         static void SetChargingEventListener(IChargingEventListener& listener);
 281
 282         /**
 283          * Adds the charging event listener.
 284          *
 285          * @since       2.1
 286          *
 287          * @param[in]   listener                The charging event listener
 288          * @exception E_SUCCESS               The method is successful.
 289          * @exception E_OBJ_ALREADY_EXIST   The listener has already been added.
 290          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 291          * @see IChargingEventListener
 292          * @see RemoveChargingEventListener()
 293          */
 294         static result AddChargingEventListener(IChargingEventListener& listener);
 295
 296         /**
 297          * Removes the charging event listener.
 298          *
 299          * @since       2.1
 300          *
 301          * @param[in]   listener                The charging event listener
 302          * @exception E_SUCCESS               The method is successful.
 303          * @exception E_OBJ_NOT_FOUND     The specified listener cannot be found.
 304          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 305          * @see IChargingEventListener
 306          * @see AddChargingEventListener()
 307          */
 308         static result RemoveChargingEventListener(IChargingEventListener& listener);
 309
 310         /**
 311          * Sets the battery event listener.
 312          *
 313          * @since       2.0
 314          *
 315          * @return      An error code
 316          * @param[in]   pListener       The battery event listener
 317          * @exception   E_SUCCESS       The method is successful.
 318          * @exception   E_SYSTEM        A system error has occurred.
 319          * @remarks     If @c pListener is set to @c null, the pre-registered listener is unregistered.
 320          */
 321         static result SetBatteryEventListener(IBatteryEventListener* pListener);
 322
 323         /**
 324          * Gets the current charge remaining in the battery as a percentage.
 325          *
 326          * @since 2.0
 327          *
 328          * @return      The percentage of the charge remaining in the battery.
 329          * @exception   E_SUCCESS               The method is successful.
 330          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 331          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 332          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 333          * @remarks     The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
 334          */
 335         static int GetCurrentBatteryLevelInPercentage(void);
 336
 337         /**
 338          * Gets the current charging level of the battery.
 339          *
 340          * @since 2.0
 341          *
 342          * @return      A value from the enumerator BatteryLevel indicating the current charging level
 343          * @exception   E_SUCCESS               The method is successful.
 344          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 345          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 346          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 347          */
 348         static BatteryLevel GetCurrentBatteryLevel(void);
 349
 350         /**
 351          * Checks whether the battery is currently charging.
 352          *
 353          * @since 2.0
 354          *
 355          * @return      @c true if the charging cable is connected to the phone, @n
 356          *              else @c false
 357          * @exception   E_SUCCESS               The method is successful.
 358          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 359          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 360          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 361          */
 362         static bool IsCharging(void);
 363
 364         /**
 365          * Adds the boot event listener.
 366          *
 367          * @since       2.1
 368          *
 369          * @return      An error code
 370          * @param[in]   listener        The boot event listener
 371          * @exception   E_SUCCESS       The method is successful.
 372          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 373          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 374          */
 375         static result AddBootEventListener(IBootEventListener& listener);
 376
 377         /**
 378          * Removes the boot event listener.
 379          *
 380          * @since       2.1
 381          *
 382          * @return      An error code
 383          * @param[in]   listener        The boot event listener
 384          * @exception   E_SUCCESS       The method is successful.
 385          * @exception   E_OBJ_ALREADY_EXIST     The listener is not added.
 386          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 387          */
 388         static result RemoveBootEventListener(IBootEventListener& listener);
 389
 390 private:
 391         /**
 392          * 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.
 393          */
 394         PowerManager(void);
 395         /**
 396          * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
 397          */
 398         virtual ~PowerManager(void);
 399
 400         /**
 401          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 402          */
 403         PowerManager(const PowerManager& value);
 404
 405         /**
 406          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 407          */
 408         PowerManager& operator = (const PowerManager& value);
 409
 410 private:
 411         friend class _PowerManagerImpl;
 412         class _PowerManagerImpl* __pPowerManagerImpl;
 413 }; // PowerManager
 414
 415 } } // Tizen::System
 416
 417 #endif // _FSYS_POWER_MANAGER_H_