From: JinWang An Date: Mon, 30 Sep 2024 07:26:28 +0000 (+0900) Subject: Add system settings API doxygen X-Git-Tag: accepted/tizen/unified/20241004.041855^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=064ad6c1e801048f51ee687870d481ec866d9334;p=platform%2Fcore%2Fapi%2Fsystem-settings.git Add system settings API doxygen Change-Id: I33889b63b900d3db1a5f941e631ff545ec385839 Signed-off-by: JinWang An --- diff --git a/include/system_settings.h b/include/system_settings.h index 5f29a89..097eb7f 100644 --- 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) MUST NOT be declared to use this function since 2.3.1. + * @warning %http://tizen.org/privilege/systemsettings (public level privilege) MUST NOT 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) MUST NOT 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) MUST NOT 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) MUST NOT 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() */