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