inc/FAppAppSetting.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        FAppAppSetting.h
  20  * @brief       This is the header file for the %AppSetting class.
  21  *
  22  * This header file contains the declarations of the %AppSetting class.
  23  */
  24
  25 #ifndef _FAPP_APP_SETTING_H_
  26 #define _FAPP_APP_SETTING_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FBaseObject.h>
  31 #include <FAppTypes.h>
  32
  33
  34 namespace Tizen { namespace Base { namespace Collection
  35 {
  36 class IList;
  37 }}}
  38
  39
  40 namespace Tizen { namespace App
  41 {
  42
  43 class IAppSettingEventListener;
  44
  45 /**
  46  * @class       AppSetting
  47  * @brief       This class manages an application's settings.
  48  *
  49  * @since       2.0
  50  *
  51  * @final       This class is not intended for extension.
  52  *
  53  * The %AppSetting class lets an application to save or restore its settings.
  54  *
  55  *
  56  * The following example demonstrates how to use the %AppSetting class.
  57  *
  58  * @code
  59  *      void
  60  *      AppSettingForm::RefreshSetting(void)
  61  *      {
  62  *              AppSetting* pAppSetting = AppSetting::GetInstance();
  63  *              AppAssert(pAppSetting);
  64  *
  65  *              bool valueBool = false;
  66  *              int valueInt = 0;
  67  *              const String strLn(L"\n");
  68  *              String valueString;
  69  *              String settingText;
  70  *
  71  *              AppAssert(pAppSetting->GetValue(L"checkbox1", valueBool) == E_SUCCESS);
  72  *              settingText += L"checkbox1: ";
  73  *              settingText += strFalseTrue[valueBool ? 1 : 0];
  74  *              settingText += strLn;
  75  *
  76  *              AppAssert(pAppSetting->GetValue(L"slider1", valueInt) == E_SUCCESS);
  77  *              settingText += L"slider1: ";
  78  *              settingText += Integer(valueInt).ToString();
  79  *              settingText += strLn;
  80  *
  81  *              AppAssert(pAppSetting->GetValue(L"editbox1", valueString) == E_SUCCESS);
  82  *              settingText += L"editbox1: ";
  83  *              settingText += valueString;
  84  *              settingText += strLn;
  85  *              // . . .
  86  *      }
  87  *
  88  *      void
  89  *      AppSettingForm::SetSettingValueSet1(void)
  90  *      {
  91  *              AppSetting* pAppSetting = AppSetting::GetInstance();
  92  *              AppAssert(pAppSetting);
  93  *
  94  *              AppAssert(pAppSetting->SetValue(L"checkbox1", false) == E_SUCCESS);
  95  *              AppAssert(pAppSetting->SetValue(L"slider1", 100) == E_SUCCESS);
  96  *              AppAssert(pAppSetting->SetValue(L"editbox1", String(L"AppSetting working!")) == E_SUCCESS);
  97  *              AppAssert(pAppSetting->SetValue(L"expanditem1", String(L"1 minute")) == E_SUCCESS);
  98  *              AppAssert(pAppSetting->SetValue(L"expanditem1", false) == E_SUCCESS);
  99  *              AppAssert(pAppSetting->SetValue(L"slider2", 0) == E_SUCCESS);
 100  *              AppAssert(pAppSetting->SetValue(L"editbox2", String(L"AppSetting running!")) == E_SUCCESS);
 101  *              // . . .
 102  *      }
 103  * @endcode
 104  *
 105  */
 106 class _OSP_EXPORT_ AppSetting
 107         : public Tizen::Base::Object
 108 {
 109 public:
 110         /**
 111          * Gets the application setting instance.
 112          *
 113          * @since       2.0
 114          *
 115          * @return              A pointer to the %AppSetting instance, @n
 116          *                              else @c null if it fails
 117          * @exception   E_SUCCESS                       The method is successful.
 118          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 119          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 120          * @remarks             It returns an instance for the latest setting. @n
 121          *                              The specific error code can be accessed using the GetLastResult() method.
 122          */
 123         static AppSetting* GetInstance(void);
 124
 125         /**
 126          * Gets the application setting instance of the specified version.
 127          *
 128          * @since       2.0
 129          *
 130          * @return              A pointer to the %AppSetting instance, @n
 131          *                              else @c null if it fails
 132          * @param[in]   settingVersion          The version of setting is retrieved from GetAppSettingVersionListN()
 133          * @exception   E_SUCCESS                       The method is successful.
 134          * @exception   E_OBJ_NOT_FOUND         The specified version is not found.
 135          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 136          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 137          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 138          * @see                 GetAppSettingVersionListN()
 139          */
 140         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
 141
 142         /**
 143          * @if VISPARTNER
 144          * Gets the application setting instance of the specified AppId.
 145          *
 146          * @since       2.0
 147          *
 148          * @visibility  partner
 149          * @privilege   %http://tizen.org/privilege/appsetting
 150          *
 151          * @return              A pointer to the %AppSetting instance, @n
 152          *                              else @c null if it fails
 153          * @param[in]   appId                           The AppId of the application that has a valid application setting
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
 156          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 157          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 158          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
 159          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 160          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 161          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 162          * @see                 ReleaseInstanceByAppId()
 163          * @endif
 164          */
 165         static AppSetting* GetInstanceByAppId(const AppId& appId);
 166
 167         /**
 168          * @if VISPARTNER
 169          * Releases the specified application setting instance.
 170          *
 171          * @since       2.0
 172          *
 173          * @visibility  partner
 174          * @privilege   %http://tizen.org/privilege/appsetting
 175          *
 176          * @return              An error code
 177          * @param[in]   appId                           The AppId of the application that has a valid application setting
 178          * @exception   E_SUCCESS                       The method is successful.
 179          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
 180          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 181          * @remarks             Individual instances are managed by the platform. @n
 182          *                              It is recommended to release instances to reduce memory usage.
 183          * @see                 GetInstanceByAppId()
 184          * @endif
 185          */
 186         static result ReleaseInstanceByAppId(const AppId& appId);
 187
 188         /**
 189          * Gets a list of all the versions that existed prior to the current version. @n
 190          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
 191          *
 192          * @since       2.0
 193          *
 194          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list
 195          * @exception   E_SUCCESS                       The method is successful.
 196          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 197          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 198          * @remarks             The latest version string is located in the first position.
 199          *                              If the old version does not exist then return empty collection. @n
 200          *                              The specific error code can be accessed using the GetLastResult() method.
 201          */
 202         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
 203
 204         /**
 205          * Gets a @c bool value associated with the specified @c id.
 206          *
 207          * @since       2.0
 208          *
 209          * @return              An error code
 210          * @param[in]   id                                      The ID of the value to retrieve
 211          * @param[out]  value                           A boolean value to retrieve
 212          * @exception   E_SUCCESS                       The method is successful.
 213          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 214          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 215          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 216          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 217          */
 218         result GetValue(const Tizen::Base::String& id, bool& value) const;
 219
 220         /**
 221          * Gets an integer value associated with the specified @c id.
 222          *
 223          * @since       2.0
 224          *
 225          * @return              An error code
 226          * @param[in]   id                                      The ID of the value to retrieve
 227          * @param[out]  value                           An integer value to retrieve
 228          * @exception   E_SUCCESS                       The method is successful.
 229          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 230          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 231          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 232          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 233          */
 234         result GetValue(const Tizen::Base::String& id, int& value) const;
 235
 236         /**
 237          * Gets a string value associated with the specified @c id.
 238          *
 239          * @since       2.0
 240          *
 241          * @return              An error code
 242          * @param[in]   id                                      The id of the value to retrieve
 243          * @param[out]  value                           A string value to retrieve
 244          * @exception   E_SUCCESS                       The method is successful.
 245          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 246          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 247          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 248          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 249          */
 250         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
 251
 252         /**
 253          * Sets a @c bool value associated with the specified @c id.
 254          *
 255          * @since       2.0
 256          *
 257          * @return              An error code
 258          * @param[in]   id                                      The ID of the value to modify
 259          * @param[in]   value                           A boolean value
 260          * @exception   E_SUCCESS                       The method is successful.
 261          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 262          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 263          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 264          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 265          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 266          */
 267         result SetValue(const Tizen::Base::String& id, bool value);
 268
 269         /**
 270          * Sets an integer value associated with the specified @c id.
 271          *
 272          * @since       2.0
 273          *
 274          * @return              An error code
 275          * @param[in]   id                                      The ID of the value to modify
 276          * @param[in]   value                           An integer value
 277          * @exception   E_SUCCESS                       The method is successful.
 278          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 279          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 280          * @exception   E_OUT_OF_RANGE          The specified @c value is out of range.
 281          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 282          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 283          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 284          */
 285         result SetValue(const Tizen::Base::String& id, int value);
 286
 287         /**
 288          * Sets a string value associated with the specified @c id.
 289          *
 290          * @since       2.0
 291          *
 292          * @return              An error code
 293          * @param[in]   id                                      The ID of the value to modify
 294          * @param[in]   value                           A string value
 295          * @exception   E_SUCCESS                       The method is successful.
 296          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 297          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 298          * @exception   E_OUT_OF_RANGE          The specified string length is out of range.
 299          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 300          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 301          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 302          */
 303         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
 304
 305         /**
 306          * Sets a setting event listener.
 307          *
 308          * @since       2.0
 309          *
 310          * @return              An error code
 311          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
 312          *                                  else @c null to clear a previous one
 313          * @exception   E_SUCCESS                       The method is successful.
 314          */
 315         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
 316
 317 private:
 318         /**
 319          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 320          *
 321          * @since       2.0
 322          */
 323         AppSetting(void);
 324
 325         /**
 326          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 327          *
 328          * @since       2.0
 329          */
 330         AppSetting(const AppSetting& rhs);
 331
 332         /**
 333          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 334          *
 335          * @since       2.0
 336          */
 337         AppSetting& operator =(const AppSetting& rhs);
 338
 339         /**
 340          * This destructor is intentionally declared as private to implement the Singleton semantic.
 341          *
 342          * @since       2.0
 343          */
 344         virtual ~AppSetting(void);
 345
 346         static void InitSingleton(void);
 347         static void DestroySingleton(void);
 348
 349 private:
 350         friend class _AppSettingImpl;
 351         class _AppSettingImpl* __pAppSettingImpl;
 352         static AppSetting* __pAppSettingInstance;
 353
 354 }; // AppSetting
 355 } } // Tizen::App
 356
 357 #endif // _FAPP_APP_SETTING_H_