X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=include%2Fpower-internal.h;h=ed85e413fe0d147b1b29f09d7d027c27eaefc38d;hb=37e6821b51d294f2ee2e38fa0af4e4a448605afa;hp=817c1d467cf68c589ce3a2ef280c3e7a97037434;hpb=db2fd6133ebba7c3c2c59fabc2ed099579263355;p=platform%2Fcore%2Fapi%2Fdevice.git

diff --git a/include/power-internal.h b/include/power-internal.h
index 817c1d4..ed85e41 100644
--- a/include/power-internal.h
+++ b/include/power-internal.h
@@ -77,63 +77,94 @@ struct device_change_state_info {
 };
 
 /**
- * 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