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
  56                                                                                                         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
  58                                                                                                         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.  */
  59 };
  60
  61 /**
  62  * @enum        PowerMode
  63  *
  64  * Defines the representation of the power mode.
  65  *
  66  * @since       2.0
  67  */
  68 enum PowerMode
  69 {
  70         POWER_STANDBY,                          // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_STANDBY.
  71         POWER_SLEEP,                            // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_SLEEP.
  72         POWER_MODE_STANDBY = POWER_STANDBY,     /**< The standby power mode */
  73         POWER_MODE_SLEEP = POWER_SLEEP,         /**< The sleep power mode */
  74 };
  75
  76 /**
  77  * @class       PowerManager
  78  * @brief       This class provides methods for power management.
  79  *
  80  * @since       2.0
  81  *
  82  * @final       This class is not intended for extension.
  83  *
  84  * The %PowerManager class provides methods for managing the device power state.
  85  *
  86  * 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>.
  87
  88  */
  89
  90 class _OSP_EXPORT_ PowerManager
  91         : public Tizen::Base::Object
  92 {
  93
  94 public:
  95         /**
  96          * Changes the policy of the screen power management.
  97          *
  98          * @since               2.0
  99          *
 100          * @privlevel   public
 101          * @privilege   %http://tizen.org/privilege/power
 102          *
 103          * @return              An error code
 104          * @param[in]   keepOn  Set to @c true for the screen to remain in the 'ON' state until the application goes to the background(inactivated), @n
 105          *                      else @c false for the state of the screen to be controlled by the default power control policy of the system
 106          * @param[in]   dimming Set to @c true to dim the screen when there is no user input for a certain amount of time, @n
 107          *                      else @c false to not dim the screen
 108          * @exception   E_SUCCESS                               The method is successful.
 109          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 110          * @exception   E_SYSTEM                                A system error has occurred.
 111          * @remarks     The screen power control is available only when an application is active. @n
 112          *                      To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method.
 113          */
 114         static result KeepScreenOnState(bool keepOn, bool dimming = true);
 115
 116         /**
 117          * Restores the screen brightness control.
 118          *
 119          * @since               2.0
 120          *
 121          * @return              An error code
 122          * @exception   E_SUCCESS                       The method is successful.
 123          * @exception   E_INVALID_STATE         The brightness is never changed.
 124          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 125          * @see                 SetScreenBrightness()
 126          */
 127         static result RestoreScreenBrightness(void);
 128
 129         /**
 130          * Sets the screen brightness level for an application.
 131          *
 132          * @since               2.0
 133          *
 134          * @privlevel   public
 135          * @privilege   %http://tizen.org/privilege/power
 136          *
 137          * @return              An error code
 138          * @param[in]   brightness                      The brightness level to set between @c 1 (minimum) and @c 10 (maximum).
 139          * @exception   E_SUCCESS                       The method is successful.
 140          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 141          * @exception   E_OUT_OF_RANGE          The specified @c brightness is out of range.
 142          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 143          * @remarks     The brightness level change is available only when an application is active. @n
 144          *                      To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method. @n
 145          *                      Even if the brightness is set to level 1, a black screen is not displayed.
 146          *                      Level 1 is the minimum brightness level that can be set for an application. @n
 147          *                      To know more about turning the screen off, see the TurnScreenOff() method.
 148          * @see                 RestoreScreenBrightness()
 149          */
 150
 151         static result SetScreenBrightness(int brightness);
 152         /**
 153          * Gets the screen brightness level of an application.
 154          *
 155          * @since               2.0
 156          *
 157          * @return              The brightness level of the current application, @n
 158          *                              else @c -1 in case of error
 159          * @exception   E_SUCCESS               The method is successful.
 160          * @exception   E_SYSTEM                A system error has occurred.
 161          * @remarks
 162          *                      - This method returns the screen brightness level set for an application. If the brightness level is not set,
 163          *                      it will return the default system brightness level.
 164          *                      - The specific error code can be accessed using the GetLastResult() method.
 165          */
 166         static int GetScreenBrightness(void);
 167
 168         /**
 169          * Checks whether the screen is on.
 170          *
 171          * @since               2.0
 172          *
 173          * @return              @c true if the screen is on, @n
 174          *                              else @c false
 175          * @exception   E_SUCCESS               The method is successful.
 176          * @exception   E_SYSTEM                A system error has occurred.
 177          * @remarks
 178          *                              - This method returns @c true when the screen is in the dimming state, and @c false in case of an error.
 179          *                              - The specific error code can be accessed using the GetLastResult() method.
 180          */
 181         static bool IsScreenOn(void);
 182
 183         /**
 184          * Turns the screen on.
 185          *
 186          * @since               2.0
 187          *
 188          * @privlevel   public
 189          * @privilege   %http://tizen.org/privilege/power
 190          *
 191          * @return              An error code
 192          * @exception   E_SUCCESS                       The method is successful.
 193          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 194          * @exception   E_SYSTEM                        A system error has occurred.
 195          */
 196         static result TurnScreenOn(void);
 197
 198         /**
 199          * Turns the screen off.
 200          *
 201          * @since               2.0
 202          *
 203          * @privlevel   public
 204          * @privilege   %http://tizen.org/privilege/power
 205          *
 206          * @return              An error code
 207          * @exception   E_SUCCESS                       The method is successful.
 208          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 209          * @exception   E_SYSTEM                        A system error has occurred.
 210          */
 211         static result TurnScreenOff(void);
 212
 213         /**
 214          * Sets the policy of the CPU (Central Processing Unit) power management.
 215          *
 216          * @since               2.0
 217          *
 218          * @privlevel   public
 219          * @privilege   %http://tizen.org/privilege/power
 220          *
 221          * @return              An error code
 222          * @param[in]   enable  Set to @c true to prevent the CPU from going into sleep mode, @n
 223          *                                              else @c false to let the state of the CPU follow the system default power management policy
 224          * @exception   E_SUCCESS                       The method is successful.
 225          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 226          * @exception   E_SYSTEM                        A system error has occurred.
 227          * @remarks             This method only manages the CPU power state. The screen state or lock screen is not managed by this method.
 228          */
 229         static result KeepCpuAwake(bool enable);
 230
 231         /**
 232          * Sets the screen event listener.
 233          *
 234          * @brief               <i>[Deprecated]</i>
 235          * @deprecated  This method is deprecated. @n
 236          *                              Instead of using this method, use AddScreenEventListener() and RemoveScreenEventListener().
 237          * @since               2.0
 238          *
 239          * @param[in]   listener                The screen event listener
 240          * @remarks             This method always overwrites the first element of internal IScreenEventListener list. @n
 241          *                              The first element added by AddScreenEventListener() may be overwritten by this method,
 242          *                              which may not be an expected behavior by API users. So, it is not recommended to use this method.
 243          */
 244         static void SetScreenEventListener(IScreenEventListener& listener);
 245
 246
 247         /**
 248          * Adds the screen event listener.
 249          *
 250          * @since       2.1
 251          *
 252          * @param[in]   listener                                The screen event listener
 253          * @exception   E_SUCCESS                               The method is successful.
 254          * @exception   E_OBJ_ALREADY_EXIST             The listener has already been added.
 255          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 256          * @see         RemoveScreenEventListener()
 257          */
 258         static result AddScreenEventListener(IScreenEventListener& listener);
 259
 260         /**
 261          * Removes the specified screen event listener.
 262          *
 263          * @since       2.1
 264          *
 265          * @param[in]   listener                        The screen event listener
 266          * @exception   E_SUCCESS                       The method is successful.
 267          * @exception   E_OBJ_NOT_FOUND         The specified listener cannot be found.
 268          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 269          * @see         AddScreenEventListener()
 270          */
 271         static result RemoveScreenEventListener(IScreenEventListener& listener);
 272
 273
 274         /**
 275          * Sets the charging event listener.
 276          *
 277          * @brief               <i>[Deprecated]</i>
 278          * @deprecated  This method is deprecated. @n
 279          *                              Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
 280          * @since               2.0
 281          *
 282          * @param[in]   listener        The charging event listener
 283          * @remarks
 284          *                              - This method always overwrites the first element of internal IChargingEventListener list.
 285          *                              - The first element added by AddChargingEventListener() may be overwritten by this method,
 286          *                              which may not be the expected behavior. So, it is not recommended to use this method.
 287          */
 288         static void SetChargingEventListener(IChargingEventListener& listener);
 289
 290         /**
 291          * Adds the charging event listener.
 292          *
 293          * @since               2.1
 294          *
 295          * @param[in]   listener                                The charging event listener
 296          * @exception   E_SUCCESS                               The method is successful.
 297          * @exception   E_OBJ_ALREADY_EXIST             The listener has already been added.
 298          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 299          * @see                 RemoveChargingEventListener()
 300          */
 301         static result AddChargingEventListener(IChargingEventListener& listener);
 302
 303         /**
 304          * Removes the charging event listener.
 305          *
 306          * @since               2.1
 307          *
 308          * @param[in]   listener                        The charging event listener
 309          * @exception   E_SUCCESS                       The method is successful.
 310          * @exception   E_OBJ_NOT_FOUND         The specified listener cannot be found.
 311          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 312          * @see                 AddChargingEventListener()
 313          */
 314         static result RemoveChargingEventListener(IChargingEventListener& listener);
 315
 316         /**
 317          * Sets the battery event listener.
 318          *
 319          * @since       2.0
 320          *
 321          * @return      An error code
 322          * @param[in]   pListener       The battery event listener
 323          * @exception   E_SUCCESS       The method is successful.
 324          * @exception   E_SYSTEM        A system error has occurred.
 325          * @remarks             If @c pListener is set to @c null, the current listener is unregistered.
 326          */
 327         static result SetBatteryEventListener(IBatteryEventListener* pListener);
 328
 329         /**
 330          * Gets the current charge remaining in the battery as a percentage.
 331          *
 332          * @since 2.0
 333          *
 334          * @return              The percentage of the charge remaining in the battery.
 335          * @exception   E_SUCCESS                                       The method is successful.
 336          * @exception   E_UNSUPPORTED_OPERATION         The method is not supported by this device.
 337          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
 338          * @remarks
 339          *                              - The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
 340          *                              - The specific error code can be accessed using the GetLastResult() method.
 341          */
 342         static int GetCurrentBatteryLevelInPercentage(void);
 343
 344         /**
 345          * Gets the current charging level of the battery.
 346          *
 347          * @since 2.0
 348          *
 349          * @return              A value from the enumerator BatteryLevel indicating the current charging level
 350          * @exception   E_SUCCESS                                       The method is successful.
 351          * @exception   E_UNSUPPORTED_OPERATION         The method is not supported by this device.
 352          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
 353          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 354          */
 355         static BatteryLevel GetCurrentBatteryLevel(void);
 356
 357         /**
 358          * Checks whether the battery is currently charging.
 359          *
 360          * @since               2.0
 361          *
 362          * @return              @c true if the charging cable is connected to the phone, @n
 363          *                              else @c false
 364          * @exception   E_SUCCESS                                       The method is successful.
 365          * @exception   E_UNSUPPORTED_OPERATION         The method is not supported by this device.
 366          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
 367          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 368          */
 369         static bool IsCharging(void);
 370
 371         /**
 372          * Adds the boot event listener.
 373          *
 374          * @since       2.1
 375          *
 376          * @return      An error code
 377          * @param[in]   listener                        The boot event listener
 378          * @exception   E_SUCCESS                       The method is successful.
 379          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 380          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 381          */
 382         static result AddBootEventListener(IBootEventListener& listener);
 383
 384         /**
 385          * Removes the boot event listener.
 386          *
 387          * @since               2.1
 388          *
 389          * @return      An error code
 390          * @param[in]   listener                        The boot event listener
 391          * @exception   E_SUCCESS                       The method is successful.
 392          * @exception   E_OBJ_ALREADY_EXIST     The listener is not added.
 393          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 394          */
 395         static result RemoveBootEventListener(IBootEventListener& listener);
 396
 397 private:
 398         /**
 399          * 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.
 400          */
 401         PowerManager(void);
 402         /**
 403          * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
 404          */
 405         virtual ~PowerManager(void);
 406
 407         /**
 408          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 409          */
 410         PowerManager(const PowerManager& value);
 411
 412         /**
 413          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 414          */
 415         PowerManager& operator = (const PowerManager& value);
 416
 417 private:
 418         friend class _PowerManagerImpl;
 419         class _PowerManagerImpl* __pPowerManagerImpl;
 420 }; // PowerManager
 421
 422 } } // Tizen::System
 423
 424 #endif // _FSYS_POWER_MANAGER_H_