inc/FIoRegistry.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        FIoRegistry.h
  19  * @brief       This is the header file for the %Registry class.
  20  *
  21  * This header file contains the declarations of the %Registry class.
  22  */
  23
  24 #ifndef _FIO_REGISTRY_H_
  25 #define _FIO_REGISTRY_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseUuId.h>
  29 #include <FBaseByteBuffer.h>
  30 #include <FBaseColArrayList.h>
  31 #include <FBaseResult.h>
  32 #include <FBaseColIMap.h>
  33 #include <FIoFileLock.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 methods 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 methods 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. @n
 152         * For full construction, the Construct() method must be called right after calling this constructor.
 153         *
 154         * @since        2.0
 155         */
 156         Registry(void);
 157
 158         /**
 159         * This destructor overrides Tizen::Base::Object::~Object().
 160         *
 161         * @since        2.0
 162         */
 163         virtual ~Registry(void);
 164
 165         /**
 166         * @cond OSPDEPREC
 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:
 187         *                                                                               - The length of the specified file path string is less
 188         *                                                                                 than or equal to @c 0.
 189         *                                                                               - The overall length of the specified file path exceeds the
 190         *                                                                                 system limitation.
 191         *                                                                               - The specified file path is invalid.
 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 the 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:
 198         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 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 value for the open mode flag.
 204         * @endcond
 205         */
 206         result Construct(const Tizen::Base::String& regPath, bool createIfNotExist);
 207
 208         /**
 209         * @cond OSPDEPREC
 210         * Initializes this instance of %Registry with the specified parameters. @n
 211         * This method loads a registry file in the read-only or the read-write mode.
 212         *
 213         * @if OSPCOMPAT
 214         * @brief                        <i> [Deprecated] [Compatibility] </i>
 215         * @endif
 216         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 217         *                                       bool createParentDirectories=false) and Registry::Construct(const Tizen::Base::String& regPath, const Tizen::Base::String& openMode).
 218         * @since                        2.0
 219         * @if OSPCOMPAT
 220         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 221         *                                       For more information, see @ref CompIoPathPage "here".
 222         * @endif
 223         *
 224         * @return               An error code
 225         * @param[in]    regPath                                 The path of the registry file to open or create
 226         * @param[in]    openMode                                The flag specifying the file opening mode @n
 227         *                                       Currently, the following flags can be used in combination with
 228         *                                       the logical OR operator: @n
 229         *                                                                                (1) REG_OPEN_READ_ONLY @n
 230         *                                                                                (2) REG_OPEN_READ_WRITE @n
 231         *                                                                                (3) REG_OPEN_READ_WRITE | REG_OPEN_CREATE
 232         * @param[in]    option                                  This argument is reserved for future use. @n It is recommended to use @c 0.
 233         * @exception    E_SUCCESS                               The method is successful.
 234         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
 235         *                                                                               - The length of the specified file path string is less
 236         *                                                                                 than or equal to @c 0.
 237         *                                                                               - The overall length of the specified file path exceeds the
 238         *                                                                                 system limitation.
 239         *                                                                               - The specified file path is invalid.
 240         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 241         * @exception    E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 242         * @exception    E_END_OF_FILE                   The file pointer has reached the end of file.
 243         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 244         * @exception    E_STORAGE_FULL                  The disk space is full.
 245         * @exception    E_IO                                    Either of the following conditions has occurred:
 246         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 247         *                                                                               - %File corruption is detected.
 248         * @exception    E_INVALID_FORMAT                The input registry file contains '0x00' in the middle of the file.
 249         * @exception    E_PARSING_FAILED                The method has failed to parse the registry file.
 250         * @endcond
 251         */
 252         result Construct(const Tizen::Base::String& regPath, long openMode, long option);
 253
 254         /**
 255         * Initializes this instance of %Registry with the specified parameters. @n
 256         * This method opens an existing registry file or creates a new one according to the specified file opening mode,
 257         * loads the data of the registry file to system memory, and flushes the data to the storage when this instance
 258         * is released or Registry::Flush() is called.
 259         *
 260         * @since                2.0
 261         *
 262         * @return               An error code
 263         * @param[in]    regPath                         The path of the registry file to open or create
 264         * @param[in]    pOpenMode                       The file opening mode @n
 265         *                                                                       It can be one of the following:
 266         *                                                                       - r : Open for reading.
 267         *                                                                       - r+: Open for reading and writing.
 268         *                                                                       - w : Open for writing. The registry file is created if it does not exist,
 269         *                                                                                 otherwise it is truncated to zero length.
 270         *                                                                       - w+: Open for writing and reading. The registry file is created if it does not exist,
 271         *                                                                                 otherwise it is truncated to zero length.
 272         *                                                                       - a : Open for writing. The registry file is created if it does not exist.
 273         *                                                                       - a+: Open for writing and reading. The registry file is created if it does not exist.
 274         * @exception    E_SUCCESS                       The method is successful.
 275         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 276         *                                                               - The length of the specified file path string is less than or equal to @c 0.
 277         *                                                               - The overall length of the specified file path exceeds the system limitation.
 278         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 279         * @exception    E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
 280         * @exception    E_FILE_NOT_FOUND        The specified @c regPath cannot be found.
 281         * @exception    E_INVALID_FORMAT        Either of the following conditions has occurred:
 282         *                                                                       - The section or entry name of the registry file includes one of the following characters:
 283         *                                                                       '\0', '\\n', '#' and '='.
 284         *                                                                       - The entry value of the registry file includes one of the following characters:
 285         *                                                                       '\0' and '\\n'.
 286         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 287         * @exception    E_STORAGE_FULL          The disk space is full.
 288         * @exception    E_IO                            Either of the following conditions has occurred:
 289         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 290         *                                                                       - %File corruption is detected.
 291         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 292         */
 293         result Construct(const Tizen::Base::String& regPath, const char* pOpenMode);
 294
 295         /**
 296         * Initializes this instance of %Registry with the specified parameters. @n
 297         * This method opens an existing secure registry file or creates a new one according to the specified file opening mode,
 298         * loads the data of the secure registry file to system memory and flushes the data to the storage when this instance
 299         * is released or Registry::Flush() is called.
 300         * The contents written to the secure registry file is automatically encrypted and the contents read from the secure registry
 301         * file is automatically decrypted by the platform. @n
 302         * Applications that use this method can access the secure registry files that are created by other applications with
 303         * an identical key value in the same device. However, the secure registry files created by this method cannot be accessed in other devices.
 304         *
 305         * @since                2.0
 306         *
 307         * @return               An error code
 308         * @param[in]    regPath                         The path of the registry file to open or create
 309         * @param[in]    pOpenMode                       The file opening mode @n
 310         *                                                                       It can be one of the following:
 311         *                                                                       - r : Open for reading.
 312         *                                                                       - r+: Open for reading and writing.
 313         *                                                                       - w : Open for writing. The registry file is created if it does not exist,
 314         *                                                                                 otherwise it is truncated to zero length.
 315         *                                                                       - w+: Open for writing and reading. The registry file is created if it does not exist,
 316         *                                                                                 otherwise it is truncated to zero length.
 317         *                                                                       - a : Open for writing. The registry file is created if it does not exist.
 318         *                                                                       - a+: Open for writing and reading. The registry file is created if it does not exist.
 319         * @param[in]    secretKey                       The key to encrypt the data of the registry file or to decrypt the secure registry file @n
 320         *                                                                       If the secure registry file is created with a specific key value,
 321         *                                                                       other applications can access the secure registry file with an identical key value.
 322         * @exception    E_SUCCESS                       The method is successful.
 323         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 324         *                                                                       - The overall length of the specified path is equal to @c 0 or
 325         *                                                                         exceeds system limitations.
 326         *                                                                       - The combination of the specified @c pOpenMode is not allowed.
 327         *                                                                       - The specified @c secretKey is incorrect or the secure registry file is corrupted.
 328         * @exception    E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
 329         * @exception    E_FILE_NOT_FOUND        The specified @c regPath cannot be found.
 330         * @exception    E_INVALID_FORMAT        Either of the following conditions has occurred:
 331         *                                                                       - The section or entry name of the registry file includes one of the following characters:
 332         *                                                                       '\0', '\\n', '#' and '='.
 333         *                                                                       - The entry value of the registry file includes one of the following characters:
 334         *                                                                       '\0' and '\\n'.
 335         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 336         * @exception    E_STORAGE_FULL          The disk space is full.
 337         * @exception    E_IO                            Either of the following conditions has occurred:
 338         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 339         *                                                                       - %File corruption is detected.
 340         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 341         */
 342         result Construct(const Tizen::Base::String& regPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
 343
 344         /**
 345         * Flushes the current contents of the registry in memory. @n
 346         * If the secure mode is set, the contents of the registry are automatically encrypted
 347         * and saved by the platform.
 348         *
 349         * @since                2.0
 350         *
 351         * @return               An error code
 352         * @exception    E_SUCCESS                               The method is successful.
 353         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 354         * @exception    E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 355         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 356         * @exception    E_STORAGE_FULL                  The disk space is full.
 357         * @exception    E_IO                                    Either of the following conditions has occurred:
 358         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 359         *                                                                               - %File corruption is detected.
 360         */
 361         result Flush(void);
 362
 363         /**
 364         * Creates the specified section and adds it to the registry.
 365         *
 366         * @since                2.0
 367         *
 368         * @return               An error code
 369         * @param[in]    sectionName                             The section name
 370         * @exception    E_SUCCESS                               The method is successful.
 371         * @exception    E_INVALID_ARG                   The length of the specified string for a section name is less than or equal to @c 0.
 372         * @exception    E_SECTION_ALREADY_EXIST The section with the specified name already exists.
 373         */
 374         result AddSection(const Tizen::Base::String& sectionName);
 375
 376         /**
 377         * Removes the section from the registry.
 378         *
 379         * @since                2.0
 380         *
 381         * @return               An error code
 382         * @param[in]    sectionName                             The name of the section to remove
 383         * @exception    E_SUCCESS                               The method is successful.
 384         * @exception    E_INVALID_ARG                   The length of the specified string for a section is less than or equal to @c 0.
 385         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found within the registry.
 386         */
 387         result RemoveSection(const Tizen::Base::String& sectionName);
 388
 389         /**
 390         * Gets all the section names in the registry.
 391         *
 392         * @since                2.0
 393         *
 394         * @return               The list of all section names in the registry @n
 395         *                               If this method fails, @c null value is returned. @n
 396         *                               When there are no sections, the method returns an empty list instance. @n
 397         *                               Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of elements in the list.
 398         * @exception    E_SUCCESS                               The method is successful.
 399         * @remarks
 400         *                               - Do not forget to delete not only the returned Tizen::Base::Collection::IList instance, but also its contents by invoking IList::RemoveAll().
 401         *                               - The specific error code can be accessed using the GetLastResult() method.
 402         */
 403         Tizen::Base::Collection::IList* GetAllSectionNamesN(void) const;
 404
 405         /**
 406         * Gets all the entry names in the specified section of the registry.
 407         *
 408         * @since                2.0
 409         *
 410         * @return               The list of entry names @n
 411         *                               If this method fails, @c null value is returned. @n
 412         *                               When there are no entries, the method returns an empty list instance. @n
 413         *                               Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of element in the list.
 414         * @param[in]    sectionName                             The section name
 415         * @exception    E_SUCCESS                               The method is successful.
 416         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 417         * @exception    E_IO                                    A system error has occurred.
 418         * @remarks
 419         *                               - Do not forget to delete not only the returned Tizen::Base::Collection::IList instance, but also its contents by invoking IList::RemoveAll().
 420         *                               - The specific error code can be accessed using the GetLastResult() method.
 421         */
 422         Tizen::Base::Collection::IList* GetAllEntryNamesN(const Tizen::Base::String& sectionName) const;
 423
 424         /**
 425         * Adds the name and integer value as an entry of the specific section.
 426         *
 427         * @since                2.0
 428         *
 429         * @return               An error code
 430         * @param[in]    sectionName                             The section name
 431         * @param[in]    entryName                               The entry name
 432         * @param[in]    value                                   The @c int value
 433         * @exception    E_SUCCESS                               The method is successful.
 434         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 435         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 436         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 437         */
 438         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int value);
 439
 440         /**
 441         * Adds the name and double value as an entry of the specific section.
 442         *
 443         * @since                2.0
 444         *
 445         * @return               An error code
 446         * @param[in]    sectionName                             The section name
 447         * @param[in]    entryName                               The entry name
 448         * @param[in]    value                                   The @c double value
 449         * @exception    E_SUCCESS                               The method is successful.
 450         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 451         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 452         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 453         * @remarks      This method converts the specified double type @c value to string value using the "%lg" format specifier. @n
 454         *                       It does not depend on the system locale.
 455         */
 456         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double value);
 457
 458         /**
 459         * Adds the name and float value as an entry of the specific section.
 460         *
 461         * @since                2.0
 462         *
 463         * @return               An error code
 464         * @param[in]    sectionName                             The section name
 465         * @param[in]    entryName                               The entry name
 466         * @param[in]    value                                   The @c float value
 467         * @exception    E_SUCCESS                               The method is successful.
 468         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 469         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 470         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 471         * @remarks      This method converts the specified float type @c value to string value using the "%g" format specifier. @n
 472         *                       It does not depend on the system locale.
 473         */
 474         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float value);
 475
 476         /**
 477         * Adds the name and String value as an entry of the specific section.
 478         *
 479         * @since                2.0
 480         *
 481         * @return               An error code
 482         * @param[in]    sectionName                             The section name
 483         * @param[in]    entryName                               The entry name
 484         * @param[in]    value                                   The String value
 485         * @exception    E_SUCCESS                               The method is successful.
 486         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 487         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 488         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 489         */
 490         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& value);
 491
 492         /**
 493         * Adds the name and UuId value as an entry for the specified section.
 494         *
 495         * @since                2.0
 496         *
 497         * @return               An error code
 498         * @param[in]    sectionName                             The section name
 499         * @param[in]    entryName                               The entry name
 500         * @param[in]    value                                   The UuId value
 501         * @exception    E_SUCCESS                               The method is successful.
 502         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 503         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 504         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 505         */
 506         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& value);
 507
 508         /**
 509         * Adds the name and ByteBuffer value as an entry for the specified section.
 510         *
 511         * @since                2.0
 512         *
 513         * @return               An error code
 514         * @param[in]    sectionName                             The section name
 515         * @param[in]    entryName                               The entry name
 516         * @param[in]    value                                   The ByteBuffer value @n
 517         *                                       Note that, it should be constructed before being passed to the method.
 518         * @exception    E_SUCCESS                               The method is successful.
 519         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 520         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 521         * @exception    E_KEY_ALREADY_EXIST             The specified @c entryName already exists in this section.
 522         * @remarks      All the contents of @c ByteBuffer are saved as an entry value. That is, byte data from @c 0 up to the buffer limit is saved.
 523         * @see                  Tizen::Base::ByteBuffer
 524         */
 525         result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& value);
 526
 527         /**
 528         * Gets the @c int value of the specified entry.
 529         *
 530         * @since                2.0
 531         *
 532         * @return               An error code
 533         * @param[in]    sectionName                             The section name
 534         * @param[in]    entryName                               The entry name to get the value
 535         * @param[out]   retVal                                  The return value obtained from the registry
 536         * @exception    E_SUCCESS                               The method is successful.
 537         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 538         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 539         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 540         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 541         *                                                                               - The method has failed to parse the encoded entry value string.
 542         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 543         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 544         *                                                                               If the value is retrieved using the ::REGTYPE_STRING type,
 545         *                                                                               an empty string is returned even if no value is assigned.
 546         */
 547         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int& retVal) const;
 548
 549         /**
 550         * Gets the @c double value of the specified entry.
 551         *
 552         * @since                2.0
 553         *
 554         * @return               An error code
 555         * @param[in]    sectionName                             The section name
 556         * @param[in]    entryName                               The entry name to get the value
 557         * @param[out]   retVal                                  The return value obtained from the registry
 558         * @exception    E_SUCCESS                               The method is successful.
 559         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 560         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 561         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 562         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 563         *                                                                               - The method has failed to parse the encoded entry value string.
 564         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 565         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 566         *                                                                               If the value is retrieved using the REGTYPE_STRING type,
 567         *                                                                               an empty string is returned even if no value is assigned.
 568         * @remarks              This method does not depend on the system locale.
 569         */
 570         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double& retVal) const;
 571
 572         /**
 573         * Gets the @c float value of the specified entry.
 574         *
 575         * @since                2.0
 576         *
 577         * @return               An error code
 578         * @param[in]    sectionName                             The section name
 579         * @param[in]    entryName                               The entry name to get the value
 580         * @param[out]   retVal                                  The return value obtained from the registry
 581         * @exception    E_SUCCESS                               The method is successful.
 582         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 583         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 584         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 585         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 586         *                                                                               - The method has failed to parse the encoded entry value string.
 587         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 588         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 589         *                                                                               If the value is retrieved using the REGTYPE_STRING type,
 590         *                                                                               an empty string is returned even if no value is assigned.
 591         * @remarks              This method does not depend on the system locale.
 592         */
 593         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float& retVal) const;
 594
 595         /**
 596         * Gets the String value of a specific entry.
 597         *
 598         * @since                2.0
 599         *
 600         * @return               An error code
 601         * @param[in]    sectionName                             The section name
 602         * @param[in]    entryName                               The entry name to get the value
 603         * @param[out]   retVal                                  The return value obtained from the registry
 604         * @exception    E_SUCCESS                               The method is successful.
 605         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 606         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 607         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 608         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 609         *                                                                               - The method has failed to parse the encoded entry value string.
 610         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 611         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 612         *                                                                               If the value is retrieved using the ::REGTYPE_STRING type,
 613         *                                                                               an empty string is returned even if no value is assigned.
 614         */
 615         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::String& retVal) const;
 616
 617         /**
 618         * Gets the UuId value of the specified entry.
 619         *
 620         * @since                2.0
 621         *
 622         * @return               An error code
 623         * @param[in]    sectionName                             The section name
 624         * @param[in]    entryName                               The entry name to get the value
 625         * @param[out]   retVal                                  The return value obtained from the registry
 626         * @exception    E_SUCCESS                               The method is successful.
 627         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 628         * @exception    E_SECTION_NOT_FOUND         The specified @c sectionName is not found in the registry.
 629         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 630         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 631         *                                                                               - The method has failed to parse the encoded entry value string.
 632         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 633         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 634         *                                                                               If the value is retrieved using the ::REGTYPE_STRING type,
 635         *                                                                               an empty string is returned even if no value is assigned.
 636         */
 637         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::UuId& retVal) const;
 638
 639         /**
 640         * Gets the ByteBuffer value of the specified entry.
 641         *
 642         * @since                2.0
 643         *
 644         * @return               An error code
 645         * @param[in]    sectionName                             The section name
 646         * @param[in]    entryName                               The entry name to get
 647         * @param[out]   retVal                                  The return value obtained from the registry
 648         * @exception    E_SUCCESS                               The method is successful.
 649         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 650         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 651         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 652         * @exception    E_PARSING_FAILED                Either of the following conditions has occurred:
 653         *                                                                               - The method has failed to parse the encoded entry value string.
 654         *                                                                               - The specified data type of the value and the data type of the retrieved value are different.
 655         * @exception    E_DATA_NOT_FOUND                There is no value assigned for the specified entry name. @n
 656         *                                                                               If the value is retrieved using the ::REGTYPE_STRING type,
 657         *                                                                               an empty string is returned even if no value is assigned.
 658         * @remarks              Decide the size of the byte data to be fecthed and construct the Tizen::Base::ByteBuffer before passing it to the method. @n
 659         *                               When the %Tizen::Base::ByteBuffer capacity is less than the actual binary data stored in the registry,
 660         *                               this method reads data that fits the %Tizen::Base::ByteBuffer capacity. The position of the %Tizen::Base::ByteBuffer and
 661         *                               limit are not changed. @n
 662         *                               When the %Tizen::Base::ByteBuffer capacity is greater than the actual data size,
 663         *                               the method reads the whole data and adjusts the limit of the buffer accordingly.
 664         * @see                  Tizen::Base::ByteBuffer
 665         */
 666         result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::ByteBuffer& retVal) const;
 667
 668         /**
 669         * Sets the @c int value for the specified entry.
 670         *
 671         * @since                2.0
 672         *
 673         * @return               An error code
 674         * @param[in]    sectionName                             The section name
 675         * @param[in]    entryName                               The entry name to set the value
 676         * @param[in]    newValue                                The @c int value
 677         * @exception    E_SUCCESS                               The method is successful.
 678         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 679         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 680         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 681         * @remarks      This method will not set the specified value as an entry of the specific section
 682         *                       if no entry with the specified name exists. @n
 683         *                       In such a case, it returns @c E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 684         * @see                  AddValue()
 685         */
 686         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int newValue);
 687
 688         /**
 689         * Sets the @c double value for the specified entry.
 690         *
 691         * @since                2.0
 692         *
 693         * @return               An error code
 694         * @param[in]    sectionName                             The section name
 695         * @param[in]    entryName                               The entry name to set the value
 696         * @param[in]    newValue                                The @c double value
 697         * @exception    E_SUCCESS                               The method is successful.
 698         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 699         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 700         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 701         * @remarks
 702         *                               - This method will not set the specified value as an entry of the specific section
 703         *                               if no entry with the specified name exists. @n
 704         *                               In such a case, it returns @c E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 705         *                               - This method converts the specified double type @c newValue to string value using the "%lg" format specifier.  @n
 706         *                               It does not depend on the system locale.
 707         * @see                  AddValue()
 708         */
 709         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double newValue);
 710
 711         /**
 712         * Sets the @c float value for the specified entry.
 713         *
 714         * @since                2.0
 715         *
 716         * @return               An error code
 717         * @param[in]    sectionName                             The section name
 718         * @param[in]    entryName                               The entry name to set the value
 719         * @param[in]    newValue                                The @c float value
 720         * @exception    E_SUCCESS                               The method is successful.
 721         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 722         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 723         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 724         * @remarks
 725         *                               - This method will not set the specified value as an entry of the specific section
 726         *                               if no entry with the specified name exists. @n
 727         *                               In such a case, it returns @c E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 728         *                               - This method converts the specified float type @c newValue to string value using the "%g" format specifier. @n
 729         *                               It does not depend on the system locale.
 730         * @see                  AddValue()
 731         */
 732         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float newValue);
 733
 734         /**
 735         * Sets the String value for the specified entry.
 736         *
 737         * @since                2.0
 738         *
 739         * @return               An error code
 740         * @param[in]    sectionName                             The section name
 741         * @param[in]    entryName                               The entry name to set the value
 742         * @param[in]    newValue                                The String value
 743         * @exception    E_SUCCESS                               The method is successful.
 744         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 745         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 746         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 747         * @remarks      This method will not set the specified value as an entry of the specific section
 748         *                       if no entry with the specified name exists. @n
 749         *                       In such a case, it returns @c E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 750         * @see                  AddValue()
 751         */
 752         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& newValue);
 753
 754         /**
 755         * Sets the UuId value for the specified entry.
 756         *
 757         * @since                2.0
 758         *
 759         * @return               An error code
 760         * @param[in]    sectionName                             The section name
 761         * @param[in]    entryName                               The entry name to set the value
 762         * @param[in]    newValue                                The UuId value
 763         * @exception    E_SUCCESS                               The method is successful.
 764         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 765         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 766         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 767         * @remarks      This method will not set the specified value as an entry of the specific section
 768         *                       if no entry with the specified name exists. @n
 769         *                       In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 770         * @see                  AddValue()
 771         */
 772         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& newValue);
 773
 774         /**
 775         * Sets the ByteBuffer value for the specified entry.
 776         *
 777         * @since                2.0
 778         *
 779         * @return               An error code
 780         * @param[in]    sectionName                             The section name
 781         * @param[in]    entryName                               The entry name to set the value
 782         * @param[in]    newValue                                The @c ByteBuffer value
 783         * @exception    E_SUCCESS                               The method is successful.
 784         * @exception    E_INVALID_ARG                   The length of the specified section name or entry name is less than or equal to @c 0.
 785         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 786         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 787         * @remarks      This method will not set the specified value as an entry of the specific section
 788         *                       if no entry with the specified name exists. @n
 789         *                       In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
 790         * @see                  AddValue()
 791         */
 792         result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& newValue);
 793
 794         /**
 795         * Removes the name-value pair entry from specified section.
 796         *
 797         * @since                2.0
 798         *
 799         * @return               An error code
 800         * @param[in]    sectionName                             The section name
 801         * @param[in]    entryName                               The entry name to remove
 802         * @exception    E_SUCCESS                               The method is successful.
 803         * @exception    E_INVALID_ARG                   The length of the specified string for a section or entry is less
 804         *                                       than or equal to @c 0.
 805         * @exception    E_SECTION_NOT_FOUND             The specified @c sectionName is not found in the registry.
 806         * @exception    E_KEY_NOT_FOUND                 The specified @c entryName is not found in the registry.
 807         */
 808         result RemoveValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName);
 809
 810         /**
 811         * Acquires the file lock on the current opened whole file if it is not acquired.
 812         * If the file lock is already acquired by another process, the current process is blocked until the file lock is
 813         * released.
 814         *
 815         * @since                        2.1
 816         *
 817         * @return           The pointer to the FileLock instance, @n
 818         *                                       else @c null pointer in case of failure
 819         * @param[in]            lockType                                The file lock type to be created
 820         * @exception            E_SUCCESS                               The method is successful.
 821         * @exception            E_INVALID_ARG                   The specified @c lockType is invalid.
 822         * @exception            E_INVALID_OPERATION             Either of the following conditions has occurred:
 823         *                                                                                       - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
 824         *                                                                                         file is not open for reading.
 825         *                                                                                       - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
 826         *                                                                                         file is not open for writing.
 827         * @exception            E_WOULD_DEADLOCK                The method would cause a deadlock. @n
 828         *                                                                                       The lock is blocked by a lock from another process, and putting the
 829         *                                                                                       calling process to sleep to wait for that lock to become free would
 830         *                                                                                       cause a deadlock.
 831         * @exception            E_MAX_EXCEEDED                  The number of file locks has exceeded system limitations.
 832         * @exception            E_SYSTEM                                The method cannot proceed due to a severe system error.
 833         * @remarks
 834         *                                       - The FileLock instance is invalid if the associated %File instance is deleted.
 835         *                                       - The specific error code can be accessed using the GetLastResult() method.
 836         */
 837         FileLock* LockN(FileLockType lockType);
 838
 839         /**
 840         * Tries to acquire the file lock on the current opened whole file.
 841         * If the file lock is already acquired by another process, @c E_OBJECT_LOCKED is returned.
 842         *
 843         * @since                        2.1
 844         *
 845         * @return                       The pointer to the FileLock instance, @n
 846         *                                       else @c null pointer in case of failure
 847         * @param[in]            lockType                                The type of file lock to be created
 848         * @exception            E_SUCCESS                               The method is successful.
 849         * @exception            E_INVALID_ARG                   The specified @c lockType is invalid.
 850         * @exception            E_INVALID_OPERATION             Either of the following conditions has occurred:
 851         *                                                                                       - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
 852         *                                                                                         file is not open for reading.
 853         *                                                                                       - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
 854         *                                                                                         file is not open for writing.
 855         * @exception            E_OBJECT_LOCKED                 Either of the following conditions has occurred:
 856         *                                                                                       - The file lock is already held by another process.
 857         *                                                                                       - The file to be locked has been memory-mapped by another process.
 858         * @exception            E_MAX_EXCEEDED                  The number of file locks has exceeded system limitations.
 859         * @exception            E_SYSTEM                                The method cannot proceed due to a severe system error.
 860         * @remarks
 861         *                                       - The FileLock instance is invalid if the associated %File instance is deleted.
 862         *                                       - The specific error code can be accessed using the GetLastResult() method.
 863         */
 864         FileLock* TryToLockN(FileLockType lockType);
 865
 866         /**
 867         * Removes the specified registry file.
 868         *
 869         * @if OSPCOMPAT
 870         * @brief <i> [Compatibility] </i>
 871         * @endif
 872         * @since                2.0
 873         * @if OSPCOMPAT
 874         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 875         *                                       For more information, see @ref CompIoPathPage "here".
 876         * @endif
 877         *
 878         * @return               An error code
 879         * @param[in]    regPath                                 The path of the registry file to remove
 880         * @exception    E_SUCCESS                               The method is successful.
 881         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
 882         *                                                                               - The length of the specified string of a file path is less
 883         *                                                                                 than or equal to @c 0.
 884         *                                                                               - The overall length of the specified path exceeds the
 885         *                                                                                 system limitation.
 886         *                                                                               - The specified path is invalid.
 887         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 888         * @exception    E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 889         * @exception    E_IO                                    Either of the following conditions has occurred:
 890         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 891         *                                                                               - %File corruption is detected.
 892         */
 893         static result Remove(const Tizen::Base::String& regPath);
 894
 895         /**
 896         * Converts a normal registry file to a secure registry file. @n
 897         * A secure registry file that is converted by this method can be shared among applications with the same key value.
 898         *
 899         * @if OSPCOMPAT
 900         * @brief <i> [Compatibility] </i>
 901         * @endif
 902         * @since 2.0
 903         * @if OSPCOMPAT
 904         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 905         *                                       For more information, see @ref CompIoPathPage "here".
 906         * @endif
 907         *
 908         * @return               An error code
 909         * @param[in]    plainRegPath                    The normal (non-encrypted) registry file path
 910         * @param[in]    secureRegPath                   The secure (encrypted) registry file path to create
 911         * @param[in]    key                                             The key that encrypts the secure registry file @n
 912         *                                                                               If the secure registry file is converted with the specific key value,
 913         *                                                                               applications can access the same secure registry file with an identical key value.
 914         * @exception    E_SUCCESS                               The method is successful.
 915         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
 916         *                                                                               - The length of the specified string of a file path is less
 917         *                                                                                 than or equal to @c 0.
 918         *                                                                               - The overall length of the specified path exceeds the
 919         *                                                                                 system limitation.
 920         *                                                                               - The specified path is invalid.
 921         * @exception    E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 922         * @exception    E_FILE_ALREADY_EXIST    The specified file already exists.
 923         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 924         * @exception    E_INVALID_FORMAT                The input registry file contains '0x00' in the middle of the file.
 925         * @exception    E_PARSING_FAILED                The method has failed to parse the registry file.
 926         * @exception    E_STORAGE_FULL                  The disk space is full.
 927         * @exception    E_IO                                    Either of the following conditions has occurred:
 928         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 929         *                                                                               - %File corruption is detected.
 930         *                                                                               - The number of opened files has exceeded the maximum limit.
 931         */
 932         static result ConvertToSecureRegistry(const Tizen::Base::String& plainRegPath, const Tizen::Base::String& secureRegPath, const Tizen::Base::ByteBuffer& key);
 933
 934 private:
 935         /**
 936         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 937         *
 938         * @since 2.0
 939         */
 940         Registry(const Registry& source);
 941
 942         /**
 943         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 944         *
 945         * @since 2.0
 946         */
 947         Registry& operator =(const Registry& source);
 948
 949         class _RegistryImpl* __pRegistryImpl;
 950
 951         friend class _RegistryImpl;
 952
 953 }; // Registry
 954
 955 }} // Tizen::Io
 956
 957 #endif //_FIO_REGISTRY_H_
 958