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          * Gets the application setting instance of the specified AppId.
 144          *
 145          * @since       2.0
 146          *
 147          * @privlevel   partner
 148          * @privilege   http://tizen.org/privilege/appsetting
 149          *
 150          * @return              A pointer to the %AppSetting instance, @n
 151          *                              else @c null if it fails
 152          * @param[in]   appId                           The AppId of the application that has a valid application setting
 153          * @exception   E_SUCCESS                       The method is successful.
 154          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
 155          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 156          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 157          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
 158          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 159          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 160          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 161          * @see                 ReleaseInstanceByAppId()
 162          */
 163         static AppSetting* GetInstanceByAppId(const AppId& appId);
 164
 165         /**
 166          * Releases the specified application setting instance.
 167          *
 168          * @since       2.0
 169          *
 170          * @privlevel   partner
 171          * @privilege   http://tizen.org/privilege/appsetting
 172          *
 173          * @return              An error code
 174          * @param[in]   appId                           The AppId of the application that has a valid application setting
 175          * @exception   E_SUCCESS                       The method is successful.
 176          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
 177          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 178          * @remarks             Individual instances are managed by the platform. @n
 179          *                              It is recommended to release instances to reduce memory usage.
 180          * @see                 GetInstanceByAppId()
 181          */
 182         static result ReleaseInstanceByAppId(const AppId& appId);
 183
 184         /**
 185          * Gets a list of all the versions that existed prior to the current version. @n
 186          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
 187          *
 188          * @since       2.0
 189          *
 190          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list
 191          * @exception   E_SUCCESS                       The method is successful.
 192          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 193          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 194          * @remarks             The latest version string is located in the first position.
 195          *                              If the old version does not exist then return empty collection. @n
 196          *                              The specific error code can be accessed using the GetLastResult() method.
 197          */
 198         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
 199
 200         /**
 201          * Gets a @c bool value associated with the specified @c id.
 202          *
 203          * @since       2.0
 204          *
 205          * @return              An error code
 206          * @param[in]   id                                      The ID of the value to retrieve
 207          * @param[out]  value                           A boolean value to retrieve
 208          * @exception   E_SUCCESS                       The method is successful.
 209          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 210          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 211          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 212          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 213          */
 214         result GetValue(const Tizen::Base::String& id, bool& value) const;
 215
 216         /**
 217          * Gets an integer value associated with the specified @c id.
 218          *
 219          * @since       2.0
 220          *
 221          * @return              An error code
 222          * @param[in]   id                                      The ID of the value to retrieve
 223          * @param[out]  value                           An integer value to retrieve
 224          * @exception   E_SUCCESS                       The method is successful.
 225          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 226          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 227          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 228          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 229          */
 230         result GetValue(const Tizen::Base::String& id, int& value) const;
 231
 232         /**
 233          * Gets a string value associated with the specified @c id.
 234          *
 235          * @since       2.0
 236          *
 237          * @return              An error code
 238          * @param[in]   id                                      The id of the value to retrieve
 239          * @param[out]  value                           A string value to retrieve
 240          * @exception   E_SUCCESS                       The method is successful.
 241          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 242          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 243          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 244          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 245          */
 246         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
 247
 248         /**
 249          * Sets a @c bool value associated with the specified @c id.
 250          *
 251          * @since       2.0
 252          *
 253          * @return              An error code
 254          * @param[in]   id                                      The ID of the value to modify
 255          * @param[in]   value                           A boolean value
 256          * @exception   E_SUCCESS                       The method is successful.
 257          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 258          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 259          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 260          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 261          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 262          */
 263         result SetValue(const Tizen::Base::String& id, bool value);
 264
 265         /**
 266          * Sets an integer value associated with the specified @c id.
 267          *
 268          * @since       2.0
 269          *
 270          * @return              An error code
 271          * @param[in]   id                                      The ID of the value to modify
 272          * @param[in]   value                           An integer value
 273          * @exception   E_SUCCESS                       The method is successful.
 274          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 275          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 276          * @exception   E_OUT_OF_RANGE          The specified @c value is out of range.
 277          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 278          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 279          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 280          */
 281         result SetValue(const Tizen::Base::String& id, int value);
 282
 283         /**
 284          * Sets a string value associated with the specified @c id.
 285          *
 286          * @since       2.0
 287          *
 288          * @return              An error code
 289          * @param[in]   id                                      The ID of the value to modify
 290          * @param[in]   value                           A string value
 291          * @exception   E_SUCCESS                       The method is successful.
 292          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 293          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 294          * @exception   E_OUT_OF_RANGE          The specified string length is out of range.
 295          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 296          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 297          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 298          */
 299         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
 300
 301         /**
 302          * Sets a setting event listener.
 303          *
 304          * @since       2.0
 305          *
 306          * @return              An error code
 307          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
 308          *                                  else @c null to clear a previous one
 309          * @exception   E_SUCCESS                       The method is successful.
 310          */
 311         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
 312
 313 private:
 314         /**
 315          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 316          *
 317          * @since       2.0
 318          */
 319         AppSetting(void);
 320
 321         /**
 322          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 323          *
 324          * @since       2.0
 325          */
 326         AppSetting(const AppSetting& rhs);
 327
 328         /**
 329          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 330          *
 331          * @since       2.0
 332          */
 333         AppSetting& operator =(const AppSetting& rhs);
 334
 335         /**
 336          * This destructor is intentionally declared as private to implement the Singleton semantic.
 337          *
 338          * @since       2.0
 339          */
 340         virtual ~AppSetting(void);
 341
 342         static void InitSingleton(void);
 343         static void DestroySingleton(void);
 344
 345 private:
 346         friend class _AppSettingImpl;
 347         class _AppSettingImpl* __pAppSettingImpl;
 348         static AppSetting* __pAppSettingInstance;
 349
 350 }; // AppSetting
 351 } } // Tizen::App
 352
 353 #endif // _FAPP_APP_SETTING_H_