Tizen Native API
9.0
|
The Power API provides functions to control the power service.
Required Header
#include <device/power.h>
Overview
The Power API provides the way to control the power service. It can be made to hold the specific state to avoid changing display and CPU state internally.
Related Features
This API is related with the following features:
- http://tizen.org/feature/display.state
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from feature element description.
Functions | |
int | device_power_request_lock (power_lock_e type, int timeout_ms) |
Locks the given specific power lock type for a specified time. | |
int | device_power_release_lock (power_lock_e type) |
Releases the given specific power lock type which was locked before. | |
int | device_power_wakeup (bool dim) TIZEN_DEPRECATED_API |
Changes the current power state to the normal/dim state. | |
int | device_power_reboot (const char *reason) |
Sends a request to the deviced Rebooting the current device. |
Enumeration Type Documentation
enum power_lock_e |
Enumeration for lock type.
Each enum ensures that the suitable device is on until all the lock requests have been released or after a timeout.
Enum Type | CPU | Brightness(Display) |
---|---|---|
POWER_LOCK_CPU | ON | OFF |
POWER_LOCK_DISPLAY | ON | ON(Normal) |
POWER_LOCK_DISPLAY_DIM | ON | ON(Dim) |
- Since :
- 2.3
- Remarks:
- An application can lock the specific type.
- These enums are mutually exclusive.
- You cannot combine with an enum below.
- POWER_LOCK_DISPLAY_DIM may be ignored if the DIM state is disabled on the platform.
Function Documentation
int device_power_reboot | ( | const char * | reason | ) |
Sends a request to the deviced Rebooting the current device.
- Warning:
- This is not for use by third-party applications.
Will not return if the reboot is successful.
It operates asynchronously.
- Since :
- 2.3.1
- Privilege Level:
- platform
- Privilege:
- http://tizen.org/privilege/reboot
- Remarks:
- If the power reboot reason is NULL, then it will be set as
"Unknown"
.
- Parameters:
-
[in] reason Pass to the platform and kernel to request special reboot reason, or null
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DEVICE_ERROR_NONE Successful DEVICE_ERROR_INVALID_PARAMETER Invalid parameter DEVICE_ERROR_PERMISSION_DENIED Permission denied DEVICE_ERROR_OPERATION_FAILED Operation failed #include <device/power.h> ... int ret = device_power_reboot("Reason_for_reboot"); if (ret != DEVICE_ERROR_NONE) { ... } ...
- See also:
- device_power_check_reboot_allowed()
int device_power_release_lock | ( | power_lock_e | type | ) |
Releases the given specific power lock type which was locked before.
Releases the lock of specific power lock type that was previously acquired using device_power_request_lock().
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/display
- Remarks:
- If display feature(http://tizen.org/feature/display) is false, then only the type POWER_LOCK_CPU is effective, and the other type returns DEVICE_ERROR_NOT_SUPPORTED. And even thoguh the display feature is false, it requires display privilege(http://tizen.org/privilege/display).
- Parameters:
-
[in] type The power type to release lock
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DEVICE_ERROR_NONE Successful DEVICE_ERROR_INVALID_PARAMETER Invalid parameter DEVICE_ERROR_PERMISSION_DENIED Permission denied DEVICE_ERROR_OPERATION_FAILED Operation failed #include <device/power.h> ... int ret = 0; ret = device_power_request_lock(POWER_LOCK_DISPLAY, 5000); if (ret != DEVICE_ERROR_NONE) { .... } ret = device_power_release_lock(POWER_LOCK_DISPLAY); ...
- See also:
- device_power_request_lock()
- power_lock_e
int device_power_request_lock | ( | power_lock_e | type, |
int | timeout_ms | ||
) |
Locks the given specific power lock type for a specified time.
After the given timeout_ms (in milliseconds), unlock the given lock state automatically. Scenario 1. If the same application requests the same power lock more than twice before it is released or expired,
the timeout will be updated to the latest requested time.
For example: The first request has a timeout of 5000ms.
The second request has a timeout of 1000ms.
If the second request is made before the first request is released or expired,
the timeout will be updated to the latest requested time, which is 1000ms.
Scenario 2. If different applications request the same power lock type,
the power state timeout will be set to the maximum of the requested timeouts.
For example: Application A requests POWER_LOCK_CPU with a timeout of 5000ms.
Application B requests the same POWER_LOCK_CPU with a timeout of 1000ms.
Unless Application A releases the POWER_LOCK_CPU lock,
the timeout for POWER_LOCK_CPU will remain at the maximum requested time, which is 5000ms.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/display
- Remarks:
- If the process dies after success request lock, then every lock will be removed. If display feature(http://tizen.org/feature/display) is false, then only the type POWER_LOCK_CPU is effective, and the other type returns DEVICE_ERROR_NOT_SUPPORTED. And even thoguh the display feature is false, it requires display privilege(http://tizen.org/privilege/display).
- Parameters:
-
[in] type The power type to request lock [in] timeout_ms The positive number in milliseconds or 0
for permanent lock
So you must release the permanent lock of power state with device_power_release_lock() if timeout_ms is zero
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DEVICE_ERROR_NONE Successful DEVICE_ERROR_INVALID_PARAMETER Invalid parameter DEVICE_ERROR_PERMISSION_DENIED Permission denied DEVICE_ERROR_OPERATION_FAILED Operation failed #include <device/power.h> ... int ret = 0; ret = device_power_request_lock(POWER_LOCK_DISPLAY, 5000); if (ret != DEVICE_ERROR_NONE) { .... } ...
- See also:
- device_power_release_lock()
- power_lock_e
int device_power_wakeup | ( | bool | dim | ) |
Changes the current power state to the normal/dim state.
- Deprecated:
- Deprecated Since 2.4
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/display
- Remarks:
- This API triggers turn on process and then updates the status when it completes. While the operation is on-going, the device_display_get_state() function returns previous display state.
- DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: http://tizen.org/feature/display.state.
- Parameters:
-
[in] dim Set true
to set the dim state, otherwise setfalse
to not set the dim state
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DEVICE_ERROR_NONE Successful DEVICE_ERROR_INVALID_PARAMETER Invalid parameter DEVICE_ERROR_PERMISSION_DENIED Permission denied DEVICE_ERROR_OPERATION_FAILED Operation failed DEVICE_ERROR_NOT_SUPPORTED Not supported device
- Postcondition:
- The device will be in DISPLAY_STATE_NORMAL state.