inc/FAppAppRegistry.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                        FAppAppRegistry.h
  20  * @brief                       This is the header file for the %AppRegistry class.
  21  *
  22  * This header file contains the declarations of the %AppRegistry class.
  23  */
  24
  25 #ifndef _FAPP_APP_REGISTRY_H_
  26 #define _FAPP_APP_REGISTRY_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FAppTypes.h>
  30
  31 namespace Tizen { namespace App
  32 {
  33
  34 /**
  35  * @class               AppRegistry
  36  * @brief               This class manages an application's preferences.
  37  *
  38  * @since       2.0
  39  *
  40  * @final       This class is not intended for extension.
  41  *
  42  * The %AppRegistry class lets an application to save or restore its preferences.
  43  * An instance of this class can be obtained through the Application class.
  44  * Also, since an application's state is generally restored in the App::OnAppInitializing() method and saved in the App::OnAppTerminating() method, an instance of this class is passed as an argument when these methods are invoked.
  45  * @n
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/app_namespace.htm">App Guide</a>.
  47  *
  48  * The following example demonstrates how to use the %AppRegistry class.
  49  *
  50  * @code
  51  *
  52  * void
  53  * MyAppClass::AppRegistryCallSample(void)
  54  * {
  55  *      AppRegistry* pAppRegistry = GetAppRegistry();
  56  *      String countKey("BasicAppRunCount");
  57  *      String nameKey("BasicAppUserName");
  58  *      String temperatureKey("BasicAppTemperature");
  59  *      String name("BasicApp");
  60  *      double temperature = 32.5;
  61  *      result r = E_SUCCESS;
  62  *      int     count = 0;
  63  *
  64  *      r = pAppRegistry->Get(nameKey, name);
  65  *      if (r == E_KEY_NOT_FOUND)
  66  *      {
  67  *              pAppRegistry->Add(nameKey, name);
  68  *      }
  69  *
  70  *      r = pAppRegistry->Get(countKey, count);
  71  *      if (r == E_KEY_NOT_FOUND)
  72  *      {
  73  *              pAppRegistry->Add(countKey, count);
  74  *      }
  75  *
  76  *      r = pAppRegistry->Get(temperatureKey, temperature);
  77  *      if (r == E_KEY_NOT_FOUND)
  78  *      {
  79  *              pAppRegistry->Add(temperatureKey, temperature);
  80  *      }
  81  *
  82  *      r = pAppRegistry->Save();
  83  *      if (IsFailed(r))
  84  *      {
  85  *              // Failed to save data to registry
  86  *      }
  87  *
  88  *      // Displays the retrieved data
  89  *      AppLog("AppRegistry Name value [%ls]", name.GetPointer());
  90  *      AppLog("AppRegistry count [%d]", count);
  91  *      AppLog("AppRegistry temperature value [%f]", temperature);
  92  *
  93  *      // Updates the state of the application variables
  94  *      count++;
  95  *      name.Append(count);
  96  *      temperature++;
  97  *
  98  *      // Saves the app registry
  99  *      r = pAppRegistry->Set(nameKey, name);
 100  *      if (IsFailed(r))
 101  *      {
 102  *              // Error condition
 103  *      }
 104  *
 105  *      r = pAppRegistry->Set(countKey, count);
 106  *      if (IsFailed(r))
 107  *      {
 108  *              // Error condition
 109  *      }
 110  *
 111  *      r = pAppRegistry->Set(temperatureKey, temperature);
 112  *      if (IsFailed(r))
 113  *      {
 114  *              // Error condition
 115  *      }
 116  *
 117  *      r = pAppRegistry->Save();
 118  *      if (IsFailed(r))
 119  *      {
 120  *              // Failed to save data to registry
 121  *      }
 122  *
 123  *      // Retrieves the saved content
 124  *      pAppRegistry->Get(nameKey, name);
 125  *      pAppRegistry->Get(countKey, count);
 126  *      pAppRegistry->Get(temperatureKey, temperature);
 127  *
 128  *      AppLog("AppRegistry Name value [%ls]", name.GetPointer());
 129  *      AppLog("AppRegistry count [%d]", count);
 130  *      AppLog("AppRegistry temperature value [%f]", temperature);
 131  *
 132  *      return;
 133  * }
 134  * @endcode
 135  *
 136  **/
 137 class _OSP_EXPORT_ AppRegistry
 138         : public Tizen::Base::Object
 139 {
 140 public:
 141         /**
 142          * Adds a string value along with the specified @c key.
 143          *
 144          * @since       2.0
 145          *
 146          * @return      An error code
 147          * @param[in]   key             A key corresponding to the value
 148          * @param[in]   value   A string value
 149          * @exception   E_SUCCESS                               The method is successful.
 150          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 151          * @exception   E_KEY_ALREADY_EXIST             The key has already been used in the application preferences.
 152          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 153          */
 154         result Add(const Tizen::Base::String& key, const Tizen::Base::String& value);
 155
 156         /**
 157          * Adds an integer value along with the specified @c key.
 158          *
 159          * @since       2.0
 160          *
 161          * @return      An error code
 162          * @param[in]   key             A key corresponding to the value
 163          * @param[in]   value   An integer value
 164          * @exception   E_SUCCESS                               The method is successful.
 165          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 166          * @exception   E_KEY_ALREADY_EXIST             The key has already been used in the application preferences.
 167          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 168          */
 169         result Add(const Tizen::Base::String& key, int value);
 170
 171         /**
 172          * Adds a floating point value along with the specified @c key.
 173          *
 174          * @since       2.0
 175          *
 176          * @return      An error code
 177          * @param[in]   key             A key corresponding to the value
 178          * @param[in]   value   A floating point value
 179          * @exception   E_SUCCESS                               The method is successful.
 180          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 181          * @exception   E_KEY_ALREADY_EXIST             The key has already been used in the application preferences.
 182          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 183          */
 184         result Add(const Tizen::Base::String& key, double value);
 185
 186         /**
 187          * Sets a string value associated with the specified @c key.
 188          *
 189          * @since       2.0
 190          *
 191          * @return      An error code
 192          * @param[in]   key             A key corresponding to the value
 193          * @param[in]   value   A string value
 194          * @exception   E_SUCCESS                       The method is successful.
 195          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 196          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 197          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 198          */
 199         result Set(const Tizen::Base::String& key, const Tizen::Base::String& value);
 200
 201         /**
 202          * Sets an integer value associated with the specified @c key.
 203          *
 204          * @since       2.0
 205          *
 206          * @return      An error code
 207          * @param[in]   key     A key corresponding to the value
 208          * @param[in]   value   An integer value
 209          * @exception   E_SUCCESS                       The method is successful.
 210          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 211          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 212          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 213          */
 214         result Set(const Tizen::Base::String& key, int value);
 215
 216         /**
 217          * Sets a floating point value associated with the specified @c key.
 218          *
 219          * @since       2.0
 220          *
 221          * @return      An error code
 222          * @param[in]   key     A key corresponding to the value
 223          * @param[in]   value   A floating point value
 224          * @exception   E_SUCCESS                       The method is successful.
 225          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 226          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 227          * @remarks     In order to save the value in the persistent storage, the Save() method must be called.
 228          */
 229         result Set(const Tizen::Base::String& key, double value);
 230
 231         /**
 232          * Saves the values temporarily in the persistent storage. @n
 233          * The %Save() method is invoked internally when the instance of this class is deleted.
 234          *
 235          * @since       2.0
 236          *
 237          * @return      An error code
 238          * @exception   E_SUCCESS                       The method is successful.
 239          */
 240         result Save(void);
 241
 242         /**
 243          * Removes a preference associated with the specified @c key.
 244          *
 245          * @since       2.0
 246          *
 247          * @return      An error code
 248          * @param[in]   key             The key of the value to remove
 249          * @exception   E_SUCCESS                               The method is successful.
 250          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 251          */
 252         result Remove(const Tizen::Base::String& key);
 253
 254         /**
 255          * Gets a string value associated with the specified @c key.
 256          *
 257          * @since       2.0
 258          *
 259          * @return      An error code
 260          * @param[in]   key             The key of the value to retrieve
 261          * @param[out]  value   A string value to retrieve
 262          * @exception   E_SUCCESS                       The method is successful.
 263          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 264          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 265          */
 266         result Get(const Tizen::Base::String& key, Tizen::Base::String& value) const;
 267
 268         /**
 269          * Gets an integer value associated with the specified @c key.
 270          *
 271          * @since       2.0
 272          *
 273          * @return      An error code
 274          * @param[in]   key             The key of the value to retrieve
 275          * @param[out]  value   An integer value to retrieve
 276          * @exception   E_SUCCESS                       The method is successful.
 277          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 278          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 279          */
 280         result Get(const Tizen::Base::String& key, int& value) const;
 281
 282         /**
 283          * Gets a floating point value associated with the specified @c key.
 284          *
 285          * @since       2.0
 286          *
 287          * @return      An error code
 288          * @param[in]   key             The key of the value to retrieve
 289          * @param[out]  value   A floating point value to retrieve
 290          * @exception   E_SUCCESS                       The method is successful.
 291          * @exception   E_INVALID_ARG                   The specified @c key is empty or is string with '\0' and @htmlonly '\n' @endhtmlonly.
 292          * @exception   E_KEY_NOT_FOUND         The specified @c key is not used in the application preferences.
 293          */
 294         result Get(const Tizen::Base::String& key, double& value) const;
 295
 296         /**
 297          * Gets the %AppRegistry instance pointer.
 298          *
 299          * @since               2.0
 300          *
 301          * @return A pointer to the %AppRegistry instance, @n
 302          *                else @c null if it fails
 303          */
 304         static AppRegistry* GetInstance(void);
 305
 306 private:
 307         /**
 308          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 309          *
 310          * @since       2.0
 311          */
 312         AppRegistry(void);
 313
 314         /**
 315          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 316          *
 317          * @since       2.0
 318          */
 319         AppRegistry(const AppRegistry& rhs);
 320
 321         /**
 322          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 323          *
 324          * @since       2.0
 325          */
 326         AppRegistry& operator =(const AppRegistry& rhs);
 327
 328         /**
 329          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 330          *
 331          * @since       2.0
 332          */
 333         virtual ~AppRegistry(void);
 334
 335         /**
 336          * Initializes this instance.
 337          *
 338          * @since       2.0
 339          *
 340          * @return      An error code
 341          * @exception   E_SUCCESS       The method is successful.
 342          * @exception   E_SYSTEM        A system error has occurred.
 343          */
 344         result Construct(void);
 345
 346 private:
 347         class _AppRegistryImpl* __pAppRegistryImpl;
 348
 349         friend class _AppRegistryImpl;
 350 }; // AppRegistry
 351
 352 } } // Tizen::App
 353
 354 #endif // _FAPP_APP_REGISTRY_H_