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
  60  * IAppSettingEventListener::OnAppSettingChanged()
  61  * 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>.
  62  *
  63  * @see IAppSettingEventListener
  64  */
  65 class _OSP_EXPORT_ AppSetting
  66         : public Tizen::Base::Object
  67 {
  68 public:
  69         /**
  70          * Gets the application setting instance.
  71          *
  72          * @since       2.0
  73          *
  74          * @return              A pointer to the %AppSetting instance for the last setting, @n
  75          *                              else @c null if it fails
  76          * @exception   E_SUCCESS                       The method is successful.
  77          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  78          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  79          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  80          */
  81         static AppSetting* GetInstance(void);
  82
  83         /**
  84          * Gets the application setting instance of the specified version.
  85          *
  86          * @since       2.0
  87          *
  88          * @return              A pointer to the %AppSetting instance, @n
  89          *                              else @c null if it fails
  90          * @param[in]   settingVersion          The version of setting is retrieved from GetAppSettingVersionListN()
  91          * @exception   E_SUCCESS                       The method is successful.
  92          * @exception   E_OBJ_NOT_FOUND         The specified version is not found.
  93          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  94          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  95          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  96          * @see                 GetAppSettingVersionListN()
  97          */
  98         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
  99
 100         /**
 101          * Gets the application setting instance of the specified AppId.
 102          *
 103          * @since       2.0
 104          *
 105          * @privlevel   platform
 106          * @privilege   %http://tizen.org/privilege/appsetting
 107          *
 108          * @return              A pointer to the %AppSetting instance, @n
 109          *                              else @c null if it fails
 110          * @param[in]   appId                           The AppId of the application that has a valid application setting
 111          * @exception   E_SUCCESS                       The method is successful.
 112          * @exception   E_OBJ_NOT_FOUND         The instance of specified AppId does not have setting information.
 113          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 114          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 115          * @exception   E_APP_NOT_INSTALLED     The AppId is not found.
 116          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 117          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 118          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 119          * @see                 ReleaseInstanceByAppId()
 120          */
 121         static AppSetting* GetInstanceByAppId(const AppId& appId);
 122
 123         /**
 124          * Releases the specified application setting instance.
 125          *
 126          * @since       2.0
 127          *
 128          * @privlevel   platform
 129          * @privilege   %http://tizen.org/privilege/appsetting
 130          *
 131          * @return              An error code
 132          * @param[in]   appId                           The AppId of the application that has a valid application setting
 133          * @exception   E_SUCCESS                       The method is successful.
 134          * @exception   E_OBJ_NOT_FOUND         The specified instance of AppId is not found or already released.
 135          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 136          * @remarks             Individual instances are managed by the platform. @n
 137          *                              It is recommended to release instances to reduce memory usage.
 138          * @see                 GetInstanceByAppId()
 139          */
 140         static result ReleaseInstanceByAppId(const AppId& appId);
 141
 142         /**
 143          * Gets a list of all the versions that existed prior to the current version. @n
 144          * The versions listed are based on the setting.xml file, which is generated when an application is installed.
 145          *
 146          * @since       2.0
 147          *
 148          * @return              A pointer to the list that contains the Tizen::Base::String instances of version list @n
 149          *                              The latest version string is located in the first position. If the old version does not exist then return empty collection.
 150          * @exception   E_SUCCESS                       The method is successful.
 151          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 152          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 153          * @remarks     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_