inc/FAppAppSetting.h

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