inc/FIoRegistry.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        FIoRegistry.h
  20  * @brief       This is the header file for the %Registry class.
  21  *
  22  * This header file contains the declarations of the %Registry class.
  23  */
  24
  25 #ifndef _FIO_REGISTRY_H_
  26 #define _FIO_REGISTRY_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseUuId.h>
  30 #include <FBaseByteBuffer.h>
  31 #include <FBaseColArrayList.h>
  32 #include <FBaseResult.h>
  33 #include <FBaseColIMap.h>
  34
  35 namespace Tizen {namespace Base
  36 {
  37 class String;
  38 class ByteBuffer;
  39 }}
  40
  41 namespace Tizen { namespace Io
  42 {
  43
  44 static const long REG_OPEN_READ_ONLY  = 0x00000001L;
  45 static const long REG_OPEN_READ_WRITE = 0x00000002L;
  46 static const long REG_OPEN_CREATE     = 0x00000004L;
  47
  48 /**
  49  * @class       Registry
  50  * @brief       This class provides a mechanism to access and manipulate registry files.
  51  *
  52  * @since       2.0
  53  *
  54  * @final       This class is not intended for extension.
  55  *
  56  * The %Registry class provides a mechanism to access and manipulate registry files.
  57  *
  58  * For more information on the class features,
  59  * see <a href="../org.tizen.native.appprogramming/html/guide/io/io_namespace.htm">Io Guide</a>.
  60  *
  61  * The following example demonstrates how to use the %Registry class.
  62  *
  63  * @code
  64 #include <FBase.h>
  65 #include <FIo.h>
  66 #include <FApp.h>
  67
  68 using namespace Tizen::Base;
  69 using namespace Tizen::Io;
  70 using namespace Tizen::App;
  71
  72 void
  73 RegistryTest()
  74 {
  75         Registry reg;
  76         String regPathName(L"regTest.ini");
  77
  78         // Section name
  79         String sect1(L"section1");
  80         String sect2(L"section2");
  81         String sect3(L"section3");
  82
  83         // Entry name
  84         String entry1(L"entry1");
  85         String entry2(L"entry2");
  86
  87         int iVal;
  88         result r;
  89
  90         r = reg.Construct(App::GetInstance()->GetAppDataPath() + regPathName, "a+");
  91         if (IsFailed(r))
  92         {
  93                 goto CATCH;
  94         }
  95
  96         // Create sections
  97         r = reg.AddSection(sect1);
  98         r = reg.AddSection(sect2);
  99         r = reg.AddSection(sect3);
 100
 101         // Add value: section1 { entry1 = 999 }
 102         r = reg.AddValue(sect1, entry1, 999);
 103         if (IsFailed(r))
 104         {
 105                 goto CATCH;
 106         }
 107
 108         // Change value: section1 { entry1 = 3 }
 109         r = reg.SetValue(sect1, entry1, 3);
 110         if (IsFailed(r))
 111         {
 112                 goto CATCH;
 113         }
 114
 115         // Add value: section2 { entry2 = 1.1234599 }
 116         r = reg.AddValue(sect2, entry2, 1.1234599);
 117         if (IsFailed(r))
 118         {
 119                 goto CATCH;
 120         }
 121
 122         // Get value: section1 { entry1 = ? }
 123         r = reg.GetValue(sect1, entry1, iVal);
 124         if (IsFailed(r))
 125         {
 126                 goto CATCH;
 127         }
 128
 129         // Write to the file
 130         r = reg.Flush();
 131         if (IsFailed(r))
 132         {
 133                 goto CATCH;
 134         }
 135
 136         return;
 137
 138 CATCH:
 139         // Do some error handling
 140         return;
 141 }
 142  * @endcode
 143  */
 144
 145 class _OSP_EXPORT_ Registry
 146         : public Tizen::Base::Object
 147 {
 148
 149 public:
 150         /**
 151         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 152         *
 153         * @since        2.0
 154         */
 155         Registry(void);
 156
 157         /**
 158         * This destructor overrides Tizen::Base::Object::~Object().
 159         *
 160         * @since        2.0
 161         */
 162         virtual ~Registry(void);
 163
 164         /**
 165         * @if OSPDEPREC
 166         * @{
 167         * Initializes this instance of %Registry with the specified parameters. @n
 168         * This method loads a registry file in the read-write mode.
 169         *
 170         * @if OSPCOMPAT
 171         * @brief                        <i> [Deprecated] [Compatibility] </i>
 172         * @endif
 173         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 174         *                                       bool createParentDirectories=false) and Registry::Construct(const Tizen::Base::String& regPath, const Tizen::Base::String& openMode).
 175         * @since                        2.0
 176         * @if OSPCOMPAT
 177         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 178         *                                       For more information, see @ref CompIoPathPage "here".
 179         * @endif
 180         *
 181         * @return               An error code
 182         * @param[in]    regPath                                 The path of the registry file to open or create
 183         * @param[in]    createIfNotExist                Set to @c true to create a registry file, @n
 184         *                                       else @c false to open an existing registry file
 185         * @exception    E_SUCCESS                               The method is successful.
 186         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 187         *                                                                               - The length of the specified string of a file path is less
 188         *                                                                                 than or equal to @c 0. @n
 189         *                                                                               - The translated overall length of the specified path exceeds the
 190         *                                                                                 system limitation. @n
 191         *                                                                               - The specified path is invalid. @n
 192         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 193         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 194         * @exception    E_END_OF_FILE                   The file pointer has reached end-of-file.
 195         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 196         * @exception    E_STORAGE_FULL                  The disk space is full.
 197         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 198         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 199         *                                                                               - %File corruption is detected.
 200         * @exception    E_INVALID_FORMAT                The input registry file contains '0x00' in the middle of the file.
 201         * @exception    E_PARSING_FAILED                The method has failed to parse the registry file.
 202         * @remarks              To load the registry in read-only mode, use the Registry::Construct(const Tizen::Base::String& regPath,
 203         *               long openMode, long option) method with REG_OPEN_READ_ONLY as a value for the open mode flag.
 204         * @}
 205         * @endif
 206         */
 207         result Construct(const Tizen::Base::String& regPath, bool createIfNotExist);
 208
 209         /**
 210         * @if OSPDEPREC
 211         * @{
 212         * Initializes this instance of %Registry with the specified parameters. @n
 213         * This method loads a registry file in the read-only or the read-write mode.
 214         *
 215         * @if OSPCOMPAT
 216         * @brief                        <i> [Deprecated] [Compatibility] </i>
 217         * @endif
 218         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 219         *                                       bool createParentDirectories=false) and Registry::Construct(const Tizen::Base::String& regPath, const Tizen::Base::String& openMode).
 220         * @since                        2.0
 221         * @if OSPCOMPAT
 222         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 223         *                                       For more information, see @ref CompIoPathPage "here".
 224         * @endif
 225         *
 226         * @return               An error code
 227         * @param[in]    regPath                                 The path of the registry file to open or create
 228         * @param[in]    openMode                                An open mode flag @n
 229         *                                       Currently, the following flags can be used in combination with
 230         *                                       the logical OR operator: @n
 231         *                                                                                (1) REG_OPEN_READ_ONLY @n
 232         *                                                                                (2) REG_OPEN_READ_WRITE @n
 233         *                                                                                (3) REG_OPEN_READ_WRITE | REG_OPEN_CREATE
 234         * @param[in]    option                                  This argument is reserved for further use @n It is recommended to use @c 0.
 235         * @exception    E_SUCCESS                               The method is successful.
 236         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 237         *                                                                               - The length of the specified string of a file path is less
 238         *                                                                                 than or equal to @c 0. @n
 239         *                                                                               - The translated overall length of the specified path exceeds the
 240         *                                                                                 system limitation. @n
 241         *                                                                               - The specified path is invalid. @n
 242         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 243         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 244         * @exception    E_END_OF_FILE                   The file pointer has reached end-of-file.
 245         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 246         * @exception    E_STORAGE_FULL                  The disk space is full.
 247         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 248         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 249         *                                                                               - %File corruption is detected.
 250         * @exception    E_INVALID_FORMAT                The input registry file contains '0x00' in the middle of the file.
 251         * @exception    E_PARSING_FAILED                The method has failed to parse the registry file.
 252         * @}
 253         * @endif
 254         */
 255         result Construct(const Tizen::Base::String& regPath, long openMode, long option);
 256
 257         /**
 258         * Initializes this instance of %Registry with the specified parameters. @n
 259         * This method opens an existing registry file or creates a new one according to the specified file opening mode.
 260         * And this method loads data of the registry file to system memory and flushes the data to the storage when this instance
 261         * is released or Registry::Flush() is called.
 262         *
 263         * @since                2.0
 264         *
 265         * @return               An error code
 266         * @param[in]    regPath                         The path of the registry file to open or create
 267         * @param[in]    pOpenMode                       The file opening mode @n
 268         *                                                                       It can be one of the following:
 269         *                                                                       - r : Open for reading.
 270         *                                                                       - r+: Open for reading and writing.
 271         *                                                                       - w : Open for writing. The registry file is created if it does not exist,
 272         *                                                                                 otherwise it is truncated to zero length.
 273         *                                                                       - w+: Open for writing and reading. The registry file is created if it does not exist,
 274         *                                                                                 otherwise it is truncated to zero length.
 275         *                                                                       - a : Open for appending. The registry file is created if it does not exist.
 276         *                                                                       - a+: Open for appending and reading. The registry file is created if it does not exist.
 277         * @exception    E_SUCCESS                       The method is successful.
 278         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 279         *                                                                       - The overall length of the specified @c regPath is equal to @c 0 or
 280         *                                                                         exceeds system limitations. @n
 281         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 282         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 283         * @exception    E_FILE_NOT_FOUND        The specified @c regPath cannot be found.
 284         * @exception    E_INVALID_FORMAT        Either of the following conditions has occurred: @n
 285         *                                                                       - The section or entry name of the registry file includes one of the following characters:
 286         *                                                                       '\0', '\n', '#' and '='.
 287         *                                                                       - The entry value of the registry file includes one of the following characters:
 288         *                                                                       '\0' and '\n'.
 289         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 290         * @exception    E_STORAGE_FULL          The disk space is full.
 291         * @exception    E_IO                            Either of the following conditions has occurred: @n
 292         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 293         *                                                                       - %File corruption is detected.
 294         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 295         */
 296         result Construct(const Tizen::Base::String& regPath, const char* pOpenMode);
 297
 298         /**
 299         * Initializes this instance of %Registry with the specified parameters. @n
 300         * This method opens an existing secure registry file or creates a new one according to the specified file opening mode.
 301         * And this method loads data of the secure registry file to system memory and flushes the data to the storage when this instance
 302         * is released or Registry::Flush() is called.
 303         * The contents written to the secure registry file is automatically encrypted and the contents read from the secure registry
 304         * file is automatically decrypted by the platform. @n
 305         * Applications using this method can access the same secure registry files that are created by other applications with the
 306         * identical key value in same device. However, the secure registry files created by this method cannot be accessed in other devices.
 307         *
 308         * @since                2.0
 309         *
 310         * @return               An error code
 311         * @param[in]    regPath                         The path of the registry file to open or create
 312         * @param[in]    pOpenMode                       The file opening mode @n
 313         *                                                                       It can be one of the following:
 314         *                                                                       - r : Open for reading.
 315         *                                                                       - r+: Open for reading and writing.
 316         *                                                                       - w : Open for writing. The registry file is created if it does not exist,
 317         *                                                                                 otherwise it is truncated to zero length.
 318         *                                                                       - w+: Open for writing and reading. The registry file is created if it does not exist,
 319         *                                                                                 otherwise it is truncated to zero length.
 320         *                                                                       - a : Open for appending. The registry file is created if it does not exist.
 321         *                                                                       - a+: Open for appending and reading. The registry file is created if it does not exist.
 322         * @param[in]    secretKey                       A key used to encrypt data of a registry file or decrypt a secure registry file @n
 323         *                                                                       If a secure registry file is created with a specific key value,
 324         *                                                                       other applications can access the same secure registry file with the identical key value.
 325         * @exception    E_SUCCESS                       The method is successful.
 326         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 327         *                                                                       - The overall length of the specified path is equal to @c 0 or
 328         *                                                                         exceeds system limitations.
 329         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 330         *                                                                       - The specified @c secretKey is incorrect or the secure registry file is corrupted.
 331         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 332         * @exception    E_FILE_NOT_FOUND        The specified @c regPath cannot be found.
 333         * @exception    E_INVALID_FORMAT        Either of the following conditions has occurred: @n
 334         *                                                                       - The section or entry name of the registry file includes one of the following characters:
 335         *                                                                       '\0', '\n', '#' and '='.
 336         *                                                                       - The entry value of the registry file includes one of the following characters:
 337         *                                                                       '\0' and '\n'.
 338         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 339         * @exception    E_STORAGE_FULL          The disk space is full.
 340         * @exception    E_IO                            Either of the following conditions has occurred: @n
 341         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 342         *                                                                       - %File corruption is detected. @n
 343         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 344         */
 345         result Construct(const Tizen::Base::String& regPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
 346
 347         /**
 348         * Writes the current contents of a registry in memory to the non-volatile storage. @n
 349         * If the secure mode is set to be @c true, the contents of the registry are automatically encrypted
 350         * and saved by the platform.
 351         *
 352         * @since                2.0
 353         *
 354         * @return               An error code
 355         * @exception    E_SUCCESS                               The method is successful.
 356         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 357         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 358         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 359         * @exception    E_STORAGE_FULL                  The disk space is full.
 360         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 361         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 362         *                                                                               - %File corruption is detected. @n
 363         *                                                                               - The memory is insufficient.
 364         */
 365         result Flush(void);
 366
 367         /**
 368         * Creates the specified section then adds it into the registry.
 369         *
 370         * @since                2.0
 371         *
 372         * @return               An error code
 373         * @param[in]    sectionName                             The section name
 374         * @exception    E_SUCCESS                               The method is successful.
 375         * @exception    E_INVALID_ARG                   The length of the specified string for a section name is less than
 376         *                                       or equal to @c 0.
 377         * @exception    E_SECTION_ALREADY_EXIST A section with the specified name already exists.
 378         */
 379         result AddSection(const Tizen::Base::String& sectionName);
 380
 381         /**
 382         * Removes the section from %Registry.
 383         *
 384         * @since                2.0
 385         *
 386         * @return               An error code
 387         * @param[in]    sectionName                             The section name to remove
 388         * @exception    E_SUCCESS                               The method is successful.
 389         * @exception    E_INVALID_ARG                   The length of the specified string for a section is less than
 390         *                                       or equal to @c 0.
 391         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 392         */
 393         result RemoveSection(const Tizen::Base::String& sectionName);
 394
 395         /**
 396         * Gets all section names in the registry.
 397         *
 398         * @since                2.0
 399         *
 400         * @return               A list of section names @n
 401         *                               If this method fails, @c null value is returned. @n
 402         *                               The specific error code can be accessed using the GetLastResult() method. @n
 403         *                               When there are no sections at all, the method returns an empty list instance. @n
 404         *                               Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of elements in the list.
 405         * @exception    E_SUCCESS                               The method is successful.
 406         * @remarks              Do not forget to delete not only the returned IList instance, but also its
 407         *               contents by invoking IList::RemoveAll(). @n
 408         *                               The specific error code can be accessed using the GetLastResult() method.
 409         */
 410         Tizen::Base::Collection::IList* GetAllSectionNamesN(void) const;
 411
 412         /**
 413         * Gets all entry names in the specified section of the registry.
 414         *
 415         * @since                2.0
 416         *
 417         * @return               A list of entry names @n
 418         *                               If this method fails, @c null value is returned. @n
 419         *                               When there are no entries at all, the method returns an empty list instance. @n
 420         *                               Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of element in the list.
 421         * @param[in]    sectionName                             The section name
 422         * @exception    E_SUCCESS                               The method is successful.
 423         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 424         * @exception    E_IO                                    A system error has occurred.
 425         * @remarks              Do not forget to delete not only the returned IList instance, but also its
 426         *                               contents by invoking IList::RemoveAll(). @n
 427         *                               The specific error code can be accessed using the GetLastResult() method.
 428         */
 429         Tizen::Base::Collection::IList* GetAllEntryNamesN(const Tizen::Base::String& sectionName) const;
 430
 431         /**
 432         * Adds the name-value pair of type integer as an entry of the specific section.
 433         *
 434         * @since                2.0
 435         *
 436         * @return               An error code
 437         * @param[in]    sectionName                             The section name
 438         * @param[in]    entryName                               The entry name
 439         * @param[in]    value                                   The @c int value
 440         * @exception    E_SUCCESS                               The method is successful.
 441         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 442         *                                       or an entry is less than or equal to @c 0,
 443         *                                       or a @c null value is passed. @n
 444         *                                                                               Note that, it is also possible that the data inside a registry instance is
 445         *                                                                               corrupted due to its usage in a multi-threaded environment without
 446         *                                                                               synchronization.
 447         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 448         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 449         */
 450         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int value);
 451
 452         /**
 453         * Adds the name-value pair of type double as an entry of the specific section.
 454         *
 455         * @since                2.0
 456         *
 457         * @return               An error code
 458         * @param[in]    sectionName                             The section name
 459         * @param[in]    entryName                               The entry name
 460         * @param[in]    value                                   The @c double value
 461         * @exception    E_SUCCESS                               The method is successful.
 462         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 463         *                                       or an entry is less than or equal to @c 0,
 464         *                                       or a @c null value is passed. @n
 465         *                                                                               Note that, it is also possible that the data inside a registry instance is
 466         *                                                                               corrupted due to its usage in a multi-threaded environment without
 467         *                                                                               synchronization.
 468         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 469         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 470         */
 471         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double value);
 472
 473         /**
 474         * Adds the name-value pair of type float as an entry of the specific section.
 475         *
 476         * @since                2.0
 477         *
 478         * @return               An error code
 479         * @param[in]    sectionName                             The section name
 480         * @param[in]    entryName                               The entry name
 481         * @param[in]    value                                   The @c float value
 482         * @exception    E_SUCCESS                               The method is successful.
 483         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 484         *                                       or an entry is less than or equal to @c 0,
 485         *                                       or a @c null value is passed. @n
 486         *                                                                               Note that, it is also possible that the data inside a registry instance is
 487         *                                                                               corrupted due to its usage in a multi-threaded environment without
 488         *                                                                               synchronization.
 489         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 490         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 491         */
 492         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float value);
 493
 494         /**
 495         * Adds the name-value pair of type String as an entry of the specific section.
 496         *
 497         * @since                2.0
 498         *
 499         * @return               An error code
 500         * @param[in]    sectionName                             The section name
 501         * @param[in]    entryName                               The entry name
 502         * @param[in]    value                                   The String value
 503         * @exception    E_SUCCESS                               The method is successful.
 504         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 505         *                                       or an entry is less than or equal to @c 0.
 506         *                                                                               Note that, it is also possible that the data inside a registry instance is
 507         *                                                                               corrupted due to its usage in a multi-threaded environment without
 508         *                                                                               synchronization.
 509         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 510         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 511         */
 512         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& value);
 513
 514         /**
 515         * Adds the name-value pair of type UuId as an entry for the specified section.
 516         *
 517         * @since                2.0
 518         *
 519         * @return               An error code
 520         * @param[in]    sectionName                             The section name
 521         * @param[in]    entryName                               The entry name
 522         * @param[in]    value                                   The UuId value
 523         * @exception    E_SUCCESS                               The method is successful.
 524     * @exception        E_INVALID_ARG                   Either the length of the specified string for a section
 525         *                                       or an entry is less than or equal to @c 0,
 526         *                                       or a @c null value is passed. @n
 527         *                                                                               Note that, it is also possible that the data inside a registry instance is
 528         *                                                                               corrupted due to its usage in a multi-threaded environment without
 529         *                                                                               synchronization.
 530         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 531         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 532         */
 533         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& value);
 534
 535         /**
 536         * Adds the name-value pair of type ByteBuffer as an entry for the specified section.
 537         *
 538         * @since                2.0
 539         *
 540         * @return               An error code
 541         * @param[in]    sectionName                             The section name
 542         * @param[in]    entryName                               The entry name
 543         * @param[in]    value                                   The @c ByteBuffer value @n
 544         *                                       Note that, it should be constructed before being passed to the method.
 545         * @exception    E_SUCCESS                               The method is successful.
 546     * @exception        E_INVALID_ARG                   Either the length of the specified string for a section
 547         *                                       or an entry is less than or equal to @c 0,
 548         *                                       or a @c null value is passed. @n
 549         *                                                                               Note that, it is also possible that the data inside a registry instance is
 550         *                                                                               corrupted due to its usage in a multi-threaded environment without
 551         *                                                                               synchronization.
 552         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 553         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 554         * @remarks              Note that all the contents of @c ByteBuffer are saved as an entry value.
 555         *               That is, byte data from @c 0 up to the buffer limit is saved.
 556         * @see                  Tizen::Base::ByteBuffer
 557         */
 558         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& value);
 559
 560         /**
 561         * Gets the @c int value of the specified entry.
 562         *
 563         * @since                2.0
 564         *
 565         * @return               An error code
 566         * @param[in]    sectionName                             The section name
 567         * @param[in]    entryName                               The name of entry where its value will be fetched
 568         * @param[out]   retVal                                  The return value obtained from the registry
 569         * @exception    E_SUCCESS                               The method is successful.
 570         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 571         *                                       or an entry is less than or equal to @c 0,
 572         *                                       or a @c null value is passed. @n
 573         *                                                                               Note that, it is also possible that the data inside a registry instance is
 574         *                                                                               corrupted due to its usage in a multi-threaded environment without
 575         *                                                                               synchronization.
 576         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 577         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 578         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 579         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 580         */
 581         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int& retVal) const;
 582
 583         /**
 584         * Gets the @c double value of the specified entry.
 585         *
 586         * @since                2.0
 587         *
 588         * @return               An error code
 589         * @param[in]    sectionName                             The section name
 590         * @param[in]    entryName                               The name of entry where its value will be fetched
 591         * @param[out]   retVal                                  The return value obtained from the registry
 592         * @exception    E_SUCCESS                               The method is successful.
 593         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 594         *                                       or an entry is less than or equal to @c 0,
 595         *                                       or a @c null value is passed. @n
 596         *                                                                               Note that, it is also possible that the data inside a registry instance is
 597         *                                                                               corrupted due to its usage in a multi-threaded environment without
 598         *                                                                               synchronization.
 599         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 600         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 601         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 602         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 603         */
 604         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double& retVal) const;
 605
 606         /**
 607         * Gets the @c float value of the specified entry.
 608         *
 609         * @since                2.0
 610         *
 611         * @return               An error code
 612         * @param[in]    sectionName                             The section name
 613         * @param[in]    entryName                               The name of entry where its value will be fetched
 614         * @param[out]   retVal                                  The return value obtained from the registry
 615         * @exception    E_SUCCESS                               The method is successful.
 616         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 617         *                                       or an entry is less than or equal to @c 0,
 618         *                                       or a @c null value is passed. @n
 619         *                                                                               Note that, it is also possible that the data inside a registry instance is
 620         *                                                                               corrupted due to its usage in a multi-threaded environment without
 621         *                                                                               synchronization.
 622         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 623         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 624         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 625         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 626         */
 627         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float& retVal) const;
 628
 629         /**
 630         * Gets the String value of a specific entry.
 631         *
 632         * @since                2.0
 633         *
 634         * @return               An error code
 635         * @param[in]    sectionName                             The section name
 636         * @param[in]    entryName                               The name of entry where its value will be fetched
 637         * @param[out]   retVal                                  The return value obtained from the registry
 638         * @exception    E_SUCCESS                               The method is successful.
 639         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 640         *                                       or an entry is less than or equal to @c 0,
 641         *                                       or a @c null value is passed. @n
 642         *                                                                               Note that, it is also possible that the data inside a registry instance is
 643         *                                                                               corrupted due to its usage in a multi-threaded environment without
 644         *                                                                               synchronization.
 645         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 646         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 647         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 648         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 649         */
 650         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::String& retVal) const;
 651
 652         /**
 653         * Gets the UuId value of the specified entry.
 654         *
 655         * @since                2.0
 656         *
 657         * @return               An error code
 658         * @param[in]    sectionName                             The section name
 659         * @param[in]    entryName                               The name of entry where its value will be fetched
 660         * @param[out]   retVal                                  The return value obtained from the registry
 661         * @exception    E_SUCCESS                               The method is successful.
 662         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 663         *                                       or an entry is less than or equal to @c 0,
 664         *                                       or a @c null value is passed. @n
 665         *                                                                               Note that, it is also possible that the data inside a registry instance is
 666         *                                                                               corrupted due to its usage in a multi-threaded environment without
 667         *                                                                               synchronization.
 668         * @exception    E_SECTION_NOT_FOUND         The specified @c sectionName is not found within the registry.
 669         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 670         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 671         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 672         */
 673         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::UuId& retVal) const;
 674
 675         /**
 676         * Gets the ByteBuffer value of the specified entry.
 677         *
 678         * @since                2.0
 679         *
 680         * @return               An error code
 681         * @param[in]    sectionName                             The section name
 682         * @param[in]    entryName                               The name of entry where its value will be fetched
 683         * @param[out]   retVal                                  The return value obtained from the registry
 684         * @exception    E_SUCCESS                               The method is successful.
 685         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 686         *                                       or an entry is less than or equal to @c 0,
 687         *                                       or a @c null value is passed. @n
 688         *                                                                               Note that, it is also possible that the data inside a registry instance is
 689         *                                                                               corrupted due to its usage in a multi-threaded environment without
 690         *                                                                               synchronization.
 691         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 692         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 693         * @exception    E_PARSING_FAILED                The method has failed to parse the encoded entry value string, or the value is retrieved by using an incorrect data type.
 694         * @exception    E_DATA_NOT_FOUND                The name-value pair has no value assigned (if the value is retrieved using the REGTYPE_STRING type, an empty string is returned even if no value is assigned).
 695         * @remarks              The ByteBuffer should be constructed before passing it to the method.
 696         *                               That is, the size of the binary data to be fetched should be decided beforehand.
 697         *                               When the %ByteBuffer capacity is less than the actual binary data stored in the registry,
 698         *                               this method reads the data as much as the %ByteBuffer capacity. The position of the %ByteBuffer and
 699         *                               limit are not changed. When the %ByteBuffer capacity is greater than the actual data size,
 700         *                               the method reads the whole data and adjusts the limit of the buffer accordingly.
 701         * @see                  Tizen::Base::ByteBuffer
 702         */
 703         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::ByteBuffer& retVal) const;
 704
 705         /**
 706         * Modifies the value of the specified entry using the specified @c int value.
 707         *
 708         * @since                2.0
 709         *
 710         * @return               An error code
 711         * @param[in]    sectionName                             The section name
 712         * @param[in]    entryName                               The entry name to modify
 713         * @param[in]    newValue                                The @c int value
 714         * @exception    E_SUCCESS                               The method is successful.
 715         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 716         *                                       or an entry is less than or equal to @c 0,
 717         *                                       or a @c null value is passed. @n
 718         *                                                                               Note that, it is also possible that the data inside a registry instance is
 719         *                                                                               corrupted due to its usage in a multi-threaded environment without
 720         *                                                                               synchronization.
 721         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 722         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 723         * @remarks              This method will not add a name-value pair as an entry of a specific section
 724         *               if no entry with the specified name exists.
 725         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 726         * @see                  AddValue()
 727         */
 728         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int newValue);
 729
 730         /**
 731         * Modifies the value of the specified entry using the specified @c double value.
 732         *
 733         * @since                2.0
 734         *
 735         * @return               An error code
 736         * @param[in]    sectionName                             The section name
 737         * @param[in]    entryName                               The entry name to modify
 738         * @param[in]    newValue                                The @c double value
 739         * @exception    E_SUCCESS                               The method is successful.
 740         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 741         *                                       or an entry is less than or equal to @c 0,
 742         *                                       or a @c null value is passed. @n
 743         *                                                                               Note that, it is also possible that the data inside a registry instance is
 744         *                                                                               corrupted due to its usage in a multi-threaded environment without
 745         *                                                                               synchronization.
 746         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 747         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 748         * @remarks              This method will not add a name-value pair as an entry of a specific section
 749         *               if no entry with the specified name exists.
 750         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 751         * @see                  AddValue()
 752         */
 753         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double newValue);
 754
 755         /**
 756         * Modifies the value of the specified entry using the specified @c float value.
 757         *
 758         * @since                2.0
 759         *
 760         * @return               An error code
 761         * @param[in]    sectionName                             The section name
 762         * @param[in]    entryName                               The entry name to modify
 763         * @param[in]    newValue                                The @c float value
 764         * @exception    E_SUCCESS                               The method is successful.
 765         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 766         *                                       or an entry is less than or equal to @c 0,
 767         *                                       or a @c null value is passed. @n
 768         *                                                                               Note that, it is also possible that the data inside a registry instance is
 769         *                                                                               corrupted due to its usage in a multi-threaded environment without
 770         *                                                                               synchronization.
 771         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 772         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 773         * @remarks              This method will not add a name-value pair as an entry of a specific section
 774         *               if no entry with the specified name exists.
 775         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 776         * @see                  AddValue()
 777         */
 778         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float newValue);
 779
 780         /**
 781         * Modifies the value of the specified entry using the specified String value.
 782         *
 783         * @since                2.0
 784         *
 785         * @return               An error code
 786         * @param[in]    sectionName                             The section name
 787         * @param[in]    entryName                               The entry name to modify
 788         * @param[in]    newValue                                The String value
 789         * @exception    E_SUCCESS                               The method is successful.
 790         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 791         *                                       or an entry is less than or equal to @c 0.
 792         *                                                                               Note that, it is also possible that the data inside a registry instance is
 793         *                                                                               corrupted due to its usage in a multi-threaded environment without
 794         *                                                                               synchronization.
 795         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 796         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 797         * @remarks              This method will not add a name-value pair as an entry of a specific section
 798         *               if no entry with the specified name exists.
 799         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 800         * @see                  AddValue()
 801         */
 802         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& newValue);
 803
 804         /**
 805         * Modifies the value of the specified entry using the specified UuID value.
 806         *
 807         * @since                2.0
 808         *
 809         * @return               An error code
 810         * @param[in]    sectionName                             The section name
 811         * @param[in]    entryName                               The entry name to modify
 812         * @param[in]    newValue                                The UuId value
 813         * @exception    E_SUCCESS                               The method is successful.
 814         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 815         *                                       or an entry is less than or equal to @c 0,
 816         *                                       or a @c null value is passed. @n
 817         *                                                                               Note that, it is also possible that the data inside a registry instance is
 818         *                                                                               corrupted due to its usage in a multi-threaded environment without
 819         *                                                                               synchronization.
 820         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 821         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 822         * @remarks              This method will not add a name-value pair as an entry of a specific section if no
 823         *               entry with the specified name exists.
 824         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 825         * @see                  AddValue()
 826         */
 827         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& newValue);
 828
 829         /**
 830         * Modifies the value of the specified entry using the specified ByteBuffer value.
 831         *
 832         * @since                2.0
 833         *
 834         * @return               An error code
 835         * @param[in]    sectionName                             The section name
 836         * @param[in]    entryName                               The entry name to modify
 837         * @param[in]    newValue                                The @c ByteBuffer value
 838         * @exception    E_SUCCESS                               The method is successful.
 839         * @exception    E_INVALID_ARG                   Either the length of the specified string for a section
 840         *                                       or an entry is less than or equal to @c 0,
 841         *                                       or a @c null value is passed. @n
 842         *                                                                               Note that, it is also possible that the data inside a registry instance is
 843         *                                                                               corrupted due to its usage in a multi-threaded environment without
 844         *                                                                               synchronization.
 845         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 846         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 847         * @remarks              This method will not add a name-value pair as an entry of a specific section
 848         *               if no entry with the specified name exists.
 849         *                               In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 850         * @see                  AddValue()
 851         */
 852         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& newValue);
 853
 854         /**
 855         * Removes the name-value pair entry from specific section.
 856         *
 857         * @since                2.0
 858         *
 859         * @return               An error code
 860         * @param[in]    sectionName                             The section name
 861         * @param[in]    entryName                               The entry name to remove
 862         * @exception    E_SUCCESS                               The method is successful.
 863         * @exception    E_INVALID_ARG                   The length of the specified string for a section or entry is less
 864         *                                       than or equal to @c 0.
 865         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 866         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found within the registry.
 867         */
 868         result RemoveValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName);
 869
 870         /**
 871         * Removes the specified registry file.
 872         *
 873         * @if OSPCOMPAT
 874         * @brief <i> [Compatibility] </i>
 875         * @endif
 876         * @since                2.0
 877         * @if OSPCOMPAT
 878         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 879         *                                       For more information, see @ref CompIoPathPage "here".
 880         * @endif
 881         *
 882         * @return               An error code
 883         * @param[in]    regPath                                 The path of the registry file to remove
 884         * @exception    E_SUCCESS                               The method is successful.
 885         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 886         *                                                                               - The length of the specified string of a file path is less
 887         *                                                                                 than or equal to @c 0. @n
 888         *                                                                               - The translated overall length of the specified path exceeds the
 889         *                                                                                 system limitation. @n
 890         *                                                                               - The specified path is invalid. @n
 891         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 892         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 893         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 894         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 895         *                                                                               - %File corruption is detected.
 896         */
 897         static result Remove(const Tizen::Base::String& regPath);
 898
 899         /**
 900         * Converts a normal registry file to a secure registry file. @n
 901         * A secure registry file that is converted by this method can be shared among applications with the same key value.
 902         *
 903         * @if OSPCOMPAT
 904         * @brief <i> [Compatibility] </i>
 905         * @endif
 906         * @since 2.0
 907         * @if OSPCOMPAT
 908         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 909         *                                       For more information, see @ref CompIoPathPage "here".
 910         * @endif
 911         *
 912         * @return               An error code
 913         * @param[in]    plainRegPath                    The normal (non-encrypted) registry file path
 914         * @param[in]    secureRegPath                   The secure (encrypted) registry file path to create
 915         * @param[in]    key                                             A key that encrypts a secure registry file @n
 916         *                                                                               If the secure registry file is converted with a specific key value,
 917         *                                                                               applications can access the same secure registry file with the identical key value.
 918         * @exception    E_SUCCESS                               The method is successful.
 919         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 920         *                                                                               - The length of the specified string of a file path is less
 921         *                                                                                 than or equal to @c 0. @n
 922         *                                                                               - The translated overall length of the specified path exceeds the
 923         *                                                                                 system limitation. @n
 924         *                                                                               - The specified path is invalid. @n
 925         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 926         * @exception    E_FILE_ALREADY_EXIST    The specified file already exists.
 927         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 928         * @exception    E_INVALID_FORMAT                The input registry file contains '0x00' in the middle of the file.
 929         * @exception    E_PARSING_FAILED                The method has failed to parse the registry file.
 930         * @exception    E_STORAGE_FULL                  The disk space is full.
 931         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 932         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 933         *                                                                               - %File corruption is detected. @n
 934         *                                                                               - The number of opened files has exceeded the maximum limit.
 935         */
 936         static result ConvertToSecureRegistry(const Tizen::Base::String& plainRegPath, const Tizen::Base::String& secureRegPath, const Tizen::Base::ByteBuffer& key);
 937
 938 private:
 939         /**
 940         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 941         *
 942         * @since 2.0
 943         */
 944         Registry(const Registry& source);
 945
 946         /**
 947         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 948         *
 949         * @since 2.0
 950         */
 951         Registry& operator =(const Registry& source);
 952
 953         class _RegistryImpl* __pRegistryImpl;
 954
 955         friend class _RegistryImpl;
 956
 957 }; // Registry
 958
 959 }} // Tizen::Io
 960
 961 #endif //_FIO_REGISTRY_H_
 962