[sample] update headers

2 files changed, 275 insertions, 28 deletions

diff --git a/inc/iot-device-manage-type.h b/inc/iot-device-manage-type.h
index e012547..d6951ff 100644
--- a/inc/iot-device-manage-type.h
+++ b/inc/iot-device-manage-type.h
@@ -21,57 +21,100 @@
 extern "C" {
 #endif
 
+/**
+* @brief Enumeration for command type
+* @since_tizen 5.0
+*/
 typedef enum {
-	IDM_CMD_TYPE_UNKNOWN = 0,
-	IDM_CMD_TYPE_POWER = 1,
-	IDM_CMD_TYPE_DIAGNOSIS = 4,
-	IDM_CMD_TYPE_INFO = 5,
+	IDM_CMD_TYPE_UNKNOWN = 0,    /**< Unknown command */
+	IDM_CMD_TYPE_POWER = 1,      /**< Command regarding power */
+	IDM_CMD_TYPE_DIAGNOSIS = 4,  /**< Command regarding diagnosis */
+	IDM_CMD_TYPE_INFO = 5,       /**< Command regarding information */
 } idm_cmd_type_e;
 
+/**
+* @brief Enumeration for command status
+* @since_tizen 5.0
+*/
 typedef enum {
-	IDM_CMD_CREATED = 0,
-	IDM_CMD_INITIALIZED,
-	IDM_CMD_RUNNING,
-	IDM_CMD_DONE,
+	IDM_CMD_CREATED = 0,  /**< Command is created */
+	IDM_CMD_INITIALIZED,  /**< Command is initialized */
+	IDM_CMD_RUNNING,      /**< Command is running */
+	IDM_CMD_DONE,         /**< Command is done */
 } idm_cmd_status_e;
 
+/**
+* @brief Enumeration for command regarding power
+* @since_tizen 5.0
+*/
 typedef enum { /* TBD */
-	IDM_CMD_POWER_REBOOT = 100,
-	IDM_CMD_POWER_LCDOFF,			/* TBD */
-	IDM_CMD_POWER_HIBERNATE,		/* TBD : Control electric power on the peak season */
-	IDM_CMD_POWER_HALT,				/* TBD : Control electric power on the peak season */
+	IDM_CMD_POWER_REBOOT = 100,  /**< Command for power rebooting */
+	IDM_CMD_POWER_LCDOFF,        /**< Command for turning LCD off */               /* TBD */
+	IDM_CMD_POWER_HIBERNATE,     /**< Command for hibernating on peak season */    /* TBD : Control electric power on the peak season */
+	IDM_CMD_POWER_HALT,          /**< Command for halting on peak season */        /* TBD : Control electric power on the peak season */
 } idm_cmd_power_e;
 
+/**
+* @brief Enumeration for command regarding diagnosis
+* @since_tizen 5.0
+*/
 typedef enum { /* TBD */
-	IDM_CMD_DIAGNOSIS_GET_LOG = 400,
-	IDM_CMD_DIAGNOSIS_GET_ERR_CODE,	/* TBD : Collect error codes from sensors & motors */
+	IDM_CMD_DIAGNOSIS_GET_LOG_ARCHIVE = 400,  /**< Command for getting logs for diagnosis */
+	IDM_CMD_DIAGNOSIS_GET_ERR_CODE,   /**< Command for getting error codes for diagnosis */    /* TBD : Collect error codes from sensors & motors */
 } idm_cmd_diagnosis_e;
 
+/**
+* @brief Enumeration for command regarding information
+* @since_tizen 5.0
+*/
 typedef enum { /* TBD */
-	IDM_CMD_INFO_GET_SYSINFO = 500,
-	IDM_CMD_INFO_GET_TASKINFO,		/* TBD : Add lots of things to a gateway so it needs to monitor resources. */
+	IDM_CMD_INFO_GET_SYSINFO = 500,  /**< Command for getting system information */
+	IDM_CMD_INFO_GET_TASKINFO,       /**< Command for getting task information */    /* TBD : Add lots of things to a gateway so it needs to monitor resources. */
 } idm_cmd_info_e;
 
+/**
+* @brief Enumeration for command result
+* @since_tizen 5.0
+*/
 typedef enum {
-	IDM_RESULT_RUNNING,
-	IDM_RESULT_SUCCESS,
-	IDM_RESULT_FAILED,
+	IDM_RESULT_RUNNING,    /**< Command is still running */
+	IDM_RESULT_SUCCESS,    /**< Command succeded */
+	IDM_RESULT_FAILED,     /**< Command failed */
 } idm_result_e;
 
+/**
+* @brief Enumeration for error reason
+* @since_tizen 5.0
+*/
 typedef enum {
-	IDM_REASON_NONE,
-	IDM_REASON_UNKNOWN,
-	IDM_REASON_INVALID_PARAMETER,
-	IDM_REASON_OUT_OF_MEMORY,
-	IDM_REASON_IO_ERROR,
-	IDM_REASON_PERMISSION_DENIED,
-	IDM_REASON_INVALID_OPERATION,
-	IDM_REASON_STOPPED,
-	IDM_REASON_NOT_SUPPORTED,
+	IDM_REASON_NONE,                /**< No error */
+	IDM_REASON_UNKNOWN,             /**< Unknown error */
+	IDM_REASON_INVALID_PARAMETER,   /**< Invalid parameter */
+	IDM_REASON_OUT_OF_MEMORY,       /**< Out of memory */
+	IDM_REASON_IO_ERROR,            /**< Input/output error */
+	IDM_REASON_PERMISSION_DENIED,   /**< Permission denied */
+	IDM_REASON_INVALID_OPERATION,   /**< Invalid operation */
+	IDM_REASON_STOPPED,             /**< Stopped */
+	IDM_REASON_NOT_SUPPORTED,       /**< Not supported */
 } idm_reason_e;
 
+/**
+* @brief Structure for command
+* @since_tizen 5.0
+*/
 typedef struct __idm_command_h *idm_command_h;
 
+/**
+* @brief Type definition of result callback function
+* @since_tizen 5.0
+* @param command Command handle
+* @param result Enum value for result
+* @param reason Enum value for reason
+* @param detail Detail about result
+* @param data User data
+* @pre The callback must be registered using idm_command_run()
+* @see idm_command_run()
+*/
 typedef void (*idm_result_cb) (idm_command_h command, idm_result_e result, idm_reason_e reason, const char *detail, void *data); /* TBD */
 
 #ifdef __cplusplus
diff --git a/inc/iot-device-manage.h b/inc/iot-device-manage.h
index b733a9e..0e11b4b 100644
--- a/inc/iot-device-manage.h
+++ b/inc/iot-device-manage.h
@@ -23,17 +23,221 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Creates a idm_command handle.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @post The idm_command must be released using idm_command_free().
+ * @param[out] command The idm_command handle to be newly created on success
+ * @return 0 on success, otherwise a negative error value
+ */
 int idm_command_new(idm_command_h *command);
+
+/**
+ * @brief Destroys the idm_command handle and releases all its resources.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @return 0 on success, otherwise a negative error value
+ */
 int idm_command_free(idm_command_h command);
+
+/**
+ * @brief Runs the pre-set command.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ *          This works asynchronously.
+ * @pre To use this API, the command must be perset by using idm_command_set_power_cmd(), idm_command_set_diagnosis_cmd(), idm_command_set_info_cmd().
+ * @param[in] command The idm_command handle
+ * @param[in] result_cb The callback function to get result
+ * @param[in] user_data The user data to be passed to the callback function
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_command_set_power_cmd()
+ * @see idm_command_set_diagnosis_cmd()
+ * @see idm_command_set_info_cmd()
+ * @see idm_command_stop()
+ */
 int idm_command_run(idm_command_h command, idm_result_cb result_cb, void *user_data);
+
+/**
+ * @brief Stops the command.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ *          if the command is not running, This returns -1(fail).
+ * @param[in] command The idm_command handle
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_command_run()
+ */
 int idm_command_stop(idm_command_h command);
+
+/**
+ * @brief Gets state of the command.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[out] state The current state of the command
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_cmd_status_e
+ */
 int idm_command_get_state(idm_command_h command, idm_cmd_status_e *state);
+
+/**
+ * @brief Sets ID of the command.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[in] id The ID of the command
+ * @return 0 on success, otherwise a negative error value
+ */
 int idm_command_set_id(idm_command_h command, unsigned long id);
+
+/**
+ * @brief Gets ID of the command.
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[out] id The ID of the command
+ * @return 0 on success, otherwise a negative error value
+ */
 int idm_command_get_id(idm_command_h command, unsigned long *id);
 
+/**
+ * @brief Gets type of the command
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[out] type The type of the command
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_cmd_type_e
+ */
 int idm_command_get_type(idm_command_h command, idm_cmd_type_e *type);
+
+/**
+ * @brief Sets the command regarding power
+ * @privilege http://tizen.org/privilege/reboot
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[in] cmd The command regarding power
+ * @param[in] reason The reason for setting @cmd
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_cmd_power_e
+ *
+ * @par Example
+ * @code
+ * #include <libidm.h>
+ *
+ * static void __reboot_result_callback(idm_command_h command, idm_result_e result, idm_reason_e reason, const char *detail, void *data)
+ * {
+ *  	app_data *ad = data;
+ * 		_D("result : %d, reason : %d, detail : %s", result, reason, detail ? detail : "None");
+ *
+ *		if (result != IDM_RESULT_RUNNING) {
+ *			idm_command_free(command);
+ *		}
+ * }
+ *
+ * static void __reboot(void)
+ * {
+ *		idm_command_h command = NULL;
+ *		int ret = -1;
+ *
+ *		ret = idm_command_new(&command);
+ *		if (ret != 0) {
+ *			_E("failed to idm_command_new");
+ *			return;
+ *		}
+ *
+ *		ret = idm_command_set_power_cmd(command, IDM_CMD_POWER_REBOOT, NULL);
+ *		if (ret != 0) {
+ *			_E("failed to idm_command_set_power_cmd");
+ *			idm_command_stop(ad->command);
+ *			idm_command_free(command);
+ *			return;
+ *		}
+ *
+ *		ret = idm_command_run(command, __reboot_result_callback, ad);
+ *		if (ret != 0) {
+ *			_E("failed to idm_command_run");
+ *			idm_command_stop(ad->command);
+ *			idm_command_free(command);
+ *			return;
+ *		}
+ * }
+ * @endcode
+ */
 int idm_command_set_power_cmd(idm_command_h command, idm_cmd_power_e cmd, const char* reason);
+
+/**
+ * @brief Sets the command regarding diagnosis
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[in] cmd The command regarding diagnosis
+ * @param[in] detail The details for setting @cmd
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_cmd_diagnosis_e
+ */
 int idm_command_set_diagnosis_cmd(idm_command_h command, idm_cmd_diagnosis_e cmd, const char* detail);
+
+/**
+ * @brief Sets the command for getting information
+ * @privilege http://tizen.org/privilege/systemmonitor
+ * @remarks This is not for use by third-party applications.
+ *          This is not thread safe.
+ * @param[in] command The idm_command handle
+ * @param[in] cmd The command for getting information
+ * @param[in] detail The details for setting @cmd
+ * @return 0 on success, otherwise a negative error value
+ * @see idm_cmd_info_e
+ *
+ * @par Example
+ * @code
+ * #include <libidm.h>
+ *
+ * static void __result_cb(idm_command_h command, idm_result_e result, idm_reason_e reason, const char *detail, void *data)
+ * {
+ * 		unsigned long id;
+ * 		idm_command_get_id(command, &id);
+ *
+ * 		_D("[%d] result : %d, reason : %d, detail : %s", id, result, reason, detail ? detail : "None");
+ *
+ * 		if (result != IDM_RESULT_RUNNING) {
+ * 			idm_command_free(command);
+ * 		}
+ * }
+ *
+ * static void __get_taskinfo(char *request, unsigned long id)
+ * {
+ * 		idm_command_h command = NULL;
+ * 		int ret = -1;
+ *
+ * 		idm_command_new(&command);
+ * 		if (ret != 0) {
+ * 			_E("failed to idm_command_new");
+ * 			return;
+ * 		}
+ *
+ * 		idm_command_set_id(command, id);
+ *
+ * 		ret = idm_command_set_info_cmd(command, IDM_CMD_INFO_GET_TASKINFO, request);
+ * 		if (ret != 0) {
+ * 			_E("failed to idm_command_set_info_cmd");
+ * 			idm_command_stop(ad->command);
+ * 			idm_command_free(command);
+ * 			return;
+ * 		}
+ *
+ * 		ret = idm_command_run(command, __result_cb, NULL);
+ * 		if (ret != 0) {
+ * 			_E("failed to idm_command_run");
+ * 			idm_command_stop(ad->command);
+ * 			idm_command_free(command);
+ * 			return;
+ * 		}
+ * }
+ * @endcode
+ */
 int idm_command_set_info_cmd(idm_command_h command, idm_cmd_info_e cmd, const char* detail);
 
 #ifdef __cplusplus