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          *                      - @b Since: @b 2.0 Refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
  94          *                        @xmlonly <pcheck kind="value" since="2.0">locale.country, locale.time.format, locale.date.format, locale.datetime.format, font.type, locale.language, theme, sound.ringtone, screen.wallpaper, screen.wallpaper.lock, usbmode</pcheck> @endxmlonly
  95          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer
  96          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
  97          * @endif
  98          * @param[out]  value           The setting information of type Tizen::Base::String
  99          * @exception   E_SUCCESS       The method is successful.
 100          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 101          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 102          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 103          */
 104         static result GetValue(const Tizen::Base::String& key, Tizen::Base::String& value);
 105
 106         /**
 107          * Gets the specific integer type setting information based on the specified
 108          * designators (keys).
 109          *
 110          * @since       2.0
 111          *
 112          * @return      An error code
 113          * @param[in]   key     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information @n
 114          * @if OSPCOMPAT
 115          *                      The following key values are updated: @n
 116          *                      - @b Since: @b 2.0 Refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
 117          *                        @xmlonly <pcheck kind="value" since="2.0">font.size, sound.media.volume, sound.notification.volume, sound.ringtone.volume, sound.system.volume, vibrator.level </pcheck> @endxmlonly
 118          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer
 119          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
 120          * @endif
 121          * @param[out]  value           The setting information of type integer
 122          * @exception   E_SUCCESS       The method is successful.
 123          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 124          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 125          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 126          */
 127         static result GetValue(const Tizen::Base::String& key, int& value);
 128
 129         /**
 130          * Gets the specific @c long @c long type setting information based on the specified
 131          * designators (key).
 132          *
 133          * @since       2.0
 134          *
 135          * @return      An error code
 136          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 137          * @param[out]  value           The setting information of type @c long @c long
 138          * @exception   E_SUCCESS       The method is successful.
 139          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 140          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 141          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 142          */
 143         static result GetValue(const Tizen::Base::String& key, long long& value);
 144
 145         /**
 146          * Gets the specific double type setting information based on the specified
 147          * designators (key).
 148          *
 149          * @since       2.0
 150          *
 151          * @return      An error code
 152          * @param[in]   key             The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 153          * @param[out]  value           The setting information of type double
 154          * @exception   E_SUCCESS       The method is successful.
 155          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 156          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 157          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 158          */
 159         static result GetValue(const Tizen::Base::String& key, double& value);
 160
 161         /**
 162          * Gets the specific @c bool type setting information based on the specified
 163          * designators (key).
 164          *
 165          * @since       2.0
 166          *
 167          * @return      An error code
 168          * @param[in]   key     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information @n
 169          * @if OSPCOMPAT
 170          *                      The following key values are updated: @n
 171          *                      - @b Since: @b 2.0 Refer <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">here</a>.
 172          *                        @xmlonly <pcheck kind="value" since="2.0">network.roaming, network.flightmode, network.packetservice, locale.time.format.24hour, location.gps, location.wps, sound.silentmode, motion </pcheck> @endxmlonly
 173          *                      - @b Deprecated All the key values provided prior to %Tizen 2.0 are deprecated. For more detailed information, refer
 174          *                       <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info_deprecated.htm">here</a>.
 175          * @endif
 176          * @param[out]  value           The setting information of type bool
 177          * @exception   E_SUCCESS       The method is successful.
 178          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 179          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 180          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 181          */
 182         static result GetValue(const Tizen::Base::String& key, bool& value);
 183
 184         /**
 185          * Gets the specific UuId type setting information based on the specified
 186          * designators (key).
 187          *
 188          * @since       2.0
 189          *
 190          * @return      An error code
 191          * @param[in]   key     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 192          * @param[out]  value           The setting information of type UuId
 193          * @exception   E_SUCCESS       The method is successful.
 194          * @exception   E_OBJ_NOT_FOUND The specified @c key is not found.
 195          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 196          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 197          */
 198         static result GetValue(const Tizen::Base::String& key, Tizen::Base::UuId& value);
 199
 200         /**
 201          * Checks whether specific designator(key) is supported or not.
 202          *
 203          * @since 2.0
 204          *
 205          * @return @c true if the key is supported, @n
 206          *      else @c false
 207          * @param[in]   key The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 208          *
 209          */
 210         static bool HasKey(const Tizen::Base::String& key);
 211
 212         /**
 213          * Sets the specific @c bool type setting information based on the specified designators (key).
 214          *
 215          * @since 2.0
 216          *
 217          * @privilege   %http://tizen.org/privilege/setting
 218          *
 219          * @return      An error code
 220          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 221          * @param[in]   value                   The setting information of type bool
 222          * @exception   E_SUCCESS               The method is successful.
 223          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
 224          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
 225          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
 226          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 227          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 228          */
 229         static result SetValue(const Tizen::Base::String& key, bool value);
 230
 231         /**
 232          * Sets the specific @c int type setting information based on the specified designators (key).
 233          *
 234          * @since 2.0
 235          *
 236          * @privilege   %http://tizen.org/privilege/setting
 237          *
 238          * @return      An error code
 239          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 240          * @param[in]   value                   The setting information of type int
 241          * @exception   E_SUCCESS               The method is successful.
 242          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
 243          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
 244          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
 245          * @exception   E_UNSUPPORTED_OPERATION The specified @c key exists. However, it is not supported by this device.
 246          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 247          */
 248         static result SetValue(const Tizen::Base::String& key, int value);
 249
 250         /**
 251          * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
 252          *
 253          * @since 2.0
 254          *
 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   %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          * @remarks     The specified wallpaper file is copied to the managed folder by the system, while the previously set wallpaper is removed. <br> This parameter is compatible with "Wallpaper".
 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   %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          * @remarks     The specified ringtone file has to exist in the media directory.
 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   %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          * @if  VISPARTNER-MANUFACTURER
 353          * Gets the specific @c bool type setting information based on the specified designators (key).
 354          *
 355          * @since 2.0
 356          *
 357          * @visibility  partner-manufacturer
 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          * @endif
 369          */
 370         static result GetValueForPrivilegedKey(const Tizen::Base::String& key, bool& value);
 371
 372         /**
 373          * @if  VISPARTNER-MANUFACTURER
 374          * Sets the specific @c bool type setting information based on the specified designators (key).
 375          *
 376          * @since 2.0
 377          *
 378          * @visibility  partner-manufacturer
 379          * @privilege   %http://tizen.org/privilege/systemsetting.write
 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          * @endif
 391          */
 392         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, bool value);
 393
 394         /**
 395          * @if  VISPARTNER-MANUFACTURER
 396          * Sets the specific @c bool type setting information based on the specified designators (key) asynchronously.
 397          *
 398          * @since 2.0
 399          * @visibility  partner-manufacturer
 400          * @privilege   %http://tizen.org/privilege/systemsetting.write
 401          *
 402          * @return      An error code
 403          * @param[in]   key                     The <a href="../org.tizen.native.appprogramming/html/guide/system/settings_info.htm">key name</a> of the setting information
 404          * @param[in]   value                   The setting information of type bool
 405          * @param[in]   listener                The result listener.
 406          * @exception   E_SUCCESS               The method is successful.
 407          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
 408          * @exception   E_INVALID_ARG           The specified @c value is invalid value.
 409          * @exception   E_OBJ_NOT_FOUND         The specified @c key is not found.
 410          * @exception   E_UNSUPPORTED_OPERATION The specified @c key is existed, However it is not supported by this device.
 411          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 412          * @remarks The listener instance ownership is transferred to platform. After notifying result, listener instance is removed automatically. A reuse of the listener instance is not allowed.
 413          * @endif
 414          */
 415         static result SetValueAsyncForPrivilegedKey(const Tizen::Base::String& key, bool value, ISettingInfoSetValueAsyncResultListener* listener);
 416
 417         /**
 418          * @if  VISPARTNER-MANUFACTURER
 419          * Sets the specific Tizen::Base::String type setting information based on the specified designators (key).
 420          *
 421          * @since 2.0
 422          *
 423          * @visibility  partner-manufacturer
 424          * @privilege   %http://tizen.org/privilege/systemsetting.write
 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 Tizen::Base::String
 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 exists. However, it is not supported by this device.
 434          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 435          * @endif
 436          */
 437         static result SetValueForPrivilegedKey(const Tizen::Base::String& key, Tizen::Base::String value);
 438
 439         /**
 440          * @if  VISPARTNER-MANUFACTURER
 441          * Resets current device. @n
 442          * All data is removed and device is initialized.
 443          *
 444          * @since 2.0
 445          *
 446          * @visibility  partner-manufacturer
 447          * @privilege   %http://tizen.org/privilege/systemsetting.write
 448          *
 449          * @return      An error code
 450          * @exception   E_SUCCESS               The method is successful.
 451          * @exception   E_PRIVILEGED_DENIED     The application does not have the privilege to call this method.
 452          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 453          * @endif
 454          */
 455         static result ResetToFactoryDefault(void);
 456
 457         /**
 458          * @if OSPCOMPAT
 459          * @if OSPDEPREC
 460          * Sets the setting event listener.
 461          *
 462          * @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().
 463          * @since       2.0
 464          *
 465          * @return      An error code
 466          * @param[in]   pListener       The setting event listener
 467          * @exception   E_SUCCESS       The method is successful.
 468          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 469          * @remarks     If the value of the listener object (pListener) is @c null, the setting event listener is not called.
 470          * @endif
 471          * @endif
 472          */
 473         static result SetSettingEventListener(ISettingEventListener* pListener);
 474
 475
 476 private:
 477         /**
 478          * This is the default constructor for this class. This default constructor is intentionally
 479  declared as private so that only the platform can create an instance.
 480          */
 481         SettingInfo(void);
 482
 483         /**
 484          * This is the destructor for this class.  This destructor overrides Tizen::Base::Object::~Object().
 485          */
 486         virtual ~SettingInfo(void);
 487
 488         /**
 489          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 490          */
 491         SettingInfo(const SettingInfo& value);
 492
 493         /**
 494          *  The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 495          */
 496         SettingInfo& operator =(const SettingInfo& value);
 497
 498 private:
 499         friend class _SettingInfoImpl;
 500         class _SettingInfoImpl* __pSettingInfoImpl;
 501 }; // SettingInfo
 502
 503 } } // Tizen::System
 504
 505 #endif // _FSYS_SETTING_INFO_H_