Add system settings API doxygen

Change-Id: I33889b63b900d3db1a5f941e631ff545ec385839
Signed-off-by: JinWang An <jinwang.an@samsung.com>

diff --git a/include/system_settings.h b/include/system_settings.h
index 5f29a89..097eb7f 100644 (file)
--- a/include/system_settings.h
+++ b/include/system_settings.h
@@ -92,7 +92,7 @@ typedef enum {
        SYSTEM_SETTINGS_KEY_ACCESSIBILITY_GRAYSCALE,    /**< (bool) Indicates whether accessibility grayscale is enabled on the device. (Since 5.5) */
        SYSTEM_SETTINGS_KEY_ACCESSIBILITY_NEGATIVE_COLOR,       /**< (bool) Indicates whether accessibility negative color is enabled on the device. (Since 5.5) */
        SYSTEM_SETTINGS_KEY_ROTARY_EVENT_ENABLED,       /**< (bool) Indicates whether rotary event is enabled on the device. (Since 5.5) */
-       SYSTEM_SETTINGS_KEY_MAX,
+       SYSTEM_SETTINGS_KEY_MAX, /**< max of system settings key */
 } system_settings_key_e;
 
 /**
@@ -144,6 +144,7 @@ typedef void* system_settings_cb_id;
 /**
  * @platform
  * @brief Sets the system settings value associated with the given key as an integer.
+ * @details This API is used to set an int value for a key with an int type value in System Settings APIs. When using this function, be careful not to include keys of other types (such as string or bool) as parameters.
  * @since_tizen 2.3
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -152,32 +153,34 @@ typedef void* system_settings_cb_id;
  * @param[out] value The new system settings value of the given key
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- */
+  */
 int system_settings_set_value_int(system_settings_key_e key, int value);
 
 /**
  * @brief Gets the system settings value associated with the given key as an integer.
+ * @details This API is used to get the int value set for a key with an int type value in System Settings APIs. When using this function, be careful not to include keys of other types (such as string or bool) as parameters
  * @since_tizen 2.3
  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
  * @param[in] key The key name of the system settings
  * @param[out] value The current system settings value of the given key
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this function since 2.3.1.
+  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this function since 2.3.1.
  */
 int system_settings_get_value_int(system_settings_key_e key, int *value);
 
 /**
  * @platform
  * @brief Sets the system settings value associated with the given key as a boolean.
+ * @details This API is used to set a bool value for a key with a bool type value in System Settings APIs. When using this function, be careful not to include keys of other types (such as string or int) as parameters.
  * @since_tizen 2.3
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -186,25 +189,26 @@ int system_settings_get_value_int(system_settings_key_e key, int *value);
  * @param[out] value The new system settings value of the given key
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
- */
+  */
 int system_settings_set_value_bool(system_settings_key_e key, bool value);
 
 /**
  * @brief Gets the system settings value associated with the given key as a boolean.
+ * @details This API is used to get the bool value set for a key with a bool type value in System Settings APIs. When using this function, be careful not to include keys of other types (such as string or int) as parameters
  * @since_tizen 2.3
  * @remarks When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
  * @param[in] key The key name of the system settings
  * @param[out] value The current system settings value of the given key
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this function since 2.3.1.
  */
 int system_settings_get_value_bool(system_settings_key_e key, bool *value);
@@ -212,6 +216,7 @@ int system_settings_get_value_bool(system_settings_key_e key, bool *value);
 /**
  * @platform
  * @brief Sets the system settings value associated with the given key as a string.
+ * @details This API is used to set a string value for a key that can be set string in System Settings APIs. When using this function, be careful not to include keys of other types (such as int or bool) as parameters.
  * @since_tizen 2.3
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -220,31 +225,41 @@ int system_settings_get_value_bool(system_settings_key_e key, bool *value);
  * @param[out] value The new system settings value of the given key
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
  */
 int system_settings_set_value_string(system_settings_key_e key, const char *value);
 
 /**
  * @brief Gets the system settings value associated with the given key as a string.
+ * @details This API is used to get the string value set for a string key in System Settings APIs. When using this function, be careful not to include keys of other types (such as int or bool) as parameters
  * @since_tizen 2.3
  * @remarks You must release @a value using free(). When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
  * @param[in] key The key name of the system settings
  * @param[out] value The current system settings value of the given key
  * @return 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @code
+ *  char *value = NULL;
+ *  int retcode = system_settings_get_value_string(SYSTEM_SETTINGS_KEY_LOCALE_COUNTRY, &value);
+ *  if (retcode == SYSTEM_SETTINGS_ERROR_NONE) {
+ *    printf("%s", value);
+ *    free(value);
+ *  }
+ * @endcode
  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this function since 2.3.1.
  */
 int system_settings_get_value_string(system_settings_key_e key, char **value);
 
 /**
  * @brief Sets a change event callback for the given system settings key.
+ * @details This function is used to specify a callback function that is called when a key value changes. Each key can have only one callback function specified. To release this callback function, you can use the system_settings_unset_changed_cb() function
  * @since_tizen 2.3
  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb. When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
  * @param[in] key The key name of the system settings
@@ -252,9 +267,9 @@ int system_settings_get_value_string(system_settings_key_e key, char **value);
  * @param[in] user_data The user data to be passed to the callback function
  * @return 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
- * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
+ * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @post system_settings_changed_cb() will be invoked.
  *
  * @see system_settings_unset_changed_cb()
@@ -266,14 +281,15 @@ int system_settings_set_changed_cb(system_settings_key_e key, system_settings_ch
 
 /**
  * @brief Unsets the callback function.
+ * @details This function is used to release the callback function specified by system_settings_set_changed_cb().
  * @since_tizen 2.3
  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb. When the feature related to the @a key is not supported on the device, #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED will be returned.
  * @param[in] key The key name of the system settings
  * @return 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
- * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
+ * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  *
  * @see system_settings_set_changed_cb()
  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this function since 2.3.1.
@@ -283,6 +299,7 @@ int system_settings_unset_changed_cb(system_settings_key_e key);
 /**
  * @platform
  * @brief Called to get each string value from string typed list.
+ * @details This callback is used in system_settings_foreach_value_string(). Through this callback, the stored string list is passed one by one.
  * @since_tizen 3.0
  * @param[in] index zero based number indicating index of node in a list
  * @param[in] value value returned from the list
@@ -294,6 +311,7 @@ typedef bool (*system_settings_iter_cb)(int index, const char *value, void *cb_d
 /**
  * @platform
  * @brief Iterate the system settings value associated with the given key as a string type.
+ * @details This function is used to pass the path list of ringtones one by one through a callback when using #SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE.
  * @since_tizen 3.0
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -303,16 +321,17 @@ typedef bool (*system_settings_iter_cb)(int index, const char *value, void *cb_d
  * @param[in] user_data  The user data passed from caller-side
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
  */
 int system_settings_foreach_value_string(system_settings_key_e key, system_settings_iter_cb callback, void *user_data);
 
 /**
  * @platform
  * @brief Adds the system settings value associated with the given key as a string type if it supports List iteration.
+ * @details This function is used to add the path of the ringtone when using a KEY such as #SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE.
  * @since_tizen 3.0
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -321,16 +340,17 @@ int system_settings_foreach_value_string(system_settings_key_e key, system_setti
  * @param[in] value string typed value to be appended
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
  */
 int system_settings_add_value_string(system_settings_key_e key, const char *value);
 
 /**
  * @platform
  * @brief Delete the system settings value associated with the given key as an string type if it supports List iteration.
+ * @details This function is used to delete the path of the ringtone when using a KEY such as #SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE.
  * @since_tizen 3.0
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/systemsettings.admin
@@ -339,10 +359,10 @@ int system_settings_add_value_string(system_settings_key_e key, const char *valu
  * @param[in] value string typed value to be removed
  * @return @c 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
+ * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
  * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
- * @retval #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
- * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
  */
 int system_settings_delete_value_string(system_settings_key_e key, const char *value);
 
@@ -357,8 +377,8 @@ int system_settings_delete_value_string(system_settings_key_e key, const char *v
  * @param[in] user_data The user data to be passed to the callback function
  * @return 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
- * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @post system_settings_changed_cb() will be invoked.
  *
  * @see system_settings_remove_changed_cb()
@@ -376,8 +396,8 @@ int system_settings_add_changed_cb(system_settings_key_e key, system_settings_ch
  * @param[in] callback The callback function to be removed
  * @return 0 on success, otherwise a negative error value
  * @retval #SYSTEM_SETTINGS_ERROR_NONE Successful
- * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED The related feature is not supported on the device
+ * @retval #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
  *
  * @see system_settings_add_changed_cb()
  */