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 lets an application to save or restore its settings.
55 * The following example demonstrates how to use the %AppSetting class.
59 * AppSettingForm::RefreshSetting(void)
61 * AppSetting* pAppSetting = AppSetting::GetInstance();
62 * AppAssert(pAppSetting);
64 * bool valueBool = false;
66 * const String strLn(L"\n");
70 * AppAssert(pAppSetting->GetValue(L"checkbox1", valueBool) == E_SUCCESS);
71 * settingText += L"checkbox1: ";
72 * settingText += strFalseTrue[valueBool ? 1 : 0];
73 * settingText += strLn;
75 * AppAssert(pAppSetting->GetValue(L"slider1", valueInt) == E_SUCCESS);
76 * settingText += L"slider1: ";
77 * settingText += Integer(valueInt).ToString();
78 * settingText += strLn;
80 * AppAssert(pAppSetting->GetValue(L"editbox1", valueString) == E_SUCCESS);
81 * settingText += L"editbox1: ";
82 * settingText += valueString;
83 * settingText += strLn;
88 * AppSettingForm::SetSettingValueSet1(void)
90 * AppSetting* pAppSetting = AppSetting::GetInstance();
91 * AppAssert(pAppSetting);
93 * AppAssert(pAppSetting->SetValue(L"checkbox1", false) == E_SUCCESS);
94 * AppAssert(pAppSetting->SetValue(L"slider1", 100) == E_SUCCESS);
95 * AppAssert(pAppSetting->SetValue(L"editbox1", String(L"AppSetting working!")) == E_SUCCESS);
96 * AppAssert(pAppSetting->SetValue(L"expanditem1", String(L"1 minute")) == E_SUCCESS);
97 * AppAssert(pAppSetting->SetValue(L"expanditem1", false) == E_SUCCESS);
98 * AppAssert(pAppSetting->SetValue(L"slider2", 0) == E_SUCCESS);
99 * AppAssert(pAppSetting->SetValue(L"editbox2", String(L"AppSetting running!")) == E_SUCCESS);
105 class _OSP_EXPORT_ AppSetting
106 : public Tizen::Base::Object
110 * Gets the application setting instance.
114 * @return A pointer to the %AppSetting instance, @n
115 * else @c null if it fails
116 * @exception E_SUCCESS The method is successful.
117 * @exception E_OUT_OF_MEMORY The memory is insufficient.
118 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
119 * @remarks It returns an instance for the latest setting. @n
120 * The specific error code can be accessed using the GetLastResult() method.
122 static AppSetting* GetInstance(void);
125 * Gets the application setting instance of the specified version.
129 * @return A pointer to the %AppSetting instance, @n
130 * else @c null if it fails
131 * @param[in] settingVersion The version of setting is retrieved from GetAppSettingVersionListN()
132 * @exception E_SUCCESS The method is successful.
133 * @exception E_OBJ_NOT_FOUND The specified version is not found.
134 * @exception E_OUT_OF_MEMORY The memory is insufficient.
135 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
136 * @remarks The specific error code can be accessed using the GetLastResult() method.
137 * @see GetAppSettingVersionListN()
139 static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
142 * Gets the application setting instance of the specified AppId.
146 * @privlevel platform
147 * @privilege %http://tizen.org/privilege/appsetting
149 * @return A pointer to the %AppSetting instance, @n
150 * else @c null if it fails
151 * @param[in] appId The AppId of the application that has a valid application setting
152 * @exception E_SUCCESS The method is successful.
153 * @exception E_OBJ_NOT_FOUND The instance of specified AppId does not have setting information.
154 * @exception E_OUT_OF_MEMORY The memory is insufficient.
155 * @exception E_INVALID_ARG The specified input parameter is invalid.
156 * @exception E_APP_NOT_INSTALLED The AppId is not found.
157 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
158 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
159 * @remarks The specific error code can be accessed using the GetLastResult() method.
160 * @see ReleaseInstanceByAppId()
162 static AppSetting* GetInstanceByAppId(const AppId& appId);
165 * Releases the specified application setting instance.
169 * @privlevel platform
170 * @privilege %http://tizen.org/privilege/appsetting
172 * @return An error code
173 * @param[in] appId The AppId of the application that has a valid application setting
174 * @exception E_SUCCESS The method is successful.
175 * @exception E_OBJ_NOT_FOUND The specified instance of AppId is not found or already released.
176 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
177 * @remarks Individual instances are managed by the platform. @n
178 * It is recommended to release instances to reduce memory usage.
179 * @see GetInstanceByAppId()
181 static result ReleaseInstanceByAppId(const AppId& appId);
184 * Gets a list of all the versions that existed prior to the current version. @n
185 * The versions listed are based on the setting.xml file, which is generated when an application is installed.
189 * @return A pointer to the list that contains the Tizen::Base::String instances of version list
190 * @exception E_SUCCESS The method is successful.
191 * @exception E_OUT_OF_MEMORY The memory is insufficient.
192 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
193 * @remarks The latest version string is located in the first position.
194 * If the old version does not exist then return empty collection. @n
195 * The specific error code can be accessed using the GetLastResult() method.
197 static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
200 * Gets a @c bool value associated with the specified @c id.
204 * @return An error code
205 * @param[in] id The ID of the value to retrieve
206 * @param[out] value A boolean value to retrieve
207 * @exception E_SUCCESS The method is successful.
208 * @exception E_OUT_OF_MEMORY The memory is insufficient.
209 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
210 * @exception E_INVALID_ARG A specified input parameter is invalid.
211 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
213 result GetValue(const Tizen::Base::String& id, bool& value) const;
216 * Gets an integer value associated with the specified @c id.
220 * @return An error code
221 * @param[in] id The ID of the value to retrieve
222 * @param[out] value An integer value to retrieve
223 * @exception E_SUCCESS The method is successful.
224 * @exception E_OUT_OF_MEMORY The memory is insufficient.
225 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
226 * @exception E_INVALID_ARG A specified input parameter is invalid.
227 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
229 result GetValue(const Tizen::Base::String& id, int& value) const;
232 * Gets a string value associated with the specified @c id.
236 * @return An error code
237 * @param[in] id The id of the value to retrieve
238 * @param[out] value A string value to retrieve
239 * @exception E_SUCCESS The method is successful.
240 * @exception E_OUT_OF_MEMORY The memory is insufficient.
241 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
242 * @exception E_INVALID_ARG A specified input parameter is invalid.
243 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
245 result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
248 * Sets a @c bool value associated with the specified @c id.
252 * @return An error code
253 * @param[in] id The ID of the value to modify
254 * @param[in] value A boolean value
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_OUT_OF_MEMORY The memory is insufficient.
257 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
258 * @exception E_INVALID_ARG A specified input parameter is invalid.
259 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
260 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
262 result SetValue(const Tizen::Base::String& id, bool value);
265 * Sets an integer value associated with the specified @c id.
269 * @return An error code
270 * @param[in] id The ID of the value to modify
271 * @param[in] value An integer value
272 * @exception E_SUCCESS The method is successful.
273 * @exception E_OUT_OF_MEMORY The memory is insufficient.
274 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
275 * @exception E_OUT_OF_RANGE The specified @c value is out of range.
276 * @exception E_INVALID_ARG A specified input parameter is invalid.
277 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
278 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
280 result SetValue(const Tizen::Base::String& id, int value);
283 * Sets a string value associated with the specified @c id.
287 * @return An error code
288 * @param[in] id The ID of the value to modify
289 * @param[in] value A string value
290 * @exception E_SUCCESS The method is successful.
291 * @exception E_OUT_OF_MEMORY The memory is insufficient.
292 * @exception E_OBJ_NOT_FOUND The specified @c id is not found in the application setting.
293 * @exception E_OUT_OF_RANGE The specified string length is out of range.
294 * @exception E_INVALID_ARG A specified input parameter is invalid.
295 * @exception E_TYPE_MISMATCH The operation has attempted to access different types.
296 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
298 result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
301 * Sets a setting event listener.
305 * @return An error code
306 * @param[in] pListener An instance of IAppSettingEventListener to set, @n
307 * else @c null to clear a previous one
308 * @exception E_SUCCESS The method is successful.
310 result SetAppSettingEventListener(IAppSettingEventListener* pListener);
314 * This default constructor is intentionally declared as private to implement the Singleton semantic.
321 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
325 AppSetting(const AppSetting& rhs);
328 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
332 AppSetting& operator =(const AppSetting& rhs);
335 * This destructor is intentionally declared as private to implement the Singleton semantic.
339 virtual ~AppSetting(void);
341 static void InitSingleton(void);
342 static void DestroySingleton(void);
345 friend class _AppSettingImpl;
346 class _AppSettingImpl* __pAppSettingImpl;
347 static AppSetting* __pAppSettingInstance;
352 #endif // _FAPP_APP_SETTING_H_