Merge "Calling g_io_channel_set_close_on_unref() after crating channel" into tizen_2.1
[platform/framework/native/appfw.git] / inc / FAppAppSetting.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19  * @file        FAppAppSetting.h
20  * @brief       This is the header file for the %AppSetting class.
21  *
22  * This header file contains the declarations of the %AppSetting class.
23  */
24
25 #ifndef _FAPP_APP_SETTING_H_
26 #define _FAPP_APP_SETTING_H_
27
28 #include <FBaseTypes.h>
29 #include <FBaseString.h>
30 #include <FBaseObject.h>
31 #include <FAppTypes.h>
32
33
34 namespace Tizen { namespace Base { namespace Collection
35 {
36 class IList;
37 }}}
38
39
40 namespace Tizen { namespace App
41 {
42
43 class IAppSettingEventListener;
44
45 /**
46  * @class       AppSetting
47  * @brief       This class manages an application's settings.
48  *
49  * @since       2.0
50  *
51  * @final       This class is not intended for extension.
52  *
53  * The %AppSetting class lets an application to save or restore its settings.
54  *
55  *
56  * The following example demonstrates how to use the %AppSetting class.
57  *
58  * @code
59  *      void
60  *      AppSettingForm::RefreshSetting(void)
61  *      {
62  *              AppSetting* pAppSetting = AppSetting::GetInstance();
63  *              AppAssert(pAppSetting);
64  *
65  *              bool valueBool = false;
66  *              int valueInt = 0;
67  *              const String strLn(L"\n");
68  *              String valueString;
69  *              String settingText;
70  *
71  *              AppAssert(pAppSetting->GetValue(L"checkbox1", valueBool) == E_SUCCESS);
72  *              settingText += L"checkbox1: ";
73  *              settingText += strFalseTrue[valueBool ? 1 : 0];
74  *              settingText += strLn;
75  *
76  *              AppAssert(pAppSetting->GetValue(L"slider1", valueInt) == E_SUCCESS);
77  *              settingText += L"slider1: ";
78  *              settingText += Integer(valueInt).ToString();
79  *              settingText += strLn;
80  *
81  *              AppAssert(pAppSetting->GetValue(L"editbox1", valueString) == E_SUCCESS);
82  *              settingText += L"editbox1: ";
83  *              settingText += valueString;
84  *              settingText += strLn;
85  *              // . . .
86  *      }
87  *
88  *      void
89  *      AppSettingForm::SetSettingValueSet1(void)
90  *      {
91  *              AppSetting* pAppSetting = AppSetting::GetInstance();
92  *              AppAssert(pAppSetting);
93  *
94  *              AppAssert(pAppSetting->SetValue(L"checkbox1", false) == E_SUCCESS);
95  *              AppAssert(pAppSetting->SetValue(L"slider1", 100) == E_SUCCESS);
96  *              AppAssert(pAppSetting->SetValue(L"editbox1", String(L"AppSetting working!")) == E_SUCCESS);
97  *              AppAssert(pAppSetting->SetValue(L"expanditem1", String(L"1 minute")) == E_SUCCESS);
98  *              AppAssert(pAppSetting->SetValue(L"expanditem1", false) == E_SUCCESS);
99  *              AppAssert(pAppSetting->SetValue(L"slider2", 0) == E_SUCCESS);
100  *              AppAssert(pAppSetting->SetValue(L"editbox2", String(L"AppSetting running!")) == E_SUCCESS);
101  *              // . . .
102  *      }
103  * @endcode
104  *
105  */
106 class _OSP_EXPORT_ AppSetting
107         : public Tizen::Base::Object
108 {
109 public:
110         /**
111          * Gets the application setting instance.
112          *
113          * @since       2.0
114          *
115          * @return              A pointer to the %AppSetting instance, @n
116          *                              else @c null if it fails
117          * @exception   E_SUCCESS                       The method is successful.
118          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
119          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
120          * @remarks             It returns an instance for the latest setting. @n
121          *                              The specific error code can be accessed using the GetLastResult() method.
122          */
123         static AppSetting* GetInstance(void);
124
125         /**
126          * Gets the application setting instance of the specified version.
127          *
128          * @since       2.0
129          *
130          * @return              A pointer to the %AppSetting instance, @n
131          *                              else @c null if it fails
132          * @param[in]   settingVersion          The version of setting is retrieved from GetAppSettingVersionListN()
133          * @exception   E_SUCCESS                       The method is successful.
134          * @exception   E_OBJ_NOT_FOUND         The specified version is not found.
135          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
136          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
137          * @remarks     The specific error code can be accessed using the GetLastResult() method.
138          * @see                 GetAppSettingVersionListN()
139          */
140         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
141
142         /**
143          * Gets the application setting instance of the specified AppId.
144          *
145          * @since       2.0
146          *
147          * @privlevel   platform
148          * @privilege   %http://tizen.org/privilege/appsetting
149          *
150          * @return              A pointer to the %AppSetting instance, @n
151          *                              else @c null if it fails
152          * @param[in]   appId                           The AppId of the application that has a valid application setting
153          * @exception   E_SUCCESS                       The method is successful.
154          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
155          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
156          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
157          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
158          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
159          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
160          * @remarks             The specific error code can be accessed using the GetLastResult() method.
161          * @see                 ReleaseInstanceByAppId()
162          */
163         static AppSetting* GetInstanceByAppId(const AppId& appId);
164
165         /**
166          * Releases the specified application setting instance.
167          *
168          * @since       2.0
169          *
170          * @privlevel   platform
171          * @privilege   %http://tizen.org/privilege/appsetting
172          *
173          * @return              An error code
174          * @param[in]   appId                           The AppId of the application that has a valid application setting
175          * @exception   E_SUCCESS                       The method is successful.
176          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
177          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
178          * @remarks             Individual instances are managed by the platform. @n
179          *                              It is recommended to release instances to reduce memory usage.
180          * @see                 GetInstanceByAppId()
181          */
182         static result ReleaseInstanceByAppId(const AppId& appId);
183
184         /**
185          * Gets a list of all the versions that existed prior to the current version. @n
186          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
187          *
188          * @since       2.0
189          *
190          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list
191          * @exception   E_SUCCESS                       The method is successful.
192          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
193          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
194          * @remarks             The latest version string is located in the first position.
195          *                              If the old version does not exist then return empty collection. @n
196          *                              The specific error code can be accessed using the GetLastResult() method.
197          */
198         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
199
200         /**
201          * Gets a @c bool value associated with the specified @c id.
202          *
203          * @since       2.0
204          *
205          * @return              An error code
206          * @param[in]   id                                      The ID of the value to retrieve
207          * @param[out]  value                           A boolean value to retrieve
208          * @exception   E_SUCCESS                       The method is successful.
209          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
210          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
211          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
212          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
213          */
214         result GetValue(const Tizen::Base::String& id, bool& value) const;
215
216         /**
217          * Gets an integer value associated with the specified @c id.
218          *
219          * @since       2.0
220          *
221          * @return              An error code
222          * @param[in]   id                                      The ID of the value to retrieve
223          * @param[out]  value                           An integer value to retrieve
224          * @exception   E_SUCCESS                       The method is successful.
225          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
226          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
227          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
228          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
229          */
230         result GetValue(const Tizen::Base::String& id, int& value) const;
231
232         /**
233          * Gets a string value associated with the specified @c id.
234          *
235          * @since       2.0
236          *
237          * @return              An error code
238          * @param[in]   id                                      The id of the value to retrieve
239          * @param[out]  value                           A string value to retrieve
240          * @exception   E_SUCCESS                       The method is successful.
241          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
242          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
243          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
244          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
245          */
246         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
247
248         /**
249          * Sets a @c bool value associated with the specified @c id.
250          *
251          * @since       2.0
252          *
253          * @return              An error code
254          * @param[in]   id                                      The ID of the value to modify
255          * @param[in]   value                           A boolean value
256          * @exception   E_SUCCESS                       The method is successful.
257          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
258          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
259          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
260          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
261          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
262          */
263         result SetValue(const Tizen::Base::String& id, bool value);
264
265         /**
266          * Sets an integer value associated with the specified @c id.
267          *
268          * @since       2.0
269          *
270          * @return              An error code
271          * @param[in]   id                                      The ID of the value to modify
272          * @param[in]   value                           An integer value
273          * @exception   E_SUCCESS                       The method is successful.
274          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
275          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
276          * @exception   E_OUT_OF_RANGE          The specified @c value is out of range.
277          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
278          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
279          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
280          */
281         result SetValue(const Tizen::Base::String& id, int value);
282
283         /**
284          * Sets a string value associated with the specified @c id.
285          *
286          * @since       2.0
287          *
288          * @return              An error code
289          * @param[in]   id                                      The ID of the value to modify
290          * @param[in]   value                           A string value
291          * @exception   E_SUCCESS                       The method is successful.
292          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
293          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
294          * @exception   E_OUT_OF_RANGE          The specified string length is out of range.
295          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
296          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
297          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
298          */
299         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
300
301         /**
302          * Sets a setting event listener.
303          *
304          * @since       2.0
305          *
306          * @return              An error code
307          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
308          *                                  else @c null to clear a previous one
309          * @exception   E_SUCCESS                       The method is successful.
310          */
311         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
312
313 private:
314         /**
315          * This default constructor is intentionally declared as private to implement the Singleton semantic.
316          *
317          * @since       2.0
318          */
319         AppSetting(void);
320
321         /**
322          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
323          *
324          * @since       2.0
325          */
326         AppSetting(const AppSetting& rhs);
327
328         /**
329          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
330          *
331          * @since       2.0
332          */
333         AppSetting& operator =(const AppSetting& rhs);
334
335         /**
336          * This destructor is intentionally declared as private to implement the Singleton semantic.
337          *
338          * @since       2.0
339          */
340         virtual ~AppSetting(void);
341
342         static void InitSingleton(void);
343         static void DestroySingleton(void);
344
345 private:
346         friend class _AppSettingImpl;
347         class _AppSettingImpl* __pAppSettingImpl;
348         static AppSetting* __pAppSettingInstance;
349
350 }; // AppSetting
351 } } // Tizen::App
352
353 #endif // _FAPP_APP_SETTING_H_