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 is a helper class for an application to save or restore its settings.
  53  * A setting entity is composed of a string-typed key and a value. The value type must be only of these three types: @c int, @c bool, and @c String.
  54  * The settings are pre-defined in setting/setting.xml in the application's base directory
  55  * and they can be easily set with Tizen IDE (<a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/creating_running_app_setting.htm">Creating and Using Application Settings</a>, <a href="../org.tizen.native.appprogramming/html/ide_sdk_tools/application_settings_editor.htm">Application Settings Editor</a>).
  56  * (The setting.xml is a symbolic link to the currently used setting file, which is related to the current version of the application.) @n
  57  * The %AppSetting class is basically used for specific applications such as IME, which have no UI.
  58  * Because the applications have no external way to modify their settings, users can adjust the setting values through the setting application, which is delegated to manage the settings.
  59  * For supporting the consistency of setting values between two applications, the target application and the setting application, when setting a value in the setting application, the target application is notified from the setting application through OnAppSettingChanged()(see IAppSettingEventListener).
  60  * For detailed example on this class, see <a href="../org.tizen.native.appprogramming/html/tutorials/app_tutorial/task_app_settings.htm?resultof=%22%41%70%70%53%65%74%74%69%6e%67%22%20%22%61%70%70%73%65%74%74%69%6e%67%22%20">Task: App Setting</a>.
  61  *
  62  */
  63 class _OSP_EXPORT_ AppSetting
  64         : public Tizen::Base::Object
  65 {
  66 public:
  67         /**
  68          * Gets the application setting instance.
  69          *
  70          * @since       2.0
  71          *
  72          * @return              A pointer to the %AppSetting instance, @n
  73          *                              else @c null if it fails
  74          * @exception   E_SUCCESS                       The method is successful.
  75          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  76          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  77          * @remarks             It returns an instance for the latest setting. @n
  78          *                              The specific error code can be accessed using the GetLastResult() method.
  79          */
  80         static AppSetting* GetInstance(void);
  81
  82         /**
  83          * Gets the application setting instance of the specified version.
  84          *
  85          * @since       2.0
  86          *
  87          * @return              A pointer to the %AppSetting instance, @n
  88          *                              else @c null if it fails
  89          * @param[in]   settingVersion          The version of setting is retrieved from GetAppSettingVersionListN()
  90          * @exception   E_SUCCESS                       The method is successful.
  91          * @exception   E_OBJ_NOT_FOUND         The specified version is not found.
  92          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  93          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  94          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  95          * @see                 GetAppSettingVersionListN()
  96          */
  97         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
  98
  99         /**
 100          * Gets the application setting instance of the specified AppId.
 101          *
 102          * @since       2.0
 103          *
 104          * @privlevel   platform
 105          * @privilege   %http://tizen.org/privilege/appsetting
 106          *
 107          * @return              A pointer to the %AppSetting instance, @n
 108          *                              else @c null if it fails
 109          * @param[in]   appId                           The AppId of the application that has a valid application setting
 110          * @exception   E_SUCCESS                       The method is successful.
 111          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
 112          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 113          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 114          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
 115          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 116          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 117          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 118          * @see                 ReleaseInstanceByAppId()
 119          */
 120         static AppSetting* GetInstanceByAppId(const AppId& appId);
 121
 122         /**
 123          * Releases the specified application setting instance.
 124          *
 125          * @since       2.0
 126          *
 127          * @privlevel   platform
 128          * @privilege   %http://tizen.org/privilege/appsetting
 129          *
 130          * @return              An error code
 131          * @param[in]   appId                           The AppId of the application that has a valid application setting
 132          * @exception   E_SUCCESS                       The method is successful.
 133          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
 134          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 135          * @remarks             Individual instances are managed by the platform. @n
 136          *                              It is recommended to release instances to reduce memory usage.
 137          * @see                 GetInstanceByAppId()
 138          */
 139         static result ReleaseInstanceByAppId(const AppId& appId);
 140
 141         /**
 142          * Gets a list of all the versions that existed prior to the current version. @n
 143          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
 144          *
 145          * @since       2.0
 146          *
 147          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list
 148          * @exception   E_SUCCESS                       The method is successful.
 149          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 150          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 151          * @remarks             The latest version string is located in the first position.
 152          *                              If the old version does not exist then return empty collection. @n
 153          *                              The specific error code can be accessed using the GetLastResult() method.
 154          */
 155         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
 156
 157         /**
 158          * Gets a @c bool value associated with the specified @c id.
 159          *
 160          * @since       2.0
 161          *
 162          * @return              An error code
 163          * @param[in]   id                                      The ID of the value to retrieve
 164          * @param[out]  value                           A boolean value to retrieve
 165          * @exception   E_SUCCESS                       The method is successful.
 166          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 167          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 168          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 169          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 170          */
 171         result GetValue(const Tizen::Base::String& id, bool& value) const;
 172
 173         /**
 174          * Gets an integer value associated with the specified @c id.
 175          *
 176          * @since       2.0
 177          *
 178          * @return              An error code
 179          * @param[in]   id                                      The ID of the value to retrieve
 180          * @param[out]  value                           An integer value to retrieve
 181          * @exception   E_SUCCESS                       The method is successful.
 182          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 183          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 184          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 185          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 186          */
 187         result GetValue(const Tizen::Base::String& id, int& value) const;
 188
 189         /**
 190          * Gets a string value associated with the specified @c id.
 191          *
 192          * @since       2.0
 193          *
 194          * @return              An error code
 195          * @param[in]   id                                      The id of the value to retrieve
 196          * @param[out]  value                           A string value to retrieve
 197          * @exception   E_SUCCESS                       The method is successful.
 198          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 199          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 200          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 201          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 202          */
 203         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
 204
 205         /**
 206          * Sets a @c bool value associated with the specified @c id.
 207          *
 208          * @since       2.0
 209          *
 210          * @return              An error code
 211          * @param[in]   id                                      The ID of the value to modify
 212          * @param[in]   value                           A boolean value
 213          * @exception   E_SUCCESS                       The method is successful.
 214          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 215          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 216          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 217          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 218          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 219          */
 220         result SetValue(const Tizen::Base::String& id, bool value);
 221
 222         /**
 223          * Sets an integer value associated with the specified @c id.
 224          *
 225          * @since       2.0
 226          *
 227          * @return              An error code
 228          * @param[in]   id                                      The ID of the value to modify
 229          * @param[in]   value                           An integer value
 230          * @exception   E_SUCCESS                       The method is successful.
 231          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 232          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 233          * @exception   E_OUT_OF_RANGE          The specified @c value is out of range.
 234          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 235          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 236          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 237          */
 238         result SetValue(const Tizen::Base::String& id, int value);
 239
 240         /**
 241          * Sets a string value associated with the specified @c id.
 242          *
 243          * @since       2.0
 244          *
 245          * @return              An error code
 246          * @param[in]   id                                      The ID of the value to modify
 247          * @param[in]   value                           A string value
 248          * @exception   E_SUCCESS                       The method is successful.
 249          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 250          * @exception   E_OBJ_NOT_FOUND         The specified @c id is not found in the application setting.
 251          * @exception   E_OUT_OF_RANGE          The specified string length is out of range.
 252          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 253          * @exception   E_TYPE_MISMATCH         The operation has attempted to access different types.
 254          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 255          */
 256         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
 257
 258         /**
 259          * Sets a setting event listener.
 260          *
 261          * @since       2.0
 262          *
 263          * @return              An error code
 264          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
 265          *                                  else @c null to clear a previous one
 266          * @exception   E_SUCCESS                       The method is successful.
 267          */
 268         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
 269
 270 private:
 271         /**
 272          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 273          *
 274          * @since       2.0
 275          */
 276         AppSetting(void);
 277
 278         /**
 279          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 280          *
 281          * @since       2.0
 282          */
 283         AppSetting(const AppSetting& rhs);
 284
 285         /**
 286          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 287          *
 288          * @since       2.0
 289          */
 290         AppSetting& operator =(const AppSetting& rhs);
 291
 292         /**
 293          * This destructor is intentionally declared as private to implement the Singleton semantic.
 294          *
 295          * @since       2.0
 296          */
 297         virtual ~AppSetting(void);
 298
 299         static void InitSingleton(void);
 300         static void DestroySingleton(void);
 301
 302 private:
 303         friend class _AppSettingImpl;
 304         class _AppSettingImpl* __pAppSettingImpl;
 305         static AppSetting* __pAppSettingInstance;
 306
 307 }; // AppSetting
 308 } } // Tizen::App
 309
 310 #endif // _FAPP_APP_SETTING_H_