Update reviewed Tizen::Io doxygen
[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          * @privlevel   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          * @privlevel   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          * @privlevel   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          * @privlevel   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          * @privlevel   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          * @privlevel   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/settingmanager.read @n
359          *              (%http://tizen.org/privilege/systemsetting.read is deprecated.)
360          *
361          * @return      An error code
362          * @param[in]   key     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
363          * @param[out]  value                   The setting information of type bool
364          * @exception   E_SUCCESS               The method is successful.
365          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
366          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
367          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
368          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
369          */
370         static result GetValueForPrivilegedKey(const Tizen::Base::String& key, bool& value);
371
372         /**
373          * Sets the specific @c bool type setting information based on the specified designators (key).
374          *
375          * @since 2.0
376          *
377          * @privlevel   platform
378          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
379          *              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
380          *
381          * @return      An error code
382          * @param[in]   key     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
383          * @param[in]   value                   The setting information of type bool
384          * @exception   E_SUCCESS               The method is successful.
385          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
386          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
387          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
388          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
389          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
390          */
391         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, bool value);
392
393         /**
394          * Sets the specific @c bool type setting information based on the specified designators (key) asynchronously.
395          *
396          * @since 2.0
397          * @privlevel   platform
398          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
399          *              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
400          *
401          * @return      An error code
402          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
403          * @param[in]   value                   The setting information of type bool
404          * @param[in]   listener                The result listener.
405          * @exception   E_SUCCESS               The method is successful.
406          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
407          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
408          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
409          * @exception   E_UNSUPPORTED_OPERATION The specified @c key is existed, However it is not supported by this device.
410          * @exception   E_IN_PROGRESS           The specified key is under processing or invalid state.
411          * @exception   E_SYSTEM                Either of the following conditions has occured:
412          *                                      - The method cannot proceed due to a severe system error.
413          *                                      - This error can occur and Wi-Fi Directâ„¢ is not activated if the @c key is %http://tizen.org/setting/network.wifi.direct and Wi-Fi is activated.-
414 Directâ„¢ is not activated if the @c key is %http://tizen.org/setting/network.wifi.direct and Wi-Fi is activated.
415
416          */
417         static result SetValueAsyncForPrivilegedKey(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
418
419         /**
420          * Sets the specific @c bool type setting information based on the specified designators (key) asynchronously.
421          *
422          * @since 2.0
423          * @privlevel   platform
424          * @privilege   %http://tizen.org/privilege/setting
425          *
426          * @return      An error code
427          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
428          * @param[in]   value                   The setting information of type bool
429          * @param[in]   listener                The result listener.
430          * @exception   E_SUCCESS               The method is successful.
431          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
432          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
433          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
434          * @exception   E_UNSUPPORTED_OPERATION The specified @c key is existed, However it is not supported by this device.
435          * @exception   E_IN_PROGRESS           The specified key is under processing or invalid state.
436          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
437          */
438         static result SetValueAsync(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
439
440
441         /**
442          * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
443          *
444          * @since 2.0
445          *
446          * @privlevel   platform
447          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
448          *              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
449          *
450          * @return      An error code
451          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
452          * @param[in]   value                   The setting information of type Tizen::Base::String
453          * @exception   E_SUCCESS               The method is successful.
454          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
455          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
456          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
457          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
458          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
459          */
460         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, Tizen::Base::String value);
461
462         /**
463          * Resets current device. @n
464          * All data is removed and device is initialized.
465          *
466          * @since 2.0
467          *
468          * @privlevel   platform
469          * @privilege   %http://tizen.org/privilege/settingmanager.write @n
470          *              (%http://tizen.org/privilege/systemsetting.write is deprecated.)
471          *
472          * @return      An error code
473          * @exception   E_SUCCESS               The method is successful.
474          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
475          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
476          */
477         static result ResetToFactoryDefault(void);
478
479         /**
480          * @if OSPCOMPAT
481          * @if OSPDEPREC
482          * Sets the setting event listener.
483          *
484          * @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().
485          * @since       2.0
486          *
487          * @return      An error code
488          * @param[in]   pListener       The setting event listener
489          * @exception   E_SUCCESS       The method is successful.
490          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
491          * @remarks     If the value of the listener object (pListener) is @c null, the setting event listener is not called.
492          * @endif
493          * @endif
494          */
495         static result SetSettingEventListener(ISettingEventListener* pListener);
496
497
498 private:
499         /**
500          * This is the default constructor for this class. This default constructor is intentionally
501  declared as private so that only the platform can create an instance.
502          */
503         SettingInfo(void);
504
505         /**
506          * This is the destructor for this class.  This destructor overrides Tizen::Base::Object::~Object().
507          */
508         virtual ~SettingInfo(void);
509
510         /**
511          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
512          */
513         SettingInfo(const SettingInfo& value);
514
515         /**
516          *  The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
517          */
518         SettingInfo& operator =(const SettingInfo& value);
519
520 private:
521         friend class _SettingInfoImpl;
522         class _SettingInfoImpl* __pSettingInfoImpl;
523 }; // SettingInfo
524
525 } } // Tizen::System
526
527 #endif // _FSYS_SETTING_INFO_H_