3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FSysPowerManager.h
20 * @brief This is the header file for the %PowerManager class.
22 * This header file contains the declarations of the %PowerManager class.
25 #ifndef _FSYS_POWER_MANAGER_H_
26 #define _FSYS_POWER_MANAGER_H_
28 #include <FBaseObject.h>
30 namespace Tizen { namespace System
33 class IScreenEventListener;
34 class IChargingEventListener;
35 class IBatteryEventListener;
36 class IBootEventListener;
41 * Defines the representation of the remaining charge in the battery.
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. */
62 * Defines the representation of the charge remaining in the battery.
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 */
76 * @brief This class provides methods for power management.
80 * @final This class is not intended for extension.
82 * The %PowerManager class provides methods for managing the device power state.
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>.
88 class _OSP_EXPORT_ PowerManager
89 : public Tizen::Base::Object
94 * Changes the policy of the screen power management.
99 * @privilege %http://tizen.org/privilege/power
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.
111 static result KeepScreenOnState(bool keepOn, bool dimming = true);
114 * Restores the screen brightness control.
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()
124 static result RestoreScreenBrightness(void);
127 * Sets the screen brightness level for an application.
132 * @privilege %http://tizen.org/privilege/power
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()
145 static result SetScreenBrightness(int brightness);
147 * Gets the screen brightness level of an application.
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.
158 static int GetScreenBrightness(void);
161 * Checks whether the screen is on.
165 * @return @c true if the screen is on, @n
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.
172 static bool IsScreenOn(void);
175 * Turns on the screen.
180 * @privilege %http://tizen.org/privilege/power
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.
187 static result TurnScreenOn(void);
190 * Turns off the screen.
195 * @privilege %http://tizen.org/privilege/power
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.
202 static result TurnScreenOff(void);
205 * Changes the policy of the CPU (Central Processing Unit) power management.
210 * @privilege %http://tizen.org/privilege/power
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.
220 static result KeepCpuAwake(bool enable);
223 * Sets the screen event listener.
225 * @deprecated This method is deprecated. @n
226 * Instead of using this method, use AddScreenEventListener() and RemoveScreenEventListener().
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.
234 static void SetScreenEventListener(IScreenEventListener& listener);
238 * Adds the screen event listener.
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()
249 static result AddScreenEventListener(IScreenEventListener& listener);
252 * Removes the screen event listener.
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()
263 static result RemoveScreenEventListener(IScreenEventListener& listener);
267 * Sets the charging event listener.
269 * @deprecated This method is deprecated. @n
270 * Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
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.
278 static void SetChargingEventListener(IChargingEventListener& listener);
281 * Adds the charging event listener.
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()
292 static result AddChargingEventListener(IChargingEventListener& listener);
295 * Removes the charging event listener.
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()
306 static result RemoveChargingEventListener(IChargingEventListener& listener);
309 * Sets the battery event listener.
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.
319 static result SetBatteryEventListener(IBatteryEventListener* pListener);
322 * Gets the current charge remaining in the battery as a percentage.
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.
333 static int GetCurrentBatteryLevelInPercentage(void);
336 * Gets the current charging level of the battery.
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.
346 static BatteryLevel GetCurrentBatteryLevel(void);
349 * Checks whether the battery is currently charging.
353 * @return @c true if the charging cable is connected to the phone, @n
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.
360 static bool IsCharging(void);
363 * Adds the boot event listener.
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.
373 static result AddBootEventListener(IBootEventListener& listener);
376 * Removes the boot event listener.
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.
386 static result RemoveBootEventListener(IBootEventListener& listener);
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.
394 * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
396 virtual ~PowerManager(void);
399 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
401 PowerManager(const PowerManager& value);
404 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
406 PowerManager& operator = (const PowerManager& value);
409 friend class _PowerManagerImpl;
410 class _PowerManagerImpl* __pPowerManagerImpl;
415 #endif // _FSYS_POWER_MANAGER_H_