};
/**
- * Callback function that delivers information about a state transition.
+ * @brief Called when a device power state is changed
+ * @details If both change_state_wait_callback and change_state_callback have registered to the same power state, \n
+ * then the change_state_wait_callback will be invoked first and the change_state_callback will follow.
+ * @param[out] info Information about state change
+ * @param[out] user_data User data passed from the callback registration
*/
typedef void (*change_state_wait_callback) (const struct device_change_state_info *info, void *user_data);
/**
- * Add callback for states to be transitioned. The action caused by the transition,
- * e.g., wake unlock for sleep or shutdown for reboot, would be defered until calling
- * device_power_change_state_wait_done().
- *
- * uint64_t state_bits: bitwise-ORing of interesting state.
- * change_state_wait_callback cb: For every state transition to the state_bit, the cb will be invoked.
- * void *user_data: user data for the callback.
+ * @brief Add a callback to observe 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 POWER_STATE_POWEROFF or \n
+ * wake unlock on changing state to POWER_STATE_SLEEP, will be deferred to give a chance \n
+ * for the API caller to prepare for the action.
+ * @sinze_tizen 6.5
+ * @param[in] state_bits Bitwise ORed power state
+ * @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
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
*/
int device_power_add_change_state_wait_callback(uint64_t state_bits, change_state_wait_callback cb, void *user_data);
/**
- * Notify the deviced that it is ready to transition state.
- *
- * uint64_t id: id of device_change_state_info that has received through callback.
+ * @brief Notify the deviced that it is ready for the actual action.
+ * @details Notify the deviced that it is ok to take an actual action of change state. \n
+ * This API only works on the id received from change_state_wait_callback.
+ * @since_tizen 6.5
+ * @param[in] id Id of a state change
+ * @return 0 on success,
+ * otherwise a negative error value
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
*/
int device_power_change_state_wait_done(uint64_t id);
/**
- * Remove callback of state transition.
+ * @brief Remove callback that has registered to power state.
+ * @since_tizen 6.5
+ * @param[in] state_bits Bitwise ORed power state
*/
void device_power_remove_change_state_wait_callback(uint64_t state_bits);
/**
- * Async callback of device_power_change_state()
- *
- * uint64_t state: which state it has transitioned.
- * int retval: result of the method call.
- * void *user_data: user data for the callback.
+ * @brief Async callback of device_power_change_state().
+ * @details If both change_state_wait_callback and change_state_callback have registered to the same power state, \n
+ * then the change_state_wait_callback will be invoked first and the change_state_callback will follow.
+ * @since_tizen 6.5
+ * @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
*/
typedef void (*change_state_callback) (uint64_t state, int retval, void *user_data);
/**
- * Send a request to the deviced for changing power state. It doesn't ensure the whole execution
- * of a callback subroutine - think of a request for sleep/poweroff/reboot state. To ensure
- * the whole execution of a callback, use device_power_add_change_state_wait_callback() additionally.
- * If both change_state_wait_callback and change_state_callback has registered to a state,
- * it is unpredictable which callback will be invoked first.
- *
- * uint64_t state: which state to transition to
- * int timeout_sec: maximum timeout of async method call. if it expires, then the second parameter of
- * a callback function, int retval, gives -ETIMEDOUT error. If it is 0 or negative, it is set to
- * the default, 10 seconds.
- * change_state_callback cb: async callback function, nullable
- * void *user_data: user data for the callback.
+ * @brief Send request for changing power state asynchronously.
+ * @since_tizen 6.5
+ * @param[in] state Target 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
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
*/
int device_power_change_state(uint64_t state, int timeout_sec, change_state_callback cb, void *user_data);
/**
- * Return 0 if cloning partition is in progress.
+ * @brief Check if reboot is possible on the current device state
+ * @since_tizen 6.5
+ * @return 1 if a device is able to reboot,
+ * otherwise return 0
*/
int device_power_check_reboot_allowed(void);
+/**
+ * @brief Get internal power state of the deviced
+ * @since_tizen 6.5
+ * @param[out] state Internal power state of the deviced
+ * @return 0 on success,
+ * otherwise a negative error value
+ * @retval #DEVICE_ERROR_NONE Successful
+ * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
+ */
int device_power_get_state(uint64_t *state);
#ifdef __cplusplus
projects / platform / core / api / device.git / blobdiff