X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppAppSetting.h;h=303b4309afd22b12d15831f3b46eb60d09eb6371;hb=0a3f6678afe1bdff47660be2598a82d6d037c161;hp=df63ca944a07d55c52ec98532db6c007ee648fdd;hpb=51be9df64c710d680cf6212c0849ac90e7d76e41;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppAppSetting.h b/inc/FAppAppSetting.h index df63ca9..303b430 100644 --- a/inc/FAppAppSetting.h +++ b/inc/FAppAppSetting.h @@ -50,15 +50,16 @@ class IAppSettingEventListener; * @final This class is not intended for extension. * * The %AppSetting class is a helper class for an application to save or restore its settings. - * A setting entity is composed of a string-typed key and a value. The value type must be only of these three types: @c int, @c bool, and @c String. - * The settings are pre-defined in setting/setting.xml in the application's base directory + * A setting entity is composed of a string-typed key and a value. The value type must only be of three types: @c int, @c bool, and @c String. + * The settings are pre-defined at setting/setting.xml in the application's base directory * and they can be easily set with %Tizen IDE (Creating and Using Application Settings, Application Settings Editor). - * (The setting.xml is a symbolic link to the currently used setting file, which is related to the current version of the application.) @n - * The %AppSetting class is basically used for specific applications such as IME, which have no UI. + * (setting.xml is a symbolic link to the currently used setting file, which is related to the current version of the application.) @n + * The %AppSetting class is basically used for specific applications which have no UI, such as IME. * Because the applications have no external way to modify their settings, users can adjust the setting values through the setting application, which is delegated to manage the settings. - * For supporting the consistency of setting values between two applications, the target application and the setting application, when setting a value in the setting application, the target application is notified from the setting application through - * IAppSettingEventListener::OnAppSettingChanged() - * For detailed example on this class, see Task: App Setting. + * For supporting the consistency between the setting values of two applications, that is, the target application and the setting application, the setting application notifies the target application through + * the IAppSettingEventListener::OnAppSettingChanged() method when setting a value. + * + * For a detailed example on the %AppSetting class, see Task: App Setting. * * @see IAppSettingEventListener */ @@ -67,11 +68,11 @@ class _OSP_EXPORT_ AppSetting { public: /** - * Gets the application setting instance. + * Gets the pointer to the %AppSetting instance. * * @since 2.0 * - * @return A pointer to the %AppSetting instance for the last setting, @n + * @return The pointer to the %AppSetting instance for the last setting, @n * else @c null if it fails * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. @@ -81,24 +82,23 @@ public: static AppSetting* GetInstance(void); /** - * Gets the application setting instance of the specified version. + * Gets the pointer to the %AppSetting instance of the specified version. * * @since 2.0 * - * @return A pointer to the %AppSetting instance, @n + * @return The pointer to the %AppSetting instance, @n * else @c null if it fails - * @param[in] settingVersion The version of setting is retrieved from GetAppSettingVersionListN() + * @param[in] settingVersion The version of the setting which is retrieved from GetAppSettingVersionListN() * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The specified version is not found. + * @exception E_OBJ_NOT_FOUND The specified version has not been found. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM The method cannot proceed due to a severe system error. * @remarks The specific error code can be accessed using the GetLastResult() method. - * @see GetAppSettingVersionListN() */ static AppSetting* GetInstance(const Tizen::Base::String& settingVersion); /** - * Gets the application setting instance of the specified AppId. + * Gets an %AppSetting instance of the specified ID. * * @since 2.0 * @@ -107,12 +107,12 @@ public: * * @return A pointer to the %AppSetting instance, @n * else @c null if it fails - * @param[in] appId The AppId of the application that has a valid application setting + * @param[in] appId The ID of the application that has a valid application setting * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The instance of specified AppId does not have setting information. + * @exception E_OBJ_NOT_FOUND The specified @c appId does not have the required setting information. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_INVALID_ARG The specified input parameter is invalid. - * @exception E_APP_NOT_INSTALLED The AppId is not found. + * @exception E_APP_NOT_INSTALLED The @c appId has not been found. * @exception E_SYSTEM The method cannot proceed due to a severe system error. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. * @remarks The specific error code can be accessed using the GetLastResult() method. @@ -121,7 +121,7 @@ public: static AppSetting* GetInstanceByAppId(const AppId& appId); /** - * Releases the specified application setting instance. + * Releases the specified %AppSetting instance. * * @since 2.0 * @@ -129,24 +129,28 @@ public: * @privilege %http://tizen.org/privilege/appsetting * * @return An error code - * @param[in] appId The AppId of the application that has a valid application setting + * @param[in] appId The ID of the application that has a valid application setting * @exception E_SUCCESS The method is successful. - * @exception E_OBJ_NOT_FOUND The specified instance of AppId is not found or already released. + * @exception E_OBJ_NOT_FOUND Either of the following conditions has occurred: + * - The specified @c appId has not been found. + * - The specified @c appId is already released. * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method. - * @remarks Individual instances are managed by the platform. @n - * It is recommended to release instances to reduce memory usage. + * @remarks + * - Individual instances are managed by the platform. + * - It is recommended to release instances to reduce memory usage. * @see GetInstanceByAppId() */ static result ReleaseInstanceByAppId(const AppId& appId); /** - * Gets a list of all the versions that existed prior to the current version. @n - * The versions listed are based on the setting.xml file, which is generated when an application is installed. + * Gets the list of all the versions that existed prior to the current version. @n + * The versions are listed based on the setting.xml file, which is generated when an application is installed. * * @since 2.0 * - * @return A pointer to the list that contains the Tizen::Base::String instances of version list @n - * The latest version string is located in the first position. If the old version does not exist then return empty collection. + * @return A pointer to the list that contains the Tizen::Base::String instances of the version list @n + * The latest version string is located at the first position @n + * If the old version does not exist then an empty collection is returned. * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. * @exception E_SYSTEM The method cannot proceed due to a severe system error. @@ -155,108 +159,108 @@ public: static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void); /** - * Gets a @c bool value associated with the specified @c id. + * Gets the @c bool value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The ID of the value to retrieve - * @param[out] value A boolean value to retrieve + * @param[in] id The ID of the boolean value to retrieve + * @param[out] value The boolean value to retrieve * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. */ result GetValue(const Tizen::Base::String& id, bool& value) const; /** - * Gets an integer value associated with the specified @c id. + * Gets the integer value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The ID of the value to retrieve - * @param[out] value An integer value to retrieve + * @param[in] id The ID of the integer value to retrieve + * @param[out] value The integer value to retrieve * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. */ result GetValue(const Tizen::Base::String& id, int& value) const; /** - * Gets a string value associated with the specified @c id. + * Gets the string value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The id of the value to retrieve - * @param[out] value A string value to retrieve + * @param[in] id The ID of the string value to retrieve + * @param[out] value The string value to retrieve * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. */ result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const; /** - * Sets a @c bool value associated with the specified @c id. + * Sets the @c bool value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The ID of the value to modify - * @param[in] value A boolean value + * @param[in] id The ID of the boolean value to modify + * @param[in] value The boolean value * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. * @exception E_SYSTEM The method cannot proceed due to a severe system error. */ result SetValue(const Tizen::Base::String& id, bool value); /** - * Sets an integer value associated with the specified @c id. + * Sets the integer value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The ID of the value to modify - * @param[in] value An integer value + * @param[in] id The ID of the integer value to modify + * @param[in] value The integer value * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. - * @exception E_OUT_OF_RANGE The specified @c value is out of range. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. + * @exception E_OUT_OF_RANGE The specified @c value is out of the valid range. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. * @exception E_SYSTEM The method cannot proceed due to a severe system error. */ result SetValue(const Tizen::Base::String& id, int value); /** - * Sets a string value associated with the specified @c id. + * Sets the string value associated with the specified @c id. * * @since 2.0 * * @return An error code - * @param[in] id The ID of the value to modify - * @param[in] value A string value + * @param[in] id The ID of the string value to modify + * @param[in] value The string value * @exception E_SUCCESS The method is successful. * @exception E_OUT_OF_MEMORY The memory is insufficient. - * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting. - * @exception E_OUT_OF_RANGE The specified string length is out of range. + * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting. + * @exception E_OUT_OF_RANGE The specified string length is out of the valid range. * @exception E_INVALID_ARG A specified input parameter is invalid. - * @exception E_TYPE_MISMATCH The operation has attempted to access different types. + * @exception E_TYPE_MISMATCH The types accessed by the method do not match. * @exception E_SYSTEM The method cannot proceed due to a severe system error. */ result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value); /** - * Sets a setting event listener. + * Sets the setting event listener. * * @since 2.0 *