2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FAppAppSetting.h
19 * @brief This is the header file for the %AppSetting class.
21 * This header file contains the declarations of the %AppSetting class.
24 #ifndef _FAPP_APP_SETTING_H_
25 #define _FAPP_APP_SETTING_H_
27 #include <FBaseTypes.h>
28 #include <FBaseString.h>
29 #include <FBaseObject.h>
30 #include <FAppTypes.h>
33 namespace Tizen { namespace Base { namespace Collection
39 namespace Tizen { namespace App
42 class IAppSettingEventListener;
46 * @brief This class manages an application's settings.
50 * @final This class is not intended for extension.
52 * The %AppSetting class is a helper class for an application to save or restore its settings.
53 * 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.
54 * The settings are pre-defined at setting/setting.xml in the application's base directory
55 * and they can be easily set with %Tizen IDE (<a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/creating_running_app_setting.htm">Creating and Using Application Settings</a>, <a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/application_settings_editor.htm">Application Settings Editor</a>).
56 * (setting.xml is a symbolic link to the currently used setting file, which is related to the current version of the application.) @n
57 * The %AppSetting class is basically used for specific applications which have no UI, such as IME.
58 * 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.
59 * 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
60 * the IAppSettingEventListener::OnAppSettingChanged() method when setting a value.
62 * For a detailed example on the %AppSetting class, see <a href="../org.tizen.native.appprogramming/html/tutorials/app_tutorial/task_app_settings.htm?resultof=%22%41%70%70%53%65%74%74%69%6e%67%22%20%22%61%70%70%73%65%74%74%69%6e%67%22%20">Task: App Setting</a>.
64 * @see IAppSettingEventListener
66 class _OSP_EXPORT_ AppSetting
67 : public Tizen::Base::Object
71 * Gets the pointer to the %AppSetting instance.
75 * @return The pointer to the %AppSetting instance for the last setting, @n
76 * else @c null if it fails
77 * @exception E_SUCCESS The method is successful.
78 * @exception E_OUT_OF_MEMORY The memory is insufficient.
79 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
80 * @remarks The specific error code can be accessed using the GetLastResult() method.
82 static AppSetting* GetInstance(void);
85 * Gets the pointer to the %AppSetting instance of the specified version.
89 * @return The pointer to the %AppSetting instance, @n
90 * else @c null if it fails
91 * @param[in] settingVersion The version of the setting which is retrieved from GetAppSettingVersionListN()
92 * @exception E_SUCCESS The method is successful.
93 * @exception E_OBJ_NOT_FOUND The specified version has not been found.
94 * @exception E_OUT_OF_MEMORY The memory is insufficient.
95 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
96 * @remarks The specific error code can be accessed using the GetLastResult() method.
98 static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
101 * Gets an %AppSetting instance of the specified ID.
105 * @privlevel platform
106 * @privilege %http://tizen.org/privilege/appsetting
108 * @return A pointer to the %AppSetting instance, @n
109 * else @c null if it fails
110 * @param[in] appId The ID of the application that has a valid application setting
111 * @exception E_SUCCESS The method is successful.
112 * @exception E_OBJ_NOT_FOUND The specified @c appId does not have the required setting information.
113 * @exception E_OUT_OF_MEMORY The memory is insufficient.
114 * @exception E_INVALID_ARG The specified input parameter is invalid.
115 * @exception E_APP_NOT_INSTALLED The @c appId has not been found.
116 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
117 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
118 * @remarks The specific error code can be accessed using the GetLastResult() method.
119 * @see ReleaseInstanceByAppId()
121 static AppSetting* GetInstanceByAppId(const AppId& appId);
124 * Releases the specified %AppSetting instance.
128 * @privlevel platform
129 * @privilege %http://tizen.org/privilege/appsetting
131 * @return An error code
132 * @param[in] appId The ID of the application that has a valid application setting
133 * @exception E_SUCCESS The method is successful.
134 * @exception E_OBJ_NOT_FOUND Either of the following conditions has occurred:
135 * - The specified @c appId has not been found.
136 * - The specified @c appId is already released.
137 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
139 * - Individual instances are managed by the platform.
140 * - It is recommended to release instances to reduce memory usage.
141 * @see GetInstanceByAppId()
143 static result ReleaseInstanceByAppId(const AppId& appId);
146 * Gets the list of all the versions that existed prior to the current version. @n
147 * The versions are listed based on the setting.xml file, which is generated when an application is installed.
151 * @return A pointer to the list that contains the Tizen::Base::String instances of the version list @n
152 * The latest version string is located at the first position @n
153 * If the old version does not exist then an empty collection is returned.
154 * @exception E_SUCCESS The method is successful.
155 * @exception E_OUT_OF_MEMORY The memory is insufficient.
156 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
157 * @remarks The specific error code can be accessed using the GetLastResult() method.
159 static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
162 * Gets the @c bool value associated with the specified @c id.
166 * @return An error code
167 * @param[in] id The ID of the boolean value to retrieve
168 * @param[out] value The boolean value to retrieve
169 * @exception E_SUCCESS The method is successful.
170 * @exception E_OUT_OF_MEMORY The memory is insufficient.
171 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
172 * @exception E_INVALID_ARG A specified input parameter is invalid.
173 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
175 result GetValue(const Tizen::Base::String& id, bool& value) const;
178 * Gets the integer value associated with the specified @c id.
182 * @return An error code
183 * @param[in] id The ID of the integer value to retrieve
184 * @param[out] value The integer value to retrieve
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_OUT_OF_MEMORY The memory is insufficient.
187 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
188 * @exception E_INVALID_ARG A specified input parameter is invalid.
189 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
191 result GetValue(const Tizen::Base::String& id, int& value) const;
194 * Gets the string value associated with the specified @c id.
198 * @return An error code
199 * @param[in] id The ID of the string value to retrieve
200 * @param[out] value The string value to retrieve
201 * @exception E_SUCCESS The method is successful.
202 * @exception E_OUT_OF_MEMORY The memory is insufficient.
203 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
204 * @exception E_INVALID_ARG A specified input parameter is invalid.
205 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
207 result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
210 * Sets the @c bool value associated with the specified @c id.
214 * @return An error code
215 * @param[in] id The ID of the boolean value to modify
216 * @param[in] value The boolean value
217 * @exception E_SUCCESS The method is successful.
218 * @exception E_OUT_OF_MEMORY The memory is insufficient.
219 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
220 * @exception E_INVALID_ARG A specified input parameter is invalid.
221 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
222 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
224 result SetValue(const Tizen::Base::String& id, bool value);
227 * Sets the integer value associated with the specified @c id.
231 * @return An error code
232 * @param[in] id The ID of the integer value to modify
233 * @param[in] value The integer value
234 * @exception E_SUCCESS The method is successful.
235 * @exception E_OUT_OF_MEMORY The memory is insufficient.
236 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
237 * @exception E_OUT_OF_RANGE The specified @c value is out of the valid range.
238 * @exception E_INVALID_ARG A specified input parameter is invalid.
239 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
240 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
242 result SetValue(const Tizen::Base::String& id, int value);
245 * Sets the string value associated with the specified @c id.
249 * @return An error code
250 * @param[in] id The ID of the string value to modify
251 * @param[in] value The string value
252 * @exception E_SUCCESS The method is successful.
253 * @exception E_OUT_OF_MEMORY The memory is insufficient.
254 * @exception E_OBJ_NOT_FOUND The specified @c id has not been found in the application setting.
255 * @exception E_OUT_OF_RANGE The specified string length is out of the valid range.
256 * @exception E_INVALID_ARG A specified input parameter is invalid.
257 * @exception E_TYPE_MISMATCH The types accessed by the method do not match.
258 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
260 result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
263 * Sets the setting event listener.
267 * @return An error code
268 * @param[in] pListener An instance of IAppSettingEventListener to set, @n
269 * else @c null to clear a previous one
270 * @exception E_SUCCESS The method is successful.
272 result SetAppSettingEventListener(IAppSettingEventListener* pListener);
276 * This default constructor is intentionally declared as private to implement the Singleton semantic.
283 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
287 AppSetting(const AppSetting& rhs);
290 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
294 AppSetting& operator =(const AppSetting& rhs);
297 * This destructor is intentionally declared as private to implement the Singleton semantic.
301 virtual ~AppSetting(void);
303 static void InitSingleton(void);
304 static void DestroySingleton(void);
307 friend class _AppSettingImpl;
308 class _AppSettingImpl* __pAppSettingImpl;
309 static AppSetting* __pAppSettingInstance;
314 #endif // _FAPP_APP_SETTING_H_