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 only be of three types: @c int, @c bool, and @c String.
  54  * The settings are pre-defined at 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  * (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 which have no UI, such as IME.
  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 between the setting values of two applications, that is, the target application and the setting application, the setting application notifies the target application through
  60  * the IAppSettingEventListener::OnAppSettingChanged() method when setting a value.
  61  *
  62  * For a detailed example on the %AppSetting 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>.
  63  *
  64  * @see IAppSettingEventListener
  65  */
  66 class _OSP_EXPORT_ AppSetting
  67         : public Tizen::Base::Object
  68 {
  69 public:
  70         /**
  71          * Gets the pointer to the %AppSetting instance.
  72          *
  73          * @since       2.0
  74          *
  75          * @return              The pointer to the %AppSetting instance for the last setting, @n
  76          *                              else @c null if it fails
  77          * @exception   E_SUCCESS                       The method is successful.
  78          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  79          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  80          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  81          */
  82         static AppSetting* GetInstance(void);
  83
  84         /**
  85          * Gets the pointer to the %AppSetting instance of the specified version.
  86          *
  87          * @since       2.0
  88          *
  89          * @return              The pointer to the %AppSetting instance, @n
  90          *                              else @c null if it fails
  91          * @param[in]   settingVersion          The version of the setting which is retrieved from GetAppSettingVersionListN()
  92          * @exception   E_SUCCESS                       The method is successful.
  93          * @exception   E_OBJ_NOT_FOUND         The specified version has not been found.
  94          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  95          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  96          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  97          */
  98         static AppSetting* GetInstance(const Tizen::Base::String& settingVersion);
  99
 100         /**
 101          * Gets an %AppSetting instance of the specified ID.
 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 ID of the application that has a valid application setting
 111          * @exception   E_SUCCESS                       The method is successful.
 112          * @exception   E_OBJ_NOT_FOUND         The specified @c appId does not have the required 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 @c appId has not been 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 %AppSetting 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 ID of the application that has a valid application setting
 133          * @exception   E_SUCCESS                       The method is successful.
 134          * @exception   E_OBJ_NOT_FOUND         Either of the following conditions has occurred:
 135          *                                                              - The specified @c appId has not been found.
 136          *                                                              - The specified @c appId is already released.
 137          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 138          * @remarks
 139          *                      - Individual instances are managed by the platform.
 140          *                      - It is recommended to release instances to reduce memory usage.
 141          * @see                 GetInstanceByAppId()
 142          */
 143         static result ReleaseInstanceByAppId(const AppId& appId);
 144
 145         /**
 146          * Gets the list of all the versions that existed prior to the current version. @n
 147          * The versions are listed based on the setting.xml file, which is generated when an application is installed.
 148          *
 149          * @since       2.0
 150          *
 151          * @return              A pointer to the list that contains the Tizen::Base::String instances of the version list @n
 152          *                              The latest version string is located at the first position @n
 153          *                              If the old version does not exist then an empty collection is returned.
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 156          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 157          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 158          */
 159         static Tizen::Base::Collection::IList* GetAppSettingVersionListN(void);
 160
 161         /**
 162          * Gets the @c bool value associated with the specified @c id.
 163          *
 164          * @since       2.0
 165          *
 166          * @return              An error code
 167          * @param[in]   id                                      The ID of the boolean value to retrieve
 168          * @param[out]  value                           The boolean value to retrieve
 169          * @exception   E_SUCCESS                       The method is successful.
 170          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 171          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 172          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 173          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 174          */
 175         result GetValue(const Tizen::Base::String& id, bool& value) const;
 176
 177         /**
 178          * Gets the integer value associated with the specified @c id.
 179          *
 180          * @since       2.0
 181          *
 182          * @return              An error code
 183          * @param[in]   id                                      The ID of the integer value to retrieve
 184          * @param[out]  value                           The integer value to retrieve
 185          * @exception   E_SUCCESS                       The method is successful.
 186          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 187          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 188          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 189          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 190          */
 191         result GetValue(const Tizen::Base::String& id, int& value) const;
 192
 193         /**
 194          * Gets the string value associated with the specified @c id.
 195          *
 196          * @since       2.0
 197          *
 198          * @return              An error code
 199          * @param[in]   id                                      The ID of the string value to retrieve
 200          * @param[out]  value                           The string value to retrieve
 201          * @exception   E_SUCCESS                       The method is successful.
 202          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 203          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 204          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 205          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 206          */
 207         result GetValue(const Tizen::Base::String& id, Tizen::Base::String& value) const;
 208
 209         /**
 210          * Sets the @c bool value associated with the specified @c id.
 211          *
 212          * @since       2.0
 213          *
 214          * @return              An error code
 215          * @param[in]   id                                      The ID of the boolean value to modify
 216          * @param[in]   value                           The boolean value
 217          * @exception   E_SUCCESS                       The method is successful.
 218          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 219          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 220          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 221          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 222          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 223          */
 224         result SetValue(const Tizen::Base::String& id, bool value);
 225
 226         /**
 227          * Sets the integer value associated with the specified @c id.
 228          *
 229          * @since       2.0
 230          *
 231          * @return              An error code
 232          * @param[in]   id                                      The ID of the integer value to modify
 233          * @param[in]   value                           The integer value
 234          * @exception   E_SUCCESS                       The method is successful.
 235          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 236          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 237          * @exception   E_OUT_OF_RANGE          The specified @c value is out of the valid range.
 238          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 239          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 240          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 241          */
 242         result SetValue(const Tizen::Base::String& id, int value);
 243
 244         /**
 245          * Sets the string value associated with the specified @c id.
 246          *
 247          * @since       2.0
 248          *
 249          * @return              An error code
 250          * @param[in]   id                                      The ID of the string value to modify
 251          * @param[in]   value                           The string value
 252          * @exception   E_SUCCESS                       The method is successful.
 253          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 254          * @exception   E_OBJ_NOT_FOUND         The specified @c id has not been found in the application setting.
 255          * @exception   E_OUT_OF_RANGE          The specified string length is out of the valid range.
 256          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 257          * @exception   E_TYPE_MISMATCH         The types accessed by the method do not match.
 258          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 259          */
 260         result SetValue(const Tizen::Base::String& id, const Tizen::Base::String& value);
 261
 262         /**
 263          * Sets the setting event listener.
 264          *
 265          * @since       2.0
 266          *
 267          * @return              An error code
 268          * @param[in]   pListener                       An instance of IAppSettingEventListener to set, @n
 269          *                                  else @c null to clear a previous one
 270          * @exception   E_SUCCESS                       The method is successful.
 271          */
 272         result SetAppSettingEventListener(IAppSettingEventListener* pListener);
 273
 274 private:
 275         /**
 276          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 277          *
 278          * @since       2.0
 279          */
 280         AppSetting(void);
 281
 282         /**
 283          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 284          *
 285          * @since       2.0
 286          */
 287         AppSetting(const AppSetting& rhs);
 288
 289         /**
 290          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 291          *
 292          * @since       2.0
 293          */
 294         AppSetting& operator =(const AppSetting& rhs);
 295
 296         /**
 297          * This destructor is intentionally declared as private to implement the Singleton semantic.
 298          *
 299          * @since       2.0
 300          */
 301         virtual ~AppSetting(void);
 302
 303         static void InitSingleton(void);
 304         static void DestroySingleton(void);
 305
 306 private:
 307         friend class _AppSettingImpl;
 308         class _AppSettingImpl* __pAppSettingImpl;
 309         static AppSetting* __pAppSettingInstance;
 310
 311 }; // AppSetting
 312 } } // Tizen::App
 313
 314 #endif // _FAPP_APP_SETTING_H_