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
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. */
64 * Defines the representation of the power mode.
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 */
78 * @brief This class provides methods for power management.
82 * @final This class is not intended for extension.
84 * The %PowerManager class provides methods for managing the device power state.
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>.
90 class _OSP_EXPORT_ PowerManager
91 : public Tizen::Base::Object
96 * Changes the policy of the screen power management.
101 * @privilege %http://tizen.org/privilege/power
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.
114 static result KeepScreenOnState(bool keepOn, bool dimming = true);
117 * Restores the screen brightness control.
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()
127 static result RestoreScreenBrightness(void);
130 * Sets the screen brightness level for an application.
135 * @privilege %http://tizen.org/privilege/power
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()
151 static result SetScreenBrightness(int brightness);
153 * Gets the screen brightness level of an application.
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.
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.
166 static int GetScreenBrightness(void);
169 * Checks whether the screen is on.
173 * @return @c true if the screen is on, @n
175 * @exception E_SUCCESS The method is successful.
176 * @exception E_SYSTEM A system error has occurred.
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.
181 static bool IsScreenOn(void);
184 * Turns the screen on.
189 * @privilege %http://tizen.org/privilege/power
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.
196 static result TurnScreenOn(void);
199 * Turns the screen off.
204 * @privilege %http://tizen.org/privilege/power
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.
211 static result TurnScreenOff(void);
214 * Sets the policy of the CPU (Central Processing Unit) power management.
219 * @privilege %http://tizen.org/privilege/power
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.
229 static result KeepCpuAwake(bool enable);
232 * Sets the screen event listener.
234 * @brief <i>[Deprecated]</i>
235 * @deprecated This method is deprecated. @n
236 * Instead of using this method, use AddScreenEventListener() and RemoveScreenEventListener().
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.
244 static void SetScreenEventListener(IScreenEventListener& listener);
248 * Adds the screen event listener.
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()
258 static result AddScreenEventListener(IScreenEventListener& listener);
261 * Removes the specified screen event listener.
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()
271 static result RemoveScreenEventListener(IScreenEventListener& listener);
275 * Sets the charging event listener.
277 * @brief <i>[Deprecated]</i>
278 * @deprecated This method is deprecated. @n
279 * Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
282 * @param[in] listener The charging event listener
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.
288 static void SetChargingEventListener(IChargingEventListener& listener);
291 * Adds the charging event listener.
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()
301 static result AddChargingEventListener(IChargingEventListener& listener);
304 * Removes the charging event listener.
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()
314 static result RemoveChargingEventListener(IChargingEventListener& listener);
317 * Sets the battery event listener.
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.
327 static result SetBatteryEventListener(IBatteryEventListener* pListener);
330 * Gets the current charge remaining in the battery as a percentage.
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.
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.
342 static int GetCurrentBatteryLevelInPercentage(void);
345 * Gets the current charging level of the battery.
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.
355 static BatteryLevel GetCurrentBatteryLevel(void);
358 * Checks whether the battery is currently charging.
362 * @return @c true if the charging cable is connected to the phone, @n
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.
369 static bool IsCharging(void);
372 * Adds the boot event listener.
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.
382 static result AddBootEventListener(IBootEventListener& listener);
385 * Removes the boot event listener.
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.
395 static result RemoveBootEventListener(IBootEventListener& listener);
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.
403 * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
405 virtual ~PowerManager(void);
408 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
410 PowerManager(const PowerManager& value);
413 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
415 PowerManager& operator = (const PowerManager& value);
418 friend class _PowerManagerImpl;
419 class _PowerManagerImpl* __pPowerManagerImpl;
424 #endif // _FSYS_POWER_MANAGER_H_