//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
class IScreenEventListener;
class IChargingEventListener;
class IBatteryEventListener;
+class IBootEventListener;
/**
* @enum BatteryLevel
BATTERY_LOW, // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_LOW.
BATTERY_CRITICAL, // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_CRITICAL.
BATTERY_EMPTY, // This enum value is deprecated. Instead of using this enum value, use BATTERY_LEVEL_EMPTY.
- BATTERY_LEVEL_FULL = BATTERY_FULL,/**< The battery is fully charged */
- BATTERY_LEVEL_HIGH = BATTERY_HIGH,/**< The battery has plenty of charge */
- BATTERY_LEVEL_LOW = BATTERY_LOW,/**< The battery has little charge */
- 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. */
- 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. */
+ BATTERY_LEVEL_FULL = BATTERY_FULL, /**< The battery is fully charged */
+ BATTERY_LEVEL_HIGH = BATTERY_HIGH, /**< The battery has plenty of charge */
+ BATTERY_LEVEL_LOW = BATTERY_LOW, /**< The battery has little charge */
+ 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. */
+ 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. */
};
/**
* @enum PowerMode
*
- * Defines the representation of the charge remaining in the battery.
+ * Defines the representation of the power mode.
*
* @since 2.0
*/
{
POWER_STANDBY, // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_STANDBY.
POWER_SLEEP, // This enum value is deprecated. Instead of using this enum value, use POWER_MODE_SLEEP.
- POWER_MODE_STANDBY = POWER_STANDBY, /**< The battery is fully charged */
- POWER_MODE_SLEEP = POWER_SLEEP, /**< The battery has plenty of charge */
+ POWER_MODE_STANDBY = POWER_STANDBY, /**< The standby power mode */
+ POWER_MODE_SLEEP = POWER_SLEEP, /**< The sleep power mode */
};
/**
/**
* Changes the policy of the screen power management.
*
- * @since 2.0
+ * @since 2.0
*
+ * @privlevel public
* @privilege %http://tizen.org/privilege/power
*
- * @return An error code
- * @param[in] keepOn Set to @c true if the screen remains in the 'ON' state until the application goes to the background, @n
- * else @c false if the state of the screen is controlled by the default power control policy of the system
- * @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
- * else @c false if the screen is not dimmed
- * @exception E_SUCCESS The method is successful.
- * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
- * @exception E_SYSTEM A system error has occurred.
- * @remarks The application should explicitly call this method again, if the screen is to be kept 'ON' after coming back from the background state.
+ * @return An error code
+ * @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
+ * else @c false for the state of the screen to be controlled by the default power control policy of the system
+ * @param[in] dimming Set to @c true to dim the screen when there is no user input for a certain amount of time, @n
+ * else @c false to not dim the screen
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
+ * @exception E_SYSTEM A system error has occurred.
+ * @remarks The screen power control is available only when an application is active. @n
+ * To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method.
*/
static result KeepScreenOnState(bool keepOn, bool dimming = true);
/**
* Restores the screen brightness control.
*
- * @since 2.0
+ * @since 2.0
*
- * @return An error code
- * @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE The brightness is never changed.
- * @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @see SetScreenBrightness()
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_INVALID_STATE The brightness is never changed.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @see SetScreenBrightness()
*/
static result RestoreScreenBrightness(void);
/**
* Sets the screen brightness level for an application.
*
- * @since 2.0
+ * @since 2.0
+ *
+ * @privlevel public
* @privilege %http://tizen.org/privilege/power
*
- * @return An error code
- * @param[in] brightness The brightness level to set @n
- * The parameter value can range between @c 1 (minimum) and @c 10 (maximum).
- * @exception E_SUCCESS The method is successful.
+ * @return An error code
+ * @param[in] brightness The brightness level to set between @c 1 (minimum) and @c 10 (maximum).
+ * @exception E_SUCCESS The method is successful.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @exception E_OUT_OF_RANGE The specified @c brightness is out of range.
- * @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @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.
- * @see RestoreScreenBrightness()
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @remarks The brightness level change is available only when an application is active. @n
+ * To check the events that are active, use the Tizen::Ui::Controls::IFrameEventListener::OnFrameActivated() method. @n
+ * 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. @n
+ * To know more about turning the screen off, see the TurnScreenOff() method.
+ * @see RestoreScreenBrightness()
*/
static result SetScreenBrightness(int brightness);
/**
* Gets the screen brightness level of an application.
*
- * @since 2.0
+ * @since 2.0
*
- * @return The brightness level of the current application
- * @exception E_SUCCESS The method is successful.
- * @exception E_SYSTEM A system error has occurred.
- * @remarks The specific error code can be accessed using the GetLastResult() method.
- * @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
- * In case of error, this method returns @c -1.
+ * @return The brightness level of the current application, @n
+ * else @c -1 in case of error
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_SYSTEM A system error has occurred.
+ * @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.
+ * - The specific error code can be accessed using the GetLastResult() method.
*/
static int GetScreenBrightness(void);
/**
* Checks whether the screen is on.
*
- * @since 2.0
+ * @since 2.0
*
- * @return @c true if the screen is on, @n
- * else @c false
- * @exception E_SUCCESS The method is successful.
- * @exception E_SYSTEM A system error has occurred.
- * @remarks The specific error code can be accessed using the GetLastResult() method.
- * @remarks This method returns @c true when the screen is in the dimming state, and @c false in case of an error.
+ * @return @c true if the screen is on, @n
+ * else @c false
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_SYSTEM A system error has occurred.
+ * @remarks
+ * - This method returns @c true when the screen is in the dimming state, and @c false in case of an error.
+ * - The specific error code can be accessed using the GetLastResult() method.
*/
static bool IsScreenOn(void);
/**
- * Turns on the screen.
+ * Turns the screen on.
*
- * @since 2.0
+ * @since 2.0
*
+ * @privlevel public
* @privilege %http://tizen.org/privilege/power
- * @return An error code
- * @exception E_SUCCESS The method is successful.
+ *
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
- * @exception E_SYSTEM A system error has occurred.
+ * @exception E_SYSTEM A system error has occurred.
*/
static result TurnScreenOn(void);
/**
- * Turns off the screen.
+ * Turns the screen off.
*
- * @since 2.0
+ * @since 2.0
*
+ * @privlevel public
* @privilege %http://tizen.org/privilege/power
- * @return An error code
- * @exception E_SUCCESS The method is successful.
+ *
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
- * @exception E_SYSTEM A system error has occurred.
+ * @exception E_SYSTEM A system error has occurred.
*/
static result TurnScreenOff(void);
/**
- * Changes the policy of the CPU (Central Processing Unit) power management.
+ * Sets the policy of the CPU (Central Processing Unit) power management.
*
- * @since 2.0
+ * @since 2.0
*
+ * @privlevel public
* @privilege %http://tizen.org/privilege/power
*
- * @return An error code
+ * @return An error code
* @param[in] enable Set to @c true to prevent the CPU from going into sleep mode, @n
- * else @c false to let the state of the CPU follow the system default power management policy
- * @exception E_SUCCESS The method is successful.
+ * else @c false to let the state of the CPU follow the system default power management policy
+ * @exception E_SUCCESS The method is successful.
* @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
- * @exception E_SYSTEM A system error has occurred.
+ * @exception E_SYSTEM A system error has occurred.
+ * @remarks This method only manages the CPU power state. The screen state or lock screen is not managed by this method.
*/
static result KeepCpuAwake(bool enable);
/**
* Sets the screen event listener.
*
- * @since 2.0
+ * @brief <i>[Deprecated]</i>
+ * @deprecated This method is deprecated. @n
+ * Instead of using this method, use AddScreenEventListener() and RemoveScreenEventListener().
+ * @since 2.0
*
* @param[in] listener The screen event listener
- * @see IScreenEventListener
+ * @remarks This method always overwrites the first element of internal IScreenEventListener list. @n
+ * The first element added by AddScreenEventListener() may be overwritten by this method,
+ * which may not be an expected behavior by API users. So, it is not recommended to use this method.
*/
static void SetScreenEventListener(IScreenEventListener& listener);
+
+ /**
+ * Adds the screen event listener.
+ *
+ * @since 2.1
+ *
+ * @param[in] listener The screen event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_ALREADY_EXIST The listener has already been added.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @see RemoveScreenEventListener()
+ */
+ static result AddScreenEventListener(IScreenEventListener& listener);
+
+ /**
+ * Removes the specified screen event listener.
+ *
+ * @since 2.1
+ *
+ * @param[in] listener The screen event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_NOT_FOUND The specified listener cannot be found.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @see AddScreenEventListener()
+ */
+ static result RemoveScreenEventListener(IScreenEventListener& listener);
+
+
/**
* Sets the charging event listener.
*
- * @since 2.0
+ * @brief <i>[Deprecated]</i>
+ * @deprecated This method is deprecated. @n
+ * Instead of using this method, use AddChargingEventListener() and RemoveChargingEventListener().
+ * @since 2.0
*
* @param[in] listener The charging event listener
+ * @remarks
+ * - This method always overwrites the first element of internal IChargingEventListener list.
+ * - The first element added by AddChargingEventListener() may be overwritten by this method,
+ * which may not be the expected behavior. So, it is not recommended to use this method.
*/
static void SetChargingEventListener(IChargingEventListener& listener);
/**
+ * Adds the charging event listener.
+ *
+ * @since 2.1
+ *
+ * @param[in] listener The charging event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_ALREADY_EXIST The listener has already been added.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @see RemoveChargingEventListener()
+ */
+ static result AddChargingEventListener(IChargingEventListener& listener);
+
+ /**
+ * Removes the charging event listener.
+ *
+ * @since 2.1
+ *
+ * @param[in] listener The charging event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_NOT_FOUND The specified listener cannot be found.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @see AddChargingEventListener()
+ */
+ static result RemoveChargingEventListener(IChargingEventListener& listener);
+
+ /**
* Sets the battery event listener.
*
* @since 2.0
* @param[in] pListener The battery event listener
* @exception E_SUCCESS The method is successful.
* @exception E_SYSTEM A system error has occurred.
- * @remarks If @c pListener is set to @c null, the pre-registered listener is unregistered.
+ * @remarks If @c pListener is set to @c null, the current listener is unregistered.
*/
static result SetBatteryEventListener(IBatteryEventListener* pListener);
*
* @since 2.0
*
- * @return The percentage of the charge remaining in the battery.
- * @exception E_SUCCESS The method is successful.
- * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
- * @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remakrs The specific error code can be accessed using the GetLastResult() method.
- * @remarks The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
+ * @return The percentage of the charge remaining in the battery.
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @remarks
+ * - The resolution of the level is @c 1 percentage. The range of the level is minimum @c 0 to maximum @c 100.
+ * - The specific error code can be accessed using the GetLastResult() method.
*/
static int GetCurrentBatteryLevelInPercentage(void);
*
* @since 2.0
*
- * @return A value from the enumerator BatteryLevel indicating the current charging level
- * @exception E_SUCCESS The method is successful.
- * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
- * @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks The specific error code can be accessed using the GetLastResult() method.
+ * @return A value from the enumerator BatteryLevel indicating the current charging level
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
static BatteryLevel GetCurrentBatteryLevel(void);
/**
* Checks whether the battery is currently charging.
*
- * @since 2.0
+ * @since 2.0
*
- * @return @c true if the charging cable is connected to the phone, @n
- * else @c false
- * @exception E_SUCCESS The method is successful.
- * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
- * @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks The specific error code can be accessed using the GetLastResult() method.
+ * @return @c true if the charging cable is connected to the phone, @n
+ * else @c false
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_UNSUPPORTED_OPERATION The method is not supported by this device.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ * @remarks The specific error code can be accessed using the GetLastResult() method.
*/
static bool IsCharging(void);
+ /**
+ * Adds the boot event listener.
+ *
+ * @since 2.1
+ *
+ * @return An error code
+ * @param[in] listener The boot event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_ALREADY_EXIST The listener is already added.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ */
+ static result AddBootEventListener(IBootEventListener& listener);
+
+ /**
+ * Removes the boot event listener.
+ *
+ * @since 2.1
+ *
+ * @return An error code
+ * @param[in] listener The boot event listener
+ * @exception E_SUCCESS The method is successful.
+ * @exception E_OBJ_ALREADY_EXIST The listener is not added.
+ * @exception E_SYSTEM The method cannot proceed due to a severe system error.
+ */
+ static result RemoveBootEventListener(IBootEventListener& listener);
+
private:
/**
* 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.