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