0d4d2c8b71917ef4397d98c3b7aab1c1a190290a
[platform/framework/native/appfw.git] / inc / FAppAppSetting.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
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
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
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.
15 //
16
17 /**
18  * @file        FAppAppSetting.h
19  * @brief       This is the header file for the %AppSetting class.
20  *
21  * This header file contains the declarations of the %AppSetting class.
22  */
23
24 #ifndef _FAPP_APP_SETTING_H_
25 #define _FAPP_APP_SETTING_H_
26
27 #include <FBaseTypes.h>
28 #include <FBaseString.h>
29 #include <FBaseObject.h>
30 #include <FAppTypes.h>
31
32
33 namespace Tizen { namespace Base { namespace Collection
34 {
35 class IList;
36 }}}
37
38
39 namespace Tizen { namespace App
40 {
41
42 class IAppSettingEventListener;
43
44 /**
45  * @class       AppSetting
46  * @brief       This class manages an application's settings.
47  *
48  * @since       2.0
49  *
50  * @final       This class is not intended for extension.
51  *
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 be only of these three types: @c int, @c bool, and @c String.
54  * The settings are pre-defined in 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  * (The 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 such as IME, which have no UI. 
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 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 OnAppSettingChanged()(see IAppSettingEventListener).
60  * For detailed example on this 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>.
61  * 
62  */
63 class _OSP_EXPORT_ AppSetting
64         : public Tizen::Base::Object
65 {
66 public:
67         /**
68          * Gets the application setting instance.
69          *
70          * @since       2.0
71          *
72          * @return              A pointer to the %AppSetting instance, @n
73          *                              else @c null if it fails
74          * @exception   E_SUCCESS                       The method is successful.
75          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
76          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
77          * @remarks             It returns an instance for the latest setting. @n
78          *                              The specific error code can be accessed using the GetLastResult() method.
79          */
80         static AppSetting* GetInstance(void);
81
82         /**
83          * Gets the application setting instance of the specified version.
84          *
85          * @since       2.0
86          *
87          * @return              A pointer to the %AppSetting instance, @n
88          *                              else @c null if it fails
89          * @param[in]   settingVersion          The version of setting is retrieved from GetAppSettingVersionListN()
90          * @exception   E_SUCCESS                       The method is successful.
91          * @exception   E_OBJ_NOT_FOUND         The specified version is not found.
92          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
93          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
94          * @remarks     The specific error code can be accessed using the GetLastResult() method.
95          * @see                 GetAppSettingVersionListN()
96          */
97         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
98
99         /**
100          * Gets the application setting instance of the specified AppId.
101          *
102          * @since       2.0
103          *
104          * @privlevel   platform
105          * @privilege   %http://tizen.org/privilege/appsetting
106          *
107          * @return              A pointer to the %AppSetting instance, @n
108          *                              else @c null if it fails
109          * @param[in]   appId                           The AppId of the application that has a valid application setting
110          * @exception   E_SUCCESS                       The method is successful.
111          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
112          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
113          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
114          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
115          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
116          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
117          * @remarks             The specific error code can be accessed using the GetLastResult() method.
118          * @see                 ReleaseInstanceByAppId()
119          */
120         static AppSetting* GetInstanceByAppId(const AppId& appId);
121
122         /**
123          * Releases the specified application setting instance.
124          *
125          * @since       2.0
126          *
127          * @privlevel   platform
128          * @privilege   %http://tizen.org/privilege/appsetting
129          *
130          * @return              An error code
131          * @param[in]   appId                           The AppId of the application that has a valid application setting
132          * @exception   E_SUCCESS                       The method is successful.
133          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
134          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
135          * @remarks             Individual instances are managed by the platform. @n
136          *                              It is recommended to release instances to reduce memory usage.
137          * @see                 GetInstanceByAppId()
138          */
139         static result ReleaseInstanceByAppId(const AppId& appId);
140
141         /**
142          * Gets a list of all the versions that existed prior to the current version. @n
143          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
144          *
145          * @since       2.0
146          *
147          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list
148          * @exception   E_SUCCESS                       The method is successful.
149          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
150          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
151          * @remarks             The latest version string is located in the first position.
152          *                              If the old version does not exist then return empty collection. @n
153          *                              The specific error code can be accessed using the GetLastResult() method.
154          */
155         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
156
157         /**
158          * Gets a @c bool value associated with the specified @c id.
159          *
160          * @since       2.0
161          *
162          * @return              An error code
163          * @param[in]   id                                      The ID of the value to retrieve
164          * @param[out]  value                           A boolean value to retrieve
165          * @exception   E_SUCCESS                       The method is successful.
166          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
167          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
168          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
169          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
170          */
171         result GetValue(const Tizen::Base::String& id, bool& value) const;
172
173         /**
174          * Gets an integer value associated with the specified @c id.
175          *
176          * @since       2.0
177          *
178          * @return              An error code
179          * @param[in]   id                                      The ID of the value to retrieve
180          * @param[out]  value                           An integer value to retrieve
181          * @exception   E_SUCCESS                       The method is successful.
182          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
183          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
184          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
185          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
186          */
187         result GetValue(const Tizen::Base::String& id, int& value) const;
188
189         /**
190          * Gets a string value associated with the specified @c id.
191          *
192          * @since       2.0
193          *
194          * @return              An error code
195          * @param[in]   id                                      The id of the value to retrieve
196          * @param[out]  value                           A string value to retrieve
197          * @exception   E_SUCCESS                       The method is successful.
198          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
199          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
200          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
201          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
202          */
203         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
204
205         /**
206          * Sets a @c bool value associated with the specified @c id.
207          *
208          * @since       2.0
209          *
210          * @return              An error code
211          * @param[in]   id                                      The ID of the value to modify
212          * @param[in]   value                           A boolean value
213          * @exception   E_SUCCESS                       The method is successful.
214          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
215          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
216          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
217          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
218          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
219          */
220         result SetValue(const Tizen::Base::String& id, bool value);
221
222         /**
223          * Sets an integer value associated with the specified @c id.
224          *
225          * @since       2.0
226          *
227          * @return              An error code
228          * @param[in]   id                                      The ID of the value to modify
229          * @param[in]   value                           An integer value
230          * @exception   E_SUCCESS                       The method is successful.
231          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
232          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
233          * @exception   E_OUT_OF_RANGE          The specified @c value is out of range.
234          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
235          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
236          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
237          */
238         result SetValue(const Tizen::Base::String& id, int value);
239
240         /**
241          * Sets a string value associated with the specified @c id.
242          *
243          * @since       2.0
244          *
245          * @return              An error code
246          * @param[in]   id                                      The ID of the value to modify
247          * @param[in]   value                           A string value
248          * @exception   E_SUCCESS                       The method is successful.
249          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
250          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
251          * @exception   E_OUT_OF_RANGE          The specified string length is out of range.
252          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
253          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
254          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
255          */
256         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
257
258         /**
259          * Sets a setting event listener.
260          *
261          * @since       2.0
262          *
263          * @return              An error code
264          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
265          *                                  else @c null to clear a previous one
266          * @exception   E_SUCCESS                       The method is successful.
267          */
268         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
269
270 private:
271         /**
272          * This default constructor is intentionally declared as private to implement the Singleton semantic.
273          *
274          * @since       2.0
275          */
276         AppSetting(void);
277
278         /**
279          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
280          *
281          * @since       2.0
282          */
283         AppSetting(const AppSetting& rhs);
284
285         /**
286          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
287          *
288          * @since       2.0
289          */
290         AppSetting& operator =(const AppSetting& rhs);
291
292         /**
293          * This destructor is intentionally declared as private to implement the Singleton semantic.
294          *
295          * @since       2.0
296          */
297         virtual ~AppSetting(void);
298
299         static void InitSingleton(void);
300         static void DestroySingleton(void);
301
302 private:
303         friend class _AppSettingImpl;
304         class _AppSettingImpl* __pAppSettingImpl;
305         static AppSetting* __pAppSettingInstance;
306
307 }; // AppSetting
308 } } // Tizen::App
309
310 #endif // _FAPP_APP_SETTING_H_