Merge "Update deprecated libprivilege-control API functions." into tizen
[platform/framework/native/appfw.git] / inc / FAppAppRegistry.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                        FAppAppRegistry.h
19  * @brief                       This is the header file for the %AppRegistry class.
20  *
21  * This header file contains the declarations of the %AppRegistry class.
22  */
23
24 #ifndef _FAPP_APP_REGISTRY_H_
25 #define _FAPP_APP_REGISTRY_H_
26
27 #include <FBaseObject.h>
28 #include <FAppTypes.h>
29
30 namespace Tizen { namespace App
31 {
32
33 /**
34  * @class               AppRegistry
35  * @brief               This class manages an application's preferences.
36  *
37  * @since       2.0
38  *
39  * @final       This class is not intended for extension.
40  *
41  * The %AppRegistry class lets an application save or restore its preferences.
42  * An instance of this class can be obtained through the Application class.
43  * Also, since an application's state is generally restored in the App::OnAppInitializing() method and saved in the App::OnAppTerminating() method, an instance of this class is passed as an argument when these methods are invoked.
44  * @n
45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_namespace.htm">App Guide</a>.
46  *
47  * The following example demonstrates how to use the %AppRegistry class.
48  *
49  * @code
50  *
51  * void
52  * MyAppClass::AppRegistryCallSample(void)
53  * {
54  *      AppRegistry* pAppRegistry = GetAppRegistry();
55  *      String countKey("BasicAppRunCount");
56  *      String nameKey("BasicAppUserName");
57  *      String temperatureKey("BasicAppTemperature");
58  *      String name("BasicApp");
59  *      double temperature = 32.5;
60  *      result r = E_SUCCESS;
61  *      int     count = 0;
62  *
63  *      r = pAppRegistry->Get(nameKey, name);
64  *      if (r == E_KEY_NOT_FOUND)
65  *      {
66  *              pAppRegistry->Add(nameKey, name);
67  *      }
68  *
69  *      r = pAppRegistry->Get(countKey, count);
70  *      if (r == E_KEY_NOT_FOUND)
71  *      {
72  *              pAppRegistry->Add(countKey, count);
73  *      }
74  *
75  *      r = pAppRegistry->Get(temperatureKey, temperature);
76  *      if (r == E_KEY_NOT_FOUND)
77  *      {
78  *              pAppRegistry->Add(temperatureKey, temperature);
79  *      }
80  *
81  *      r = pAppRegistry->Save();
82  *      if (IsFailed(r))
83  *      {
84  *              // Failed to save data to registry
85  *      }
86  *
87  *      // Displays the retrieved data
88  *      AppLog("AppRegistry Name value [%ls]", name.GetPointer());
89  *      AppLog("AppRegistry count [%d]", count);
90  *      AppLog("AppRegistry temperature value [%f]", temperature);
91  *
92  *      // Updates the state of the application variables
93  *      count++;
94  *      name.Append(count);
95  *      temperature++;
96  *
97  *      // Saves the app registry
98  *      r = pAppRegistry->Set(nameKey, name);
99  *      if (IsFailed(r))
100  *      {
101  *              // Error condition
102  *      }
103  *
104  *      r = pAppRegistry->Set(countKey, count);
105  *      if (IsFailed(r))
106  *      {
107  *              // Error condition
108  *      }
109  *
110  *      r = pAppRegistry->Set(temperatureKey, temperature);
111  *      if (IsFailed(r))
112  *      {
113  *              // Error condition
114  *      }
115  *
116  *      r = pAppRegistry->Save();
117  *      if (IsFailed(r))
118  *      {
119  *              // Failed to save data to registry
120  *      }
121  *
122  *      // Retrieves the saved content
123  *      pAppRegistry->Get(nameKey, name);
124  *      pAppRegistry->Get(countKey, count);
125  *      pAppRegistry->Get(temperatureKey, temperature);
126  *
127  *      AppLog("AppRegistry Name value [%ls]", name.GetPointer());
128  *      AppLog("AppRegistry count [%d]", count);
129  *      AppLog("AppRegistry temperature value [%f]", temperature);
130  *
131  *      return;
132  * }
133  * @endcode
134  *
135  **/
136 class _OSP_EXPORT_ AppRegistry
137         : public Tizen::Base::Object
138 {
139 public:
140         /**
141          * Adds a string value along with the specified @c key.
142          *
143          * @since       2.0
144          *
145          * @return              An error code
146          * @param[in]   key                                             The key corresponding to the string value
147          * @param[in]   value                                   The string value
148          * @exception   E_SUCCESS                               The method is successful.
149          * @exception   E_INVALID_ARG                   The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
150          * @exception   E_KEY_ALREADY_EXIST             The specified @c key has already been used in the application preferences.
151          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
152          */
153         result Add(const Tizen::Base::String& key, const Tizen::Base::String& value);
154
155         /**
156          * Adds an integer value along with the specified @c key.
157          *
158          * @since       2.0
159          *
160          * @return              An error code
161          * @param[in]   key                                             The key corresponding to the integer value
162          * @param[in]   value                                   The integer value
163          * @exception   E_SUCCESS                               The method is successful.
164          * @exception   E_INVALID_ARG                   The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
165          * @exception   E_KEY_ALREADY_EXIST             The specified @c key has already been used in the application preferences.
166          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
167          */
168         result Add(const Tizen::Base::String& key, int value);
169
170         /**
171          * Adds a floating point value along with the specified @c key.
172          *
173          * @since       2.0
174          *
175          * @return              An error code
176          * @param[in]   key                                             The key corresponding to the floating point value
177          * @param[in]   value                                   The floating point value
178          * @exception   E_SUCCESS                               The method is successful.
179          * @exception   E_INVALID_ARG                   The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
180          * @exception   E_KEY_ALREADY_EXIST             The specified @c key has already been used in the application preferences.
181          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
182          */
183         result Add(const Tizen::Base::String& key, double value);
184
185         /**
186          * Sets the string value associated with the specified @c key.
187          *
188          * @since       2.0
189          *
190          * @return              An error code
191          * @param[in]   key                                     The key corresponding to the string value
192          * @param[in]   value                           The string value
193          * @exception   E_SUCCESS                       The method is successful.
194          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
195          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
196          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
197          */
198         result Set(const Tizen::Base::String& key, const Tizen::Base::String& value);
199
200         /**
201          * Sets the integer value associated with the specified @c key.
202          *
203          * @since       2.0
204          *
205          * @return              An error code
206          * @param[in]   key                                     The key corresponding to the integer value
207          * @param[in]   value                           The integer value
208          * @exception   E_SUCCESS                       The method is successful.
209          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
210          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
211          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
212          */
213         result Set(const Tizen::Base::String& key, int value);
214
215         /**
216          * Sets the floating point value associated with the specified @c key.
217          *
218          * @since       2.0
219          *
220          * @return              An error code
221          * @param[in]   key                                     The key corresponding to the floating point value
222          * @param[in]   value                           The floating point value
223          * @exception   E_SUCCESS                       The method is successful.
224          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
225          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
226          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
227          */
228         result Set(const Tizen::Base::String& key, double value);
229
230         /**
231          * Saves the values temporarily in the persistent storage. @n
232          * The %Save() method is invoked internally when the instance of this class is deleted.
233          *
234          * @since       2.0
235          *
236          * @return              An error code
237          * @exception   E_SUCCESS                       The method is successful.
238          */
239         result Save(void);
240
241         /**
242          * Removes the preference associated with the specified @c key.
243          *
244          * @since       2.0
245          *
246          * @return              An error code
247          * @param[in]   key                                     The key of the value to remove
248          * @exception   E_SUCCESS                       The method is successful.
249          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
250          */
251         result Remove(const Tizen::Base::String& key);
252
253         /**
254          * Gets the string value associated with the specified @c key.
255          *
256          * @since       2.0
257          *
258          * @return              An error code
259          * @param[in]   key                                     The key of the string value to retrieve
260          * @param[out]  value                           The string value to retrieve
261          * @exception   E_SUCCESS                       The method is successful.
262          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
263          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
264          */
265         result Get(const Tizen::Base::String& key, Tizen::Base::String& value) const;
266
267         /**
268          * Gets the integer value associated with the specified @c key.
269          *
270          * @since       2.0
271          *
272          * @return              An error code
273          * @param[in]   key                                     The key of the integer value to retrieve
274          * @param[out]  value                           The integer value to retrieve
275          * @exception   E_SUCCESS                       The method is successful.
276          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
277          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
278          */
279         result Get(const Tizen::Base::String& key, int& value) const;
280
281         /**
282          * Gets the floating point value associated with the specified @c key.
283          *
284          * @since       2.0
285          *
286          * @return              An error code
287          * @param[in]   key                                     The key of the floating point value to retrieve
288          * @param[out]  value                           The floating point value to retrieve
289          * @exception   E_SUCCESS                       The method is successful.
290          * @exception   E_INVALID_ARG           The specified @c key is empty or is a string with '\0' and @htmlonly '\n' @endhtmlonly.
291          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
292          */
293         result Get(const Tizen::Base::String& key, double& value) const;
294
295         /**
296          * Gets a pointer to the %AppRegistry instance.
297          *
298          * @since               2.0
299          *
300          * @return              A pointer to the %AppRegistry instance, @n
301          *                              else @c null if it fails
302          */
303         static AppRegistry* GetInstance(void);
304
305 private:
306         /**
307          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
308          *
309          * @since       2.0
310          */
311         AppRegistry(void);
312
313         /**
314          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
315          *
316          * @since       2.0
317          */
318         AppRegistry(const AppRegistry& rhs);
319
320         /**
321          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
322          *
323          * @since       2.0
324          */
325         AppRegistry& operator =(const AppRegistry& rhs);
326
327         /**
328          * This destructor is intentionally declared as private to implement the %Singleton semantic.
329          *
330          * @since       2.0
331          */
332         virtual ~AppRegistry(void);
333
334         /**
335          * Initializes this instance.
336          *
337          * @since       2.0
338          *
339          * @return      An error code
340          * @exception   E_SUCCESS       The method is successful.
341          * @exception   E_SYSTEM        A system error has occurred.
342          */
343         result Construct(void);
344
345 private:
346         class _AppRegistryImpl* __pAppRegistryImpl;
347
348         friend class _AppRegistryImpl;
349 }; // AppRegistry
350
351 } } // Tizen::App
352
353 #endif // _FAPP_APP_REGISTRY_H_