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_