2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FSysSettingInfo.h
19 * @brief This is the header file for the %SettingInfo class.
21 * This header file contains the declarations of the %SettingInfo class.
24 #ifndef _FSYS_SETTING_INFO_H_
25 #define _FSYS_SETTING_INFO_H_
27 #include <FBaseString.h>
28 #include <FBaseUuId.h>
29 #include <FBaseColIList.h>
30 #include <FSysISettingEventListener.h>
31 #include <FSysISettingInfoSetValueAsyncResultListener.h>
33 namespace Tizen { namespace System
38 * @brief This class provides methods to manage the setting information.
42 * @final This class is not intended for extension.
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>.
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">Settings Information</a>.
49 * The following example demonstrates how to use the %SettingInfo class.
54 * #include <FSystem.h>
56 * using namespace Tizen::Base;
57 * using namespace Tizen::System;
60 * MyClass::GetSettingInfomation(void)
62 * result r = E_SUCCESS;
64 * String key(L"http://tizen.org/setting/location.gps");
65 * bool gpsEnabled = false;
67 * r = SettingInfo::GetValue(key, gpsEnabled);
68 * TryCatch(r == E_SUCCESS, , "MySettingInfo: To get a value is failed");
78 class _OSP_EXPORT_ SettingInfo
79 : public Tizen::Base::Object
84 * Gets the Tizen::Base::String type setting information for the specified designators (key).
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
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>.
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.
102 static result GetValue(const Tizen::Base::String& key, Tizen::Base::String& value);
105 * Gets the specific integer type setting information for the specified designators (keys).
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
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>.
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.
123 static result GetValue(const Tizen::Base::String& key, int& value);
126 * Gets the @c long @c long type setting information for the specified designators (key).
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.
138 static result GetValue(const Tizen::Base::String& key, long long& value);
141 * Gets the double type setting information for the specified designators (key).
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.
153 static result GetValue(const Tizen::Base::String& key, double& value);
156 * Gets the @c bool type setting information for the specified designators (key).
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
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>.
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.
174 static result GetValue(const Tizen::Base::String& key, bool& value);
177 * Gets the UuId type setting information for the specified designators (key).
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.
189 static result GetValue(const Tizen::Base::String& key, Tizen::Base::UuId& value);
192 * Checks whether specific designator(key) is supported.
196 * @return @c true if the key is supported, @n
198 * @param[in] key The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
201 static bool HasKey(const Tizen::Base::String& key);
204 * Sets the specified @c bool type setting information for the specified designators (key).
209 * @privilege %http://tizen.org/privilege/setting
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.
221 static result SetValue(const Tizen::Base::String& key, bool value);
224 * Sets the specified @c int type setting information for the specified designators (key).
229 * @privilege %http://tizen.org/privilege/setting
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.
241 static result SetValue(const Tizen::Base::String& key, int value);
244 * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
249 * @privilege %http://tizen.org/privilege/setting
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.
261 static result SetValue(const Tizen::Base::String& key, Tizen::Base::String value);
264 * Sets the system wallpaper.
269 * @privilege %http://tizen.org/privilege/setting
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.
279 static result SetWallpaper(const Tizen::Base::String& filePath);
282 * Sets the system ringtone.
287 * @privilege %http://tizen.org/privilege/setting
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.
296 static result SetRingtone(const Tizen::Base::String& filePath);
299 * Sets the sound volume level.
304 * @privilege %http://tizen.org/privilege/setting
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.
315 static result SetVolume(const Tizen::Base::String& soundCategory, int level);
318 * Adds the setting event listener. @n
319 * This listener is called when a setting value is changed.
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()
330 static result AddSettingEventListener(ISettingEventListener& listener);
333 * Removes the setting event listener.
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()
344 static result RemoveSettingEventListener(ISettingEventListener& listener);
347 * Gets the @c bool type setting information for the specified designators (key).
351 * @privlevel platform
352 * @privilege %http://tizen.org/privilege/settingmanager.read @n
353 * (%http://tizen.org/privilege/systemsetting.read is deprecated.)
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.
364 static result GetValueForPrivilegedKey(const Tizen::Base::String& key, bool& value);
367 * Sets the @c bool type setting information for the specified designators (key).
371 * @privlevel platform
372 * @privilege %http://tizen.org/privilege/settingmanager.write @n
373 * (%http://tizen.org/privilege/systemsetting.write is deprecated.)
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.
385 static result SetValueForPrivilegedKey(const Tizen::Base::String& key, bool value);
388 * Sets the @c bool type setting information for the specified designators (key) asynchronously.
391 * @privlevel platform
392 * @privilege %http://tizen.org/privilege/settingmanager.write @n
393 * (%http://tizen.org/privilege/systemsetting.write is deprecated.)
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
410 static result SetValueAsyncForPrivilegedKey(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
413 * Sets the @c bool type setting information for the specified designators (key) asynchronously.
416 * @privlevel platform
417 * @privilege %http://tizen.org/privilege/setting
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.
431 static result SetValueAsync(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
435 * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
439 * @privlevel platform
440 * @privilege %http://tizen.org/privilege/settingmanager.write @n
441 * (%http://tizen.org/privilege/systemsetting.write is deprecated.)
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.
453 static result SetValueForPrivilegedKey(const Tizen::Base::String& key, Tizen::Base::String value);
456 * Resets the current device to the default factory settings. @n
457 * All data is removed and device is initialized.
461 * @privlevel platform
462 * @privilege %http://tizen.org/privilege/settingmanager.write @n
463 * (%http://tizen.org/privilege/systemsetting.write is deprecated.)
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.
470 static result ResetToFactoryDefault(void);
475 * Sets the specified setting event listener.
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().
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.
489 static result SetSettingEventListener(ISettingEventListener* pListener);
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.
500 * This is the destructor for this class. This destructor overrides Tizen::Base::Object::~Object().
502 virtual ~SettingInfo(void);
505 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
507 SettingInfo(const SettingInfo& value);
510 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
512 SettingInfo& operator =(const SettingInfo& value);
515 friend class _SettingInfoImpl;
516 class _SettingInfoImpl* __pSettingInfoImpl;
521 #endif // _FSYS_SETTING_INFO_H_