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