/**
* @platform
- * @brief Power off the device.
- * @details It operates synchronously.
+ * @brief Requests the current device's power state change to be changed to powered off.
+ * @details It operates synchronously and powers off the current device.
* @since_tizen 6.5
* @privlevel platform
* @privilege %http://tizen.org/privilege/reboot
- * @return @c 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * int ret = device_power_poweroff();
+ * if (ret != DEVICE_ERROR_NONE) {
+ * printf("Device powered off failed.\n");
+ * }
+ * ...
+ * @endcode
*/
int device_power_poweroff(void);
* @details Notify the deviced that it is ok to take an actual action of change state. \n
* This function only works on the id received from device_power_state_wait_callback() and device_power_transient_state_wait_callback().
* @since_tizen 6.5
+ * @remarks The @a wait_callback_id must have been previously registered using device_power_state_wait_callback() or device_power_transient_state_wait_callback().
* @param[in] wait_callback_id Wait callback id to confirm
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_state_wait_callback()
- * @see device_power_transient_state_wait_callback()
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e prev_state,
+ * device_power_state_e next_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * if (next_state == DEVICE_POWER_STATE_SLEEP) {
+ * device_power_confirm_wait_callback(wait_callback_id);
+ * }
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_state_wait_callback(DEVICE_POWER_STATE_SLEEP,
+ * power_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_state_wait_callback()
+ * @see device_power_transient_state_wait_callback()
+ * @see device_power_cancel_wait_callback()
*/
int device_power_confirm_wait_callback(uint64_t wait_callback_id);
* @details Notify the deviced that the current transition should be rewinded. \n
* This function only works on the id received from device_power_state_wait_callback() and device_power_transient_state_wait_callback().
* @since_tizen 7.0
+ * @remarks The @a wait_callback_id must have been previously registered using device_power_state_wait_callback() or device_power_transient_state_wait_callback().
* @param[in] wait_callback_id Wait callback id to cancel
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_state_wait_callback()
- * @see device_power_transient_state_wait_callback()
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e prev_state,
+ * device_power_state_e next_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * if (transition_reason == DEVICE_POWER_TRANSITION_REASON_CUSTOM && next_state == DEVICE_POWER_STATE_SLEEP) {
+ * device_power_cancel_wait_callback(wait_callback_id);
+ * }
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_state_wait_callback(DEVICE_POWER_STATE_SLEEP,
+ * power_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_state_wait_callback()
+ * @see device_power_transient_state_wait_callback()
+ * @see device_device_power_confirm_wait_callback()
*/
int device_power_cancel_wait_callback(uint64_t wait_callback_id);
/**
- * @brief Called when a device power state is changed.
+ * @brief Callback function type for device power state change events.
* @details If both device_power_state_wait_callback() and device_power_change_state_callback() have registered to the same power state, \n
* then the device_power_state_wait_callback() will be invoked first and the device_power_change_state_callback() will follow.
* @since_tizen 6.5
+ * @remarks The registered callback will be called when a power state transition occurs.
* @param[out] prev_state Power state where transition has started
* @param[out] next_state Power state to be changed by transition
* @param[out] wait_callback_id Unique id for each callback invocation
* @param[out] transition_reason Reason for what triggered the transition
* @param[out] user_data User data passed from the callback registration
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e prev_state,
+ * device_power_state_e next_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_state_wait_callback(DEVICE_POWER_STATE_NORMAL,
+ * power_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_state_wait_callback()
+ * @see device_power_state_e
+ * @see device_power_transition_reason_e
*/
typedef void (*device_power_state_wait_callback) (device_power_state_e prev_state, device_power_state_e next_state,
uint64_t wait_callback_id, device_power_transition_reason_e transition_reason, void *user_data);
/**
- * @brief Add a callback to observe power state change.
+ * @brief Adds a callback to observe the specified power state change.
* @details Register a callback for specific power state. \n
* The callback will be invoked when the deviced changes state to the designated power state. \n
* An actual action, such as triggering poweroff on changing state to #DEVICE_POWER_STATE_POWEROFF or \n
* wake unlock on changing state to #DEVICE_POWER_STATE_SLEEP, will be deferred to give a chance \n
* for the API caller to prepare for the action.
* @since_tizen 6.5
+ * @remarks Added callback based on @a state_bits can be removed by device_power_remove_state_wait_callback(). \n
* @param[in] state_bits Bitwise ORed #device_power_state_e
* @param[in] cb Callback function
* @param[in] user_data Data to be passed to the callback function
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_state_wait_callback()
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e prev_state,
+ * device_power_state_e next_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_state_wait_callback(DEVICE_POWER_STATE_NORMAL,
+ * power_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_state_wait_callback()
+ * @see device_power_remove_state_wait_callback()
+ * @see device_power_state_e
*/
int device_power_add_state_wait_callback(device_power_state_e state_bits, device_power_state_wait_callback cb, void *user_data);
/**
- * @brief Remove callback that has registered to power state.
+ * @brief Removes the callback that has registered for a specific power state.
+ * @details Unregisters a callback function that was previously registered using device_power_add_state_wait_callback().
* @since_tizen 6.5
+ * @remarks Removes the callback function only for the specified state bits.\n
+ * If the callback was registered for multiple state bits, only the specified state bits will be removed.
* @param[in] state_bits Bitwise ORed #device_power_state_e
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e prev_state,
+ * device_power_state_e next_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_state_wait_callback(DEVICE_POWER_STATE_NORMAL,
+ * power_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * ret = device_power_remove_state_wait_callback(DEVICE_POWER_STATE_NORMAL);
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_state_wait_callback()
+ * @see device_power_state_e
*/
void device_power_remove_state_wait_callback(device_power_state_e state_bits);
/**
- * @brief Called when a device power state is changed.
+ * @brief Callback function type for device power transient state change events.
+ * @details It can be registered by device_power_add_transient_state_wait_callback(). \n
+ * Also it can be removed by device_power_remove_transient_state_wait_callback().
* @since_tizen 6.5
+ * @remarks The registered callback will be invoked when a power state transient transition occurs.
* @param[out] transient_state Transient state to be changed by the transition
* @param[out] wait_callback_id Unique id for each callback invocation
* @param[out] transition_reason Reason for what triggered the transition
* @param[out] user_data User data passed from the callback registration
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_transient_state_change_cb(device_power_transient_state_e transient_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_transient_state_wait_callback(DEVICE_POWER_TRANSIENT_STATE_SUSPENDING,
+ * power_transient_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_transient_state_wait_callback()
+ * @see device_power_transient_state_e
+ * @see device_power_transition_reason_e
*/
typedef void (*device_power_transient_state_wait_callback) (device_power_transient_state_e transient_state,
uint64_t wait_callback_id, device_power_transition_reason_e transition_reason, void *user_data);
/**
- * @brief Add a callback to observe transient power state.
+ * @brief Adds a callback to observe the specified transient power state.
* @details Register a callback for specific transient power state. \n
* The callback will be invoked in the middle of transition process. \n
* Similar to the device_power_add_change_state_wait_callback(), it withholds transition \n
* until it is confirmed to be ready to go. \n
* @since_tizen 7.0
+ * @remarks Added callback based on @a transient_bits can be removed by device_power_remove_transient_state_wait_callback(). \n
* @param[in] transient_bits Bitwise ORed #device_power_transient_state_e
* @param[in] cb Callback function
* @param[in] user_data Data to be passed to the callback function
- * @return 0 on success,
+ * @return @c 0 on success,
* otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_transient_state_wait_callback()
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_transient_state_change_cb(device_power_transient_state_e transient_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_transient_state_wait_callback(DEVICE_POWER_TRANSIENT_STATE_SUSPENDING,
+ * power_transient_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_transient_state_wait_callback()
+ * @see device_power_transient_remove_state_wait_callback()
+ * @see device_power_transient_state_e
*/
int device_power_add_transient_state_wait_callback(device_power_transient_state_e transient_bits,
device_power_transient_state_wait_callback cb, void *user_data);
/**
- * @brief Remove callback that has registered to transient power state.
+ * @brief Removes the callback that has registered for a specific transient power state.
+ * @details Unregisters a callback function that was previously registered using device_power_add_state_wait_callback().
* @since_tizen 7.0
+ * @remarks Removes the callback function only for the specified transient state bits.\n
+ * If the callback was registered for multiple state bits, only the specified state bits will be removed.
* @param[in] transient_bits Bitwise ORed #device_power_transient_state_e
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_transient_state_change_cb(device_power_transient_state_e transient_state,
+ * uint64_t wait_callback_id,
+ * device_power_transition_reason_e transition_reason,
+ * void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_add_transient_state_wait_callback(DEVICE_POWER_TRANSIENT_STATE_SUSPENDING,
+ * power_transient_state_change_cb,
+ * NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * ret = device_power_remove_transient_state_wait_callback(DEVICE_POWER_TRANSIENT_STATE_SUSPENDING);
+ * }
+ * ...
+ * @endcode
+ * @see device_power_transient_state_wait_callback()
+ * @see device_power_add_transient_state_wait_callback()
+ * @see device_power_transient_state_e
*/
void device_power_remove_transient_state_wait_callback(device_power_transient_state_e transient_bits);
/**
- * @brief Async callback of device_power_change_state().
+ * @brief Asynchronous callback of device_power_change_state().
* @details If both device_power_state_wait_callback() and device_power_change_state_callback() have registered to the same power state, \n
* then the device_power_state_wait_callback() will be invoked first and the device_power_change_state_callback() will follow.
* @since_tizen 6.5
+ * @remarks The registered callback will be called when a power state transition occurs.
* @param[out] state State to be changed
* @param[out] retval Return of change state
* @param[out] user_data The user data passed from the change state function
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e state, int retval, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_change_state(DEVICE_POWER_STATE_SLEEP, 3, power_state_change_cb, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_change_state()
+ * @see device_power_state_e
*/
typedef void (*device_power_change_state_callback) (device_power_state_e state, int retval, void *user_data);
/**
- * @brief Send request for changing power state asynchronously.
+ * @brief Sends the request to change the power state asynchronously.
* @since_tizen 6.5
- * @param[in] state Target state
+ * @param[in] state Target power state
* @param[in] timeout_sec Timeout for the async reply in second, maximum of 10 seconds
* @param[in] cb Async callback of the request
* @param[in] user_data Data to be passed to the callback function
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_state_change_cb(device_power_state_e state, int retval, void *user_data)
+ * {
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = 0;
+ * ret = device_power_change_state(DEVICE_POWER_STATE_SLEEP, 3, power_state_change_cb, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * }
+ * ...
+ * @endcode
+ * @see device_power_change_state_callback()
+ * @see device_power_state_e
*/
int device_power_change_state(device_power_state_e state, int timeout_sec, device_power_change_state_callback cb, void *user_data);
/**
- * @brief Check if reboot is possible on the current device state.
+ * @brief Checks if a power reboot is possible on the current device state.
+ * @details Checks if a reboot is allowed on the current device state.\n
+ * It returns @c 1 if a reboot is allowed, otherwise it returns @c 0.
* @since_tizen 6.5
- * @return 1 if a device is able to reboot,
- * otherwise return 0
+ * @remarks Decides whether a reboot is allowed from the HAL board module.
+ * @return @c 1 if a device is able to reboot, otherwise return @c 0
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * int is_reboot_allowed = device_power_check_reboot_allowed();
+ * if (is_reboot_allowed == 1) {
+ * printf("Reboot is allowed.\n");
+ * } else {
+ * printf("Reboot is not allowed.\n");
+ * }
+ * ...
+ * @endcode
*/
int device_power_check_reboot_allowed(void);
#ifndef EXCLUDE_INTERNAL_CAPI_SYSTEM_DEVICE
/**
- * @brief Get wakeup reason.
+ * @brief Gets the reason for the last device wakeup based on the scenario.
+ * @details Retrieves the reason for the last device wakeup.\n
+ * The reason is returned as a @a device_power_transition_reason_e reason pointer.
* @since_tizen 7.0
+ * @remarks Ensure that the provided @a reason pointer is valid and has enough memory allocated.
* @param[out] reason the reason why the device wakeup
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * device_power_transition_reason_e reason;
+ * int ret = device_power_get_wakeup_reason(&reason);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * printf("Wakeup reason: %d\n", reason);
+ * ...
+ * @endcode
+ * @see device_power_transition_reason_e
*/
int device_power_get_wakeup_reason(device_power_transition_reason_e *reason);
#endif
/**
- * @brief Called when the registered power lock is changed.
+ * @brief Callback function type for device power lock state change events.
+ * @details It can be registered by device_power_add_lock_state_change_callback(). \n
* @since_tizen 7.0
+ * @remarks The callback function will be called when the state of a power lock changes.
* @param[out] power_lock_type Type of power lock
* @param[out] power_lock_state Status of power lock
* @param[out] user_data User data passed from the callback registration
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_changed_cb(power_lock_e power_lock_type, device_power_lock_state_e power_lock_state, void *user_data)
+ * {
+ * printf("Power lock state changed: type=%d, state=%d\n", power_lock_type, power_lock_state);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_state_change_callback(POWER_LOCK_NORMAL, power_lock_state_changed, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_lock_state_change_callback()
+ * @see power_lock_e
+ * @see device_power_lock_state_e
*/
typedef void (*device_power_lock_state_change_callback) (power_lock_e power_lock_type,
device_power_lock_state_e power_lock_state, void *user_data);
/**
- * @brief Called when the registered power lock is changed.
+ * @brief Callback function type for the registered device power lock count is changed.
+ * @details It can be registered by device_power_add_lock_count_change_callback(). \n
* @since_tizen 7.0
+ * @remarks The callback function will be called when the state of a power lock count is changed.
* @param[out] power_lock_type Type of power lock
* @param[out] power_lock_count Number of power lock
* @param[out] user_data User data passed from the callback registration
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_count_changed_cb(power_lock_e power_lock_type, int power_lock_count, void *user_data)
+ * {
+ * printf("Power lock state count changed: type=%d, count=%d\n", power_lock_type, power_lock_count);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_count_change_callback(POWER_LOCK_NORMAL, power_lock_state_count_changed_cb, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_lock_count_change_callback()
+ * @see power_lock_e
*/
typedef void (*device_power_lock_count_change_callback) (power_lock_e power_lock_type,
int power_lock_count, void *user_data);
/**
- * @brief Gets the status of power lock.
+ * @brief Gets the status of power lock is locked or not based on specific power lock type.
+ * @details Retrieves the status of a power lock.\n
+ * The status is returned as a @a device_power_lock_state_e power_lock_state pointer.
* @since_tizen 7.0
+ * @remarks Ensure that the provided @a power_lock_e power_lock_type pointer is valid and has enough memory allocated.
* @param[in] power_lock_type Type of power lock
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[out] power_lock_state Status of power lock to be get
- * @return 0 on success,
- * otherwise a negative error value
+ * DEVICE_POWER_LOCK_STATE_UNLOCK \n
+ * DEVICE_POWER_LOCK_STATE_LOCK
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * device_power_lock_state_e power_lock_state;
+ * int ret = device_power_get_lock_state(POWER_LOCK_DISPLAY, &power_lock_state);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see power_lock_e
+ * @see device_power_lock_state_e
*/
int device_power_get_lock_state(power_lock_e power_lock_type,
device_power_lock_state_e *power_lock_state);
/**
- * @brief Gets the status of power lock.
+ * @brief Gets the number of locks acquired in the given power lock state.
+ * @details Retrieves the status of a power lock.\n
+ * The status is returned as a int @a power_lock_count pointer.
* @since_tizen 7.0
+ * @remarks Ensure that the provided @a power_lock_count pointer is valid and has enough memory allocated.
* @param[in] power_lock_type Type of power lock
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[out] power_lock_count Number of power lock to be get
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * int power_lock_count = 0;
+ * int ret = device_power_get_lock_count(POWER_LOCK_DISPLAY, &power_lock_count);
+ * if (ret == DEVICE_ERROR_NONE) {
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see power_lock_e
*/
int device_power_get_lock_count(power_lock_e power_lock_type,
int *power_lock_count);
/**
- * @brief Add a callback to observe status of registered specific power lock.
- * @details The callback will be invoked when the power lock is changed
+ * @brief Adds a callback to observe status of registered specific power lock.
+ * @details The callback will be invoked when the power lock type state is changed.
* @since_tizen 7.0
+ * @remarks Added callback based on @a power_lock_type can be removed by device_power_remove_lock_state_change_callback(). \n
* @param[in] power_lock_type Power lock type to be observed
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[in] power_lock_state_change_callback Callback function
* @param[in] user_data Data to be passed to the callback function
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_request_lock()
- * @see device_power_release_lock()
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_changed_cb(power_lock_e power_lock_type, device_power_lock_state_e power_lock_state, void *user_data)
+ * {
+ * printf("Power lock state changed: type=%d, state=%d\n", power_lock_type, power_lock_state);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_state_change_callback(POWER_LOCK_NORMAL, power_lock_state_changed, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see device_power_request_lock()
+ * @see device_power_release_lock()
+ * @see device_power_lock_state_change_callback()
+ * @see power_lock_e
*/
int device_power_add_lock_state_change_callback(power_lock_e power_lock_type,
device_power_lock_state_change_callback power_lock_state_change_callback,
void *user_data);
/**
- * @brief Remove callback that has registered to power lock type.
+ * @brief Removes callback that has registered from device_power_add_lock_state_change_callback().
+ * @details Unregisters a callback function that was previously registered using device_power_add_lock_state_change_callback().
* @since_tizen 7.0
+ * @remarks Removes the callback function only for the specified power lock type.
* @param[in] power_lock_type Type of power lock
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[in] power_lock_state_change_callback Callback function to be removed
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_changed_cb(power_lock_e power_lock_type, device_power_lock_state_e power_lock_state, void *user_data)
+ * {
+ * printf("Power lock state changed: type=%d, state=%d\n", power_lock_type, power_lock_state);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_state_change_callback(POWER_LOCK_NORMAL, power_lock_state_changed, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * ret = device_power_remove_lock_state_change_callback(POWER_LOCK_NORMAL, power_lock_state_changed);
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_lock_state_change_callback()
+ * @see device_power_lock_state_change_callback()
+ * @see power_lock_e
*/
int device_power_remove_lock_state_change_callback(power_lock_e power_lock_type,
device_power_lock_state_change_callback power_lock_state_change_callback);
/**
- * @brief Add a callback to observe status of registered specific power lock.
- * @details The callback will be invoked when the power lock is changed
+ * @brief Adds a callback to observe number of lock status of registered specific power lock.
+ * @details The callback will be invoked when the number of lock is changed based on speicific power lock type.
* @since_tizen 7.0
+ * @remarks The callback function will be called when the state of a power lock count is changed.
* @param[in] power_lock_type Power lock type to be observed
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[in] power_lock_count_change_callback Callback function
* @param[in] user_data Data to be passed to the callback function
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
- * @see device_power_request_lock()
- * @see device_power_release_lock()
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_count_changed_cb(power_lock_e power_lock_type, int power_lock_count, void *user_data)
+ * {
+ * printf("Power lock state count changed: type=%d, count=%d\n", power_lock_type, power_lock_count);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_count_change_callback(POWER_LOCK_NORMAL, power_lock_state_count_changed_cb, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * }
+ * ...
+ * @endcode
+ * @see device_power_request_lock()
+ * @see device_power_release_lock()
+ * @see device_power_lock_count_change_callback()
+ * @see power_lock_e
*/
int device_power_add_lock_count_change_callback(power_lock_e power_lock_type,
device_power_lock_count_change_callback power_lock_count_change_callback,
void *user_data);
/**
- * @brief Remove callback that has registered to power lock type.
+ * @brief Removes callback that has registered from device_power_add_lock_count_change_callback().
+ * @details Unregisters a callback function that was previously registered using device_power_add_lock_count_change_callback().
* @since_tizen 7.0
+ * @remarks Removes the callback function only for the specified power lock type.
* @param[in] power_lock_type Type of power lock
+ * POWER_LOCK_CPU \n
+ * POWER_LOCK_DISPLAY \n
+ * POWER_LOCK_DISPLAY_DIM
* @param[in] power_lock_count_change_callback Callback function to be removed
- * @return 0 on success,
- * otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #DEVICE_ERROR_NONE Successful
* @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ * #include <stdio.h>
+ * #include <device/power-internal.h>
+ * ...
+ * static void power_lock_state_count_changed_cb(power_lock_e power_lock_type, int power_lock_count, void *user_data)
+ * {
+ * printf("Power lock state count changed: type=%d, count=%d\n", power_lock_type, power_lock_count);
+ * ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ * int ret = device_power_add_lock_count_change_callback(POWER_LOCK_NORMAL, power_lock_state_count_changed_cb, NULL);
+ * if (ret != DEVICE_ERROR_NONE) {
+ * return -1;
+ * }
+ * ...
+ * ret = device_power_remove_lock_count_change_callback(POWER_LOCK_NORMAL, power_lock_state_count_changed_cb);
+ * }
+ * ...
+ * @endcode
+ * @see device_power_add_lock_count_change_callback()
+ * @see device_power_lock_count_change_callback()
+ * @see power_lock_e
*/
int device_power_remove_lock_count_change_callback(power_lock_e power_lock_type,
device_power_lock_count_change_callback power_lock_count_change_callback);
projects / platform / core / api / device.git / commitdiff