From: Yunhee Seo Date: Mon, 30 Sep 2024 10:50:35 +0000 (+0900) Subject: power: Enhance API description X-Git-Tag: accepted/tizen/unified/20241006.053304~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a9e901b0d7e13982d2667fbc9795eb8e384b5924;p=platform%2Fcore%2Fapi%2Fdevice.git power: Enhance API description To improve readability and facilitate comprehension, more detailed API descriptions are added. Change-Id: Icd023fb6fff590a9c9efec16c2e61e7c15d28fe6 Signed-off-by: Yunhee Seo --- diff --git a/include/power-internal.h b/include/power-internal.h index 522ca5f..52f46e8 100644 --- a/include/power-internal.h +++ b/include/power-internal.h @@ -29,16 +29,24 @@ extern "C" { /** * @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 + * ... + * int ret = device_power_poweroff(); + * if (ret != DEVICE_ERROR_NONE) { + * printf("Device powered off failed.\n"); + * } + * ... + * @endcode */ int device_power_poweroff(void); @@ -124,13 +132,41 @@ typedef enum { * @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 + * ... + * 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); @@ -139,248 +175,708 @@ 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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 + * #include + * ... + * 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); diff --git a/include/power.h b/include/power.h index 404bb5c..8576ab8 100644 --- a/include/power.h +++ b/include/power.h @@ -57,39 +57,63 @@ typedef enum { /** - * @brief Locks the given lock state for a specified time. + * @brief Locks the given specific power lock type for a specified time. * @details After the given @a timeout_ms (in milliseconds), unlock the given lock state automatically. * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/display - * @remarks If the process dies, then every lock will be removed. + * @remarks If the process dies after success request lock, then every lock will be removed. + * The display state feature(http://tizen.org/feature/display.state) also should be checked. * @param[in] type The power type to request lock * @param[in] timeout_ms The positive number in milliseconds or @c 0 for permanent lock \n * So you must release the permanent lock of power state with #device_power_release_lock() if @a timeout_ms is zero - * @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_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed + * @code + * #include + * ... + * int ret = 0; + * ret = device_power_request_lock(POWER_LOCK_DISPLAY, 5000); + * if (ret != DEVICE_ERROR_NONE) { + * .... + * } + * ... + * @endcode * @see device_power_release_lock() + * @see power_lock_e */ int device_power_request_lock(power_lock_e type, int timeout_ms); /** - * @brief Releases the given lock state which was locked before. + * @brief Releases the given specific power lock type which was locked before. + * @details Releases the lock of specific power lock type that was previously acquired using device_power_request_lock(). * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/display + * @remarks The display state feature(http://tizen.org/feature/display.state) also should be checked. * @param[in] type The power type to release lock - * @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_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed + * @code + * #include + * ... + * 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); + * ... + * @endcode * @see device_power_request_lock() + * @see power_lock_e */ int device_power_release_lock(power_lock_e type); @@ -118,19 +142,29 @@ int device_power_wakeup(bool dim) TIZEN_DEPRECATED_API; /** * @platform - * @brief Reboots the device. + * @brief Sends a request to the deviced Rebooting the current device. * @details Will not return if the reboot is successful. \n * It operates asynchronously. * @since_tizen 2.3.1 * @privlevel platform * @privilege %http://tizen.org/privilege/reboot + * @remarks If the power reboot @a reason is NULL, then it will be set as @c "Unknown". * @param[in] reason Pass to the platform and kernel to request special reboot reason, or null - * @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_INVALID_PARAMETER Invalid parameter * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed + * @code + * #include + * ... + * int ret = device_power_reboot("Reason_for_reboot"); + * if (ret != DEVICE_ERROR_NONE) { + * ... + * } + * ... + * @endcode + * @see device_power_check_reboot_allowed() */ int device_power_reboot(const char *reason);