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          * @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          * @deprecated This method is deprecated. @n
 271          *               Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
 272          * @since       2.0
 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
 291          * @see RemoveChargingEventListener()
 292          */
 293         static result AddChargingEventListener(IChargingEventListener& listener);
 294
 295         /**
 296          * Removes the charging event listener.
 297          *
 298          * @since       2.1
 299          *
 300          * @param[in]   listener                The charging event listener
 301          * @exception E_SUCCESS               The method is successful.
 302          * @exception E_OBJ_NOT_FOUND     The specified listener cannot be found.
 303          * @exception E_SYSTEM                The method cannot proceed due to a severe system error.
 304          * @see IChargingEventListener
 305          * @see AddChargingEventListener()
 306          */
 307         static result RemoveChargingEventListener(IChargingEventListener& listener);
 308
 309         /**
 310          * Sets the battery event listener.
 311          *
 312          * @since       2.0
 313          *
 314          * @return      An error code
 315          * @param[in]   pListener       The battery event listener
 316          * @exception   E_SUCCESS       The method is successful.
 317          * @exception   E_SYSTEM        A system error has occurred.
 318          * @remarks     If @c pListener is set to @c null, the pre-registered listener is unregistered.
 319          */
 320         static result SetBatteryEventListener(IBatteryEventListener* pListener);
 321
 322         /**
 323          * Gets the current charge remaining in the battery as a percentage.
 324          *
 325          * @since 2.0
 326          *
 327          * @return      The percentage of the charge remaining in the battery.
 328          * @exception   E_SUCCESS               The method is successful.
 329          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 330          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 331          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 332          * @remarks     The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
 333          */
 334         static int GetCurrentBatteryLevelInPercentage(void);
 335
 336         /**
 337          * Gets the current charging level of the battery.
 338          *
 339          * @since 2.0
 340          *
 341          * @return      A value from the enumerator BatteryLevel indicating the current charging level
 342          * @exception   E_SUCCESS               The method is successful.
 343          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 344          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 345          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 346          */
 347         static BatteryLevel GetCurrentBatteryLevel(void);
 348
 349         /**
 350          * Checks whether the battery is currently charging.
 351          *
 352          * @since 2.0
 353          *
 354          * @return      @c true if the charging cable is connected to the phone, @n
 355          *              else @c false
 356          * @exception   E_SUCCESS               The method is successful.
 357          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 358          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 359          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 360          */
 361         static bool IsCharging(void);
 362
 363         /**
 364          * Adds the boot event listener.
 365          *
 366          * @since       2.1
 367          *
 368          * @return      An error code
 369          * @param[in]   listener        The boot event listener
 370          * @exception   E_SUCCESS       The method is successful.
 371          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 372          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 373          */
 374         static result AddBootEventListener(IBootEventListener& listener);
 375
 376         /**
 377          * Removes the boot event listener.
 378          *
 379          * @since       2.1
 380          *
 381          * @return      An error code
 382          * @param[in]   listener        The boot event listener
 383          * @exception   E_SUCCESS       The method is successful.
 384          * @exception   E_OBJ_ALREADY_EXIST     The listener is not added.
 385          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 386          */
 387         static result RemoveBootEventListener(IBootEventListener& listener);
 388
 389 private:
 390         /**
 391          * 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.
 392          */
 393         PowerManager(void);
 394         /**
 395          * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
 396          */
 397         virtual ~PowerManager(void);
 398
 399         /**
 400          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 401          */
 402         PowerManager(const PowerManager& value);
 403
 404         /**
 405          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 406          */
 407         PowerManager& operator = (const PowerManager& value);
 408
 409 private:
 410         friend class _PowerManagerImpl;
 411         class _PowerManagerImpl* __pPowerManagerImpl;
 412 }; // PowerManager
 413
 414 } } // Tizen::System
 415
 416 #endif // _FSYS_POWER_MANAGER_H_