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
  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          * @privilege   %http://tizen.org/privilege/power
  99          *
 100          * @return      An error code
 101          * @param[in]   keepOn  Set to @c true if the screen remains in the 'ON' state until the application goes to the background, @n
 102          *                      else @c false if the state of the screen is controlled by the default power control policy of the system
 103          * @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
 104          *                      else @c false if the screen is not dimmed
 105          * @exception   E_SUCCESS               The method is successful.
 106          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 107          * @exception   E_SYSTEM                A system error has occurred.
 108          * @remarks     The application should explicitly call this method again, if the screen is to be kept 'ON' after coming back from the background state.
 109          */
 110         static result KeepScreenOnState(bool keepOn, bool dimming = true);
 111
 112         /**
 113          * Restores the screen brightness control.
 114          *
 115          * @since 2.0
 116          *
 117          * @return An error code
 118          * @exception   E_SUCCESS The method is successful.
 119          * @exception   E_INVALID_STATE The brightness is never changed.
 120          * @exception   E_SYSTEM The method cannot proceed due to a severe system error.
 121          * @see         SetScreenBrightness()
 122          */
 123         static result RestoreScreenBrightness(void);
 124
 125         /**
 126          * Sets the screen brightness level for an application.
 127          *
 128          * @since       2.0
 129          * @privilege   %http://tizen.org/privilege/power
 130          *
 131          * @return      An error code
 132          * @param[in]   brightness      The brightness level to set @n
 133          *                              The parameter value can range between @c 1 (minimum) and @c 10 (maximum).
 134          * @exception   E_SUCCESS       The method is successful.
 135          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 136          * @exception   E_OUT_OF_RANGE          The specified @c brightness is out of range.
 137          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 138          * @remarks     This brightness level is only available when an application is running on the foreground. 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.
 139          * @see         RestoreScreenBrightness()
 140          */
 141
 142         static result SetScreenBrightness(int brightness);
 143         /**
 144          * Gets the screen brightness level of an application.
 145          *
 146          * @since       2.0
 147          *
 148          * @return      The brightness level of the current application
 149          * @exception   E_SUCCESS             The method is successful.
 150          * @exception   E_SYSTEM         A system error has occurred.
 151          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 152          * @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
 153          *              In case of error, this method returns @c -1.
 154          */
 155         static int GetScreenBrightness(void);
 156
 157         /**
 158          * Checks whether the screen is on.
 159          *
 160          * @since       2.0
 161          *
 162          * @return      @c true if the screen is on, @n
 163          *              else @c false
 164          * @exception   E_SUCCESS       The method is successful.
 165          * @exception   E_SYSTEM        A system error has occurred.
 166          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 167          * @remarks     This method returns @c true when the screen is in the dimming state, and @c false in case of an error.
 168          */
 169         static bool IsScreenOn(void);
 170
 171         /**
 172          * Turns on the screen.
 173          *
 174          * @since       2.0
 175          *
 176          * @privilege   %http://tizen.org/privilege/power
 177          * @return      An error code
 178          * @exception   E_SUCCESS               The method is successful.
 179          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 180          * @exception   E_SYSTEM                A system error has occurred.
 181          */
 182         static result TurnScreenOn(void);
 183
 184         /**
 185          * Turns off the screen.
 186          *
 187          * @since       2.0
 188          *
 189          * @privilege   %http://tizen.org/privilege/power
 190          * @return      An error code
 191          * @exception   E_SUCCESS               The method is successful.
 192          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 193          * @exception   E_SYSTEM                A system error has occurred.
 194          */
 195         static result TurnScreenOff(void);
 196
 197         /**
 198          * Changes the policy of the CPU (Central Processing Unit) power management.
 199          *
 200          * @since       2.0
 201          *
 202          * @privilege   %http://tizen.org/privilege/power
 203          *
 204          * @return      An error code
 205          * @param[in]   enable  Set to @c true to prevent the CPU from going into sleep mode, @n
 206          *              else @c false to let the state of the CPU follow the system default power management policy
 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 KeepCpuAwake(bool enable);
 212
 213         /**
 214          * Sets the screen event listener.
 215          *
 216          * @since       2.0
 217          *
 218          * @param[in]   listener                The screen event listener
 219          * @see         IScreenEventListener
 220          */
 221         static void SetScreenEventListener(IScreenEventListener& listener);
 222
 223         /**
 224          * Sets the charging event listener.
 225          *
 226          * @since       2.0
 227          *
 228          * @param[in]   listener        The charging event listener
 229          */
 230         static void SetChargingEventListener(IChargingEventListener& listener);
 231
 232         /**
 233          * Sets the battery event listener.
 234          *
 235          * @since       2.0
 236          *
 237          * @return      An error code
 238          * @param[in]   pListener       The battery event listener
 239          * @exception   E_SUCCESS       The method is successful.
 240          * @exception   E_SYSTEM        A system error has occurred.
 241          * @remarks     If @c pListener is set to @c null, the pre-registered listener is unregistered.
 242          */
 243         static result SetBatteryEventListener(IBatteryEventListener* pListener);
 244
 245         /**
 246          * Gets the current charge remaining in the battery as a percentage.
 247          *
 248          * @since 2.0
 249          *
 250          * @return      The percentage of the charge remaining in the battery.
 251          * @exception   E_SUCCESS               The method is successful.
 252          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 253          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 254          * @remakrs     The specific error code can be accessed using the GetLastResult() method.
 255          * @remarks     The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
 256          */
 257         static int GetCurrentBatteryLevelInPercentage(void);
 258
 259         /**
 260          * Gets the current charging level of the battery.
 261          *
 262          * @since 2.0
 263          *
 264          * @return      A value from the enumerator BatteryLevel indicating the current charging level
 265          * @exception   E_SUCCESS               The method is successful.
 266          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 267          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 268          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 269          */
 270         static BatteryLevel GetCurrentBatteryLevel(void);
 271
 272         /**
 273          * Checks whether the battery is currently charging.
 274          *
 275          * @since 2.0
 276          *
 277          * @return      @c true if the charging cable is connected to the phone, @n
 278          *              else @c false
 279          * @exception   E_SUCCESS               The method is successful.
 280          * @exception   E_UNSUPPORTED_OPERATION The method is not supported by this device.
 281          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 282          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 283          */
 284         static bool IsCharging(void);
 285
 286 private:
 287         /**
 288          * 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.
 289          */
 290         PowerManager(void);
 291         /**
 292          * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
 293          */
 294         virtual ~PowerManager(void);
 295
 296         /**
 297          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 298          */
 299         PowerManager(const PowerManager& value);
 300
 301         /**
 302          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 303          */
 304         PowerManager& operator = (const PowerManager& value);
 305
 306 private:
 307         friend class _PowerManagerImpl;
 308         class _PowerManagerImpl* __pPowerManagerImpl;
 309 }; // PowerManager
 310
 311 } } // Tizen::System
 312
 313 #endif // _FSYS_POWER_MANAGER_H_