Enable build with iniparser v 3.1
[platform/framework/native/appfw.git] / inc / FSysSettingInfo.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        FSysSettingInfo.h
19  * @brief       This is the header file for the %SettingInfo class.
20  *
21  * This header file contains the declarations of the %SettingInfo class.
22  */
23
24 #ifndef _FSYS_SETTING_INFO_H_
25 #define _FSYS_SETTING_INFO_H_
26
27 #include <FBaseString.h>
28 #include <FBaseUuId.h>
29 #include <FBaseColIList.h>
30 #include <FSysISettingEventListener.h>
31 #include <FSysISettingInfoSetValueAsyncResultListener.h>
32
33 namespace Tizen { namespace System
34 {
35
36 /**
37  * @class       SettingInfo
38  * @brief       This class provides methods to manage the setting information.
39  *
40  * @since       2.0
41  *
42  * @final       This class is not intended for extension.
43  *
44  * The %SettingInfo class provides methods to manage the user setting elements. @n
45  * To get the system information, you must provide the <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">SettingInfo key</a>.
46  *
47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">Settings Information</a>.
48  *
49  * The following example demonstrates how to use the %SettingInfo class.
50  *
51  *
52  * @code
53  * #include <FBase.h>
54  * #include <FSystem.h>
55  *
56  * using namespace Tizen::Base;
57  * using namespace Tizen::System;
58  *
59  * result
60  * MyClass::GetSettingInfomation(void)
61  * {
62  *       result r = E_SUCCESS;
63  *
64  *       String key(L"http://tizen.org/setting/location.gps");
65  *       bool gpsEnabled = false;
66  *
67  *       r = SettingInfo::GetValue(key, gpsEnabled);
68  *       TryCatch(r == E_SUCCESS, , "MySettingInfo: To get a value is failed");
69  *
70  *       return E_SUCCESS;
71  *
72  *      CATCH:
73  *       return r;
74  * }
75  * @endcode
76  *
77  */
78 class _OSP_EXPORT_ SettingInfo
79         : public Tizen::Base::Object
80 {
81
82 public:
83         /**
84          * Gets the Tizen::Base::String type setting information for the specified designators (key).
85          *
86          * @since                       2.0
87          *
88          * @return                      An error code
89          * @param[in]           key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information @n
90          * @if OSPCOMPAT
91          *                      The following key values are updated: @n
92          *                      - Since Tizen, refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
93          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer 
94          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
95          * @endif
96          * @param[out]  value                                           The setting information of type Tizen::Base::String
97          * @exception   E_SUCCESS                                       The method is successful.
98          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
99          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
100          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
101          */
102         static result GetValue(const Tizen::Base::String& key, Tizen::Base::String& value);
103
104         /**
105          * Gets the specific integer type setting information for the specified designators (keys).
106          *
107          * @since                       2.0
108          *
109          * @return                      An error code
110          * @param[in]           key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information @n
111          * @if OSPCOMPAT
112          *                      The following key values are updated: @n
113          *                      - Since Tizen, refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
114          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer 
115          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
116          * @endif
117          * @param[out]  value                                           The setting information of type @c int
118          * @exception   E_SUCCESS                                       The method is successful.
119          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
120          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
121          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
122          */
123         static result GetValue(const Tizen::Base::String& key, int& value);
124
125         /**
126          * Gets the @c long @c long type setting information for the specified designators (key).
127          *
128          * @since               2.0
129          *
130          * @return              An error code
131          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
132          * @param[out]  value           The setting information of type @c long @c long
133          * @exception   E_SUCCESS                                       The method is successful.
134          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
135          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
136          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
137          */
138         static result GetValue(const Tizen::Base::String& key, long long& value);
139
140         /**
141          * Gets the double type setting information for the specified designators (key).
142          *
143          * @since               2.0
144          *
145          * @return              An error code
146          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
147          * @param[out]  value           The setting information of type @c double
148          * @exception   E_SUCCESS                                       The method is successful.
149          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
150          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
151          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
152          */
153         static result GetValue(const Tizen::Base::String& key, double& value);
154
155         /**
156          * Gets the @c bool type setting information for the specified designators (key).
157          *
158          * @since               2.0
159          *
160          * @return              An error code
161          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information @n
162          * @if OSPCOMPAT
163          *                      The following key values are updated: @n
164          *                      - Since Tizen, refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
165          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer 
166          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
167          * @endif
168          * @param[out]  value                                           The setting information of type @c bool
169          * @exception   E_SUCCESS                                       The method is successful.
170          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
171          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
172          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
173          */
174         static result GetValue(const Tizen::Base::String& key, bool& value);
175
176         /**
177          * Gets the UuId type setting information for the specified designators (key).
178          *
179          * @since       2.0
180          *
181          * @return              An error code
182          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
183          * @param[out]  value                                           The setting information of type UuId
184          * @exception   E_SUCCESS                                       The method is successful.
185          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
186          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
187          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
188          */
189         static result GetValue(const Tizen::Base::String& key, Tizen::Base::UuId& value);
190
191         /**
192          * Checks whether specific designator(key) is supported.
193          *
194          * @since               2.0
195          *
196          * @return              @c true if the key is supported, @n
197          *                              else @c false
198          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
199          *
200          */
201         static bool HasKey(const Tizen::Base::String& key);
202
203         /**
204          * Sets the specified @c bool type setting information for the specified designators (key).
205          *
206          * @since 2.0
207          *
208          * @privlevel   public
209          * @privilege   %http://tizen.org/privilege/setting
210          *
211          * @return              An error code
212          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
213          * @param[in]   value           The setting information of type @c bool
214          * @exception   E_SUCCESS                                               The method is successful.
215          * @exception   E_PRIVILEGED_DENIED                             The application does not have the privilege to call this method.
216          * @exception   E_INVALID_ARG                                   The specified @c value is invalid.
217          * @exception   E_OBJ_NOT_FOUND                                 The specified @c key is not found.
218          * @exception   E_UNSUPPORTED_OPERATION                 The specified @c key exists. However, it is not supported by this device.
219          * @exception   E_SYSTEM                                                The method cannot proceed due to a severe system error.
220          */
221         static result SetValue(const Tizen::Base::String& key, bool value);
222
223         /**
224          * Sets the specified @c int type setting information for the specified designators (key).
225          *
226          * @since               2.0
227          *
228          * @privlevel   public
229          * @privilege   %http://tizen.org/privilege/setting
230          *
231          * @return              An error code
232          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
233          * @param[in]   value           The setting information of type @c int
234          * @exception   E_SUCCESS                                       The method is successful.
235          * @exception   E_PRIVILEGED_DENIED                     The application does not have the privilege to call this method.
236          * @exception   E_INVALID_ARG                           The specified @c value is invalid.
237          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
238          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
239          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
240          */
241         static result SetValue(const Tizen::Base::String& key, int value);
242
243         /**
244          * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
245          *
246          * @since               2.0
247          *
248          * @privlevel   public
249          * @privilege   %http://tizen.org/privilege/setting
250          *
251          * @return              An error code
252          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
253          * @param[in]   value           The setting information of type Tizen::Base::String
254          * @exception   E_SUCCESS                                       The method is successful.
255          * @exception   E_PRIVILEGED_DENIED                     The application does not have the privilege to call this method.
256          * @exception   E_INVALID_ARG                           The specified @c value is invalid.
257          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
258          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
259          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
260          */
261         static result SetValue(const Tizen::Base::String& key, Tizen::Base::String value);
262
263         /**
264          * Sets the system wallpaper.
265          *
266          * @since       2.0
267          *
268          * @privlevel   public
269          * @privilege   %http://tizen.org/privilege/setting
270          *
271          * @return              An error code
272          * @param[in]   filePath                        The file path of the wallpaper
273          * @exception   E_SUCCESS                       The method is successful.
274          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
275          * @exception   E_FILE_NOT_FOUND        The entry for the specified wallpaper file or the file path cannot be found.
276          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
277          */
278
279         static result SetWallpaper(const Tizen::Base::String& filePath);
280
281         /**
282          * Sets the system ringtone.
283          *
284          * @since       2.0
285          *
286          * @privlevel   public
287          * @privilege   %http://tizen.org/privilege/setting
288          *
289          * @return              An error code
290          * @param[in]   filePath                        The file path of the ringtone
291          * @exception   E_SUCCESS                       The method is successful.
292          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
293          * @exception   E_FILE_NOT_FOUND        The entry for the specified wallpaper file or the file path cannot be found.
294          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
295          */
296         static result SetRingtone(const Tizen::Base::String& filePath);
297
298         /**
299          * Sets the sound volume level.
300          *
301          * @since       2.0
302          *
303          * @privlevel   public
304          * @privilege   %http://tizen.org/privilege/setting
305          *
306          * @return              An error code
307          * @param[in]   soundCategory           The sound volume category
308          * @param[in]   level                           The sound volume level of the designated category
309          * @exception   E_SUCCESS                       The method is successful.
310          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
311          * @exception   E_INVALID_ARG           The specified @c soundCategory is invalid.
312          * @exception   E_OUT_OF_RANGE          The specified @c level is outside the bounds of @c soundCategory.
313          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
314          */
315         static result SetVolume(const Tizen::Base::String& soundCategory, int level);
316
317         /**
318          * Adds the setting event listener. @n
319          * This listener is called when a setting value is changed.
320          *
321          * @since               2.0
322          *
323          * @return              An error code
324          * @param[in]   listener                                The setting event listener
325          * @exception   E_SUCCESS                               The method is successful.
326          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
327          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
328          * @see                 RemoveSettingEventListener()
329          */
330         static result AddSettingEventListener(ISettingEventListener& listener);
331
332         /**
333          * Removes the setting event listener.
334          *
335          * @since               2.0
336          *
337          * @return              An error code
338          * @param[in]   listener                        The setting event listener
339          * @exception   E_SUCCESS                       The method is successful.
340          * @exception   E_OBJ_NOT_FOUND         The listener is not added.
341          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
342          * @see                 AddSettingEventListener()
343          */
344         static result RemoveSettingEventListener(ISettingEventListener& listener);
345
346         /**
347          * Gets the @c bool type setting information for the specified designators (key).
348          *
349          * @since               2.0
350          *
351          * @privlevel   platform
352          * @privilege   %http://tizen.org/privilege/settingmanager.read @n
353          *                              (%http://tizen.org/privilege/systemsetting.read is deprecated.)
354          *
355          * @return              An error code
356          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
357          * @param[out]  value   The setting information of type @c bool
358          * @exception   E_SUCCESS                                       The method is successful.
359          * @exception   E_PRIVILEGED_DENIED                     The application does not have the privilege to call this method.
360          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
361          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However, it is not supported by this device.
362          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
363          */
364         static result GetValueForPrivilegedKey(const Tizen::Base::String& key, bool& value);
365
366         /**
367          * Sets the @c bool type setting information for the specified designators (key).
368          *
369          * @since               2.0
370          *
371          * @privlevel   platform
372          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
373          *                              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
374          *
375          * @return              An error code
376          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
377          * @param[in]   value   The setting information of type @c bool
378          * @exception   E_SUCCESS                               The method is successful.
379          * @exception   E_PRIVILEGED_DENIED             The application does not have the privilege to call this method.
380          * @exception   E_INVALID_ARG                   The specified @c value is invalid value.
381          * @exception   E_OBJ_NOT_FOUND                 The specified @c key is not found.
382          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
383          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
384          */
385         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, bool value);
386
387         /**
388          * Sets the @c bool type setting information for the specified designators (key) asynchronously.
389          *
390          * @since               2.0
391          * @privlevel   platform
392          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
393          *                              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
394          *
395          * @return              An error code
396          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
397          * @param[in]   value           The setting information of type @c bool
398          * @param[in]   listener        The result listener
399          * @exception   E_SUCCESS                               The method is successful.
400          * @exception   E_PRIVILEGED_DENIED             The application does not have the privilege to call this method.
401          * @exception   E_INVALID_ARG                   The specified @c value is invalid.
402          * @exception   E_OBJ_NOT_FOUND                 The specified @c key is not found.
403          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However it is not supported by this device.
404          * @exception   E_IN_PROGRESS                   The specified key is under processing or is in an invalid state.
405          * @exception   E_SYSTEM                                Either of the following conditions has occured:
406          *                                                                              - The method cannot proceed due to a severe system error.
407          *                                                                              - Wi-Fi Directâ„¢ is not activated if the @c key is %http://tizen.org/setting/network.wifi.direct and Wi-Fi is 
408          *                                                                              activated.
409          */
410         static result SetValueAsyncForPrivilegedKey(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
411
412         /**
413          * Sets the @c bool type setting information for the specified designators (key) asynchronously.
414          *
415          * @since               2.0
416          * @privlevel   platform
417          * @privilege   %http://tizen.org/privilege/setting
418          *
419          * @return              An error code
420          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
421          * @param[in]   value           The setting information of type @c bool
422          * @param[in]   listener        The result listener
423          * @exception   E_SUCCESS                                       The method is successful.
424          * @exception   E_PRIVILEGED_DENIED                     The application does not have the privilege to call this method.
425          * @exception   E_INVALID_ARG                           The specified @c value is invalid value.
426          * @exception   E_OBJ_NOT_FOUND                         The specified @c key is not found.
427          * @exception   E_UNSUPPORTED_OPERATION         The specified @c key exists. However it is not supported by this device.
428          * @exception   E_IN_PROGRESS                           The specified key is under processing or is in an invalid state.
429          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
430          */
431         static result SetValueAsync(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
432
433
434         /**
435          * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
436          *
437          * @since 2.0
438          *
439          * @privlevel   platform
440          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
441          *                              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
442          *
443          * @return              An error code
444          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
445          * @param[in]   value           The setting information of type Tizen::Base::String
446          * @exception   E_SUCCESS                               The method is successful.
447          * @exception   E_PRIVILEGED_DENIED             The application does not have the privilege to call this method.
448          * @exception   E_INVALID_ARG                   The specified @c value is invalid.
449          * @exception   E_OBJ_NOT_FOUND                 The specified @c key is not found.
450          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
451          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
452          */
453         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, Tizen::Base::String value);
454
455         /**
456          * Resets the current device to the default factory settings. @n
457          * All data is removed and device is initialized.
458          *
459          * @since               2.0
460          *
461          * @privlevel   platform
462          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
463          *                              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
464          *
465          * @return              An error code
466          * @exception   E_SUCCESS                               The method is successful.
467          * @exception   E_PRIVILEGED_DENIED             The application does not have the privilege to call this method.
468          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
469          */
470         static result ResetToFactoryDefault(void);
471
472         /**
473          * @if OSPCOMPAT
474          * @if OSPDEPREC
475          * Sets the specified setting event listener.
476          *
477          * @deprecated This method is provided only for backward compatibility and will be deleted in the near future. Instead of using this method, it is 
478          * recommended to use AddSettingEventListener() and RemoveSettingEventListener().
479          * @since               2.0
480          *
481          * @return              An error code
482          * @param[in]   pListener       The setting event listener
483          * @exception   E_SUCCESS       The method is successful.
484          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
485          * @remarks             If the value of the listener object (pListener) is @c null, the setting event listener is not called.
486          * @endif
487          * @endif
488          */
489         static result SetSettingEventListener(ISettingEventListener* pListener);
490
491
492 private:
493         /**
494          * This is the default constructor for this class. This default constructor is intentionally
495  declared as private so that only the platform can create an instance.
496          */
497         SettingInfo(void);
498
499         /**
500          * This is the destructor for this class.  This destructor overrides Tizen::Base::Object::~Object().
501          */
502         virtual ~SettingInfo(void);
503
504         /**
505          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
506          */
507         SettingInfo(const SettingInfo& value);
508
509         /**
510          *  The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
511          */
512         SettingInfo& operator =(const SettingInfo& value);
513
514 private:
515         friend class _SettingInfoImpl;
516         class _SettingInfoImpl* __pSettingInfoImpl;
517 }; // SettingInfo
518
519 } } // Tizen::System
520
521 #endif // _FSYS_SETTING_INFO_H_