2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @brief This is the header file for the %Registry class.
21 * This header file contains the declarations of the %Registry class.
24 #ifndef _FIO_REGISTRY_H_
25 #define _FIO_REGISTRY_H_
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>
35 namespace Tizen {namespace Base
41 namespace Tizen { namespace Io
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;
50 * @brief This class provides a mechanism to access and manipulate registry files.
54 * @final This class is not intended for extension.
56 * The %Registry class provides a mechanism to access and manipulate registry files.
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>.
61 * The following example demonstrates how to use the %Registry class.
68 using namespace Tizen::Base;
69 using namespace Tizen::Io;
70 using namespace Tizen::App;
76 String regPathName(L"regTest.ini");
79 String sect1(L"section1");
80 String sect2(L"section2");
81 String sect3(L"section3");
84 String entry1(L"entry1");
85 String entry2(L"entry2");
90 r = reg.Construct(App::GetInstance()->GetAppDataPath() + regPathName, "a+");
97 r = reg.AddSection(sect1);
98 r = reg.AddSection(sect2);
99 r = reg.AddSection(sect3);
101 // Add value: section1 { entry1 = 999 }
102 r = reg.AddValue(sect1, entry1, 999);
108 // Change value: section1 { entry1 = 3 }
109 r = reg.SetValue(sect1, entry1, 3);
115 // Add value: section2 { entry2 = 1.1234599 }
116 r = reg.AddValue(sect2, entry2, 1.1234599);
122 // Get value: section1 { entry1 = ? }
123 r = reg.GetValue(sect1, entry1, iVal);
139 // Do some error handling
145 class _OSP_EXPORT_ Registry
146 : public Tizen::Base::Object
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.
158 * This destructor overrides Tizen::Base::Object::~Object().
162 virtual ~Registry(void);
167 * Initializes this instance of %Registry with the specified parameters. @n
168 * This method loads a registry file in the read-write mode.
171 * @brief <i> [Deprecated] [Compatibility] </i>
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).
177 * @compatibility This method has compatibility issues with OSP compatible applications. @n
178 * For more information, see @ref CompIoPathPage "here".
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.
207 result Construct(const Tizen::Base::String& regPath, bool createIfNotExist);
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.
216 * @brief <i> [Deprecated] [Compatibility] </i>
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).
222 * @compatibility This method has compatibility issues with OSP compatible applications. @n
223 * For more information, see @ref CompIoPathPage "here".
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.
255 result Construct(const Tizen::Base::String& regPath, long openMode, long option);
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.
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 writing. The registry file is created if it does not exist.
276 * - a+: Open for writing 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:
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.
296 result Construct(const Tizen::Base::String& regPath, const char* pOpenMode);
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.
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 writing. The registry file is created if it does not exist.
321 * - a+: Open for writing 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:
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.
345 result Construct(const Tizen::Base::String& regPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
348 * Flushes the current contents of a registry in memory. @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.
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
367 * Creates the specified section then adds it into the registry.
371 * @return An error code
372 * @param[in] sectionName The section name
373 * @exception E_SUCCESS The method is successful.
374 * @exception E_INVALID_ARG The length of the specified string for a section name is less than
376 * @exception E_SECTION_ALREADY_EXIST A section with the specified name already exists.
378 result AddSection(const Tizen::Base::String& sectionName);
381 * Removes the section from %Registry.
385 * @return An error code
386 * @param[in] sectionName The section name to remove
387 * @exception E_SUCCESS The method is successful.
388 * @exception E_INVALID_ARG The length of the specified string for a section is less than
390 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
392 result RemoveSection(const Tizen::Base::String& sectionName);
395 * Gets all section names in the registry.
399 * @return A list of section names @n
400 * If this method fails, @c null value is returned. @n
401 * The specific error code can be accessed using the GetLastResult() method. @n
402 * When there are no sections at all, the method returns an empty list instance. @n
403 * Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of elements in the list.
404 * @exception E_SUCCESS The method is successful.
405 * @remarks Do not forget to delete not only the returned IList instance, but also its
406 * contents by invoking IList::RemoveAll(). @n
407 * The specific error code can be accessed using the GetLastResult() method.
409 Tizen::Base::Collection::IList* GetAllSectionNamesN(void) const;
412 * Gets all entry names in the specified section of the registry.
416 * @return A list of entry names @n
417 * If this method fails, @c null value is returned. @n
418 * When there are no entries at all, the method returns an empty list instance. @n
419 * Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of element in the list.
420 * @param[in] sectionName The section name
421 * @exception E_SUCCESS The method is successful.
422 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
423 * @exception E_IO A system error has occurred.
424 * @remarks Do not forget to delete not only the returned IList instance, but also its
425 * contents by invoking IList::RemoveAll(). @n
426 * The specific error code can be accessed using the GetLastResult() method.
428 Tizen::Base::Collection::IList* GetAllEntryNamesN(const Tizen::Base::String& sectionName) const;
431 * Adds the name-value pair of type integer as an entry of the specific section.
435 * @return An error code
436 * @param[in] sectionName The section name
437 * @param[in] entryName The entry name
438 * @param[in] value The @c int value
439 * @exception E_SUCCESS The method is successful.
440 * @exception E_INVALID_ARG Either the length of the specified string for a section
441 * or an entry is less than or equal to @c 0,
442 * or a @c null value is passed. @n
443 * Note that, it is also possible that the data inside a registry instance is
444 * corrupted due to its usage in a multi-threaded environment without
446 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
447 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
449 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int value);
452 * Adds the name-value pair of type double as an entry of the specific section.
456 * @return An error code
457 * @param[in] sectionName The section name
458 * @param[in] entryName The entry name
459 * @param[in] value The @c double value
460 * @exception E_SUCCESS The method is successful.
461 * @exception E_INVALID_ARG Either the length of the specified string for a section
462 * or an entry is less than or equal to @c 0,
463 * or a @c null value is passed. @n
464 * Note that, it is also possible that the data inside a registry instance is
465 * corrupted due to its usage in a multi-threaded environment without
467 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
468 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
469 * @remarks This method converts the specified double type @c value to string value using "%lg" format specifier. @n
470 * Also, it does not depend on system locale.
472 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double value);
475 * Adds the name-value pair of type float as an entry of the specific section.
479 * @return An error code
480 * @param[in] sectionName The section name
481 * @param[in] entryName The entry name
482 * @param[in] value The @c float value
483 * @exception E_SUCCESS The method is successful.
484 * @exception E_INVALID_ARG Either the length of the specified string for a section
485 * or an entry is less than or equal to @c 0,
486 * or a @c null value is passed. @n
487 * Note that, it is also possible that the data inside a registry instance is
488 * corrupted due to its usage in a multi-threaded environment without
490 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
491 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
492 * @remarks This method converts the specified float type @c value to string value using "%g" format specifier. @n
493 * Also, it does not depend on system locale.
495 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float value);
498 * Adds the name-value pair of type String as an entry of the specific section.
502 * @return An error code
503 * @param[in] sectionName The section name
504 * @param[in] entryName The entry name
505 * @param[in] value The String value
506 * @exception E_SUCCESS The method is successful.
507 * @exception E_INVALID_ARG Either the length of the specified string for a section
508 * or an entry is less than or equal to @c 0.
509 * Note that, it is also possible that the data inside a registry instance is
510 * corrupted due to its usage in a multi-threaded environment without
512 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
513 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
515 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& value);
518 * Adds the name-value pair of type UuId as an entry for the specified section.
522 * @return An error code
523 * @param[in] sectionName The section name
524 * @param[in] entryName The entry name
525 * @param[in] value The UuId value
526 * @exception E_SUCCESS The method is successful.
527 * @exception E_INVALID_ARG Either the length of the specified string for a section
528 * or an entry is less than or equal to @c 0,
529 * or a @c null value is passed. @n
530 * Note that, it is also possible that the data inside a registry instance is
531 * corrupted due to its usage in a multi-threaded environment without
533 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
534 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
536 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& value);
539 * Adds the name-value pair of type ByteBuffer as an entry for the specified section.
543 * @return An error code
544 * @param[in] sectionName The section name
545 * @param[in] entryName The entry name
546 * @param[in] value The @c ByteBuffer value @n
547 * Note that, it should be constructed before being passed to the method.
548 * @exception E_SUCCESS The method is successful.
549 * @exception E_INVALID_ARG Either the length of the specified string for a section
550 * or an entry is less than or equal to @c 0,
551 * or a @c null value is passed. @n
552 * Note that, it is also possible that the data inside a registry instance is
553 * corrupted due to its usage in a multi-threaded environment without
555 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
556 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
557 * @remarks Note that all the contents of @c ByteBuffer are saved as an entry value.
558 * That is, byte data from @c 0 up to the buffer limit is saved.
559 * @see Tizen::Base::ByteBuffer
561 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& value);
564 * Gets the @c int value of the specified entry.
568 * @return An error code
569 * @param[in] sectionName The section name
570 * @param[in] entryName The name of entry where its value will be fetched
571 * @param[out] retVal The return value obtained from the registry
572 * @exception E_SUCCESS The method is successful.
573 * @exception E_INVALID_ARG Either the length of the specified string for a section
574 * or an entry is less than or equal to @c 0,
575 * or a @c null value is passed. @n
576 * Note that, it is also possible that the data inside a registry instance is
577 * corrupted due to its usage in a multi-threaded environment without
579 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
580 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
581 * @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.
582 * @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).
584 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int& retVal) const;
587 * Gets the @c double value of the specified entry.
591 * @return An error code
592 * @param[in] sectionName The section name
593 * @param[in] entryName The name of entry where its value will be fetched
594 * @param[out] retVal The return value obtained from the registry
595 * @exception E_SUCCESS The method is successful.
596 * @exception E_INVALID_ARG Either the length of the specified string for a section
597 * or an entry is less than or equal to @c 0,
598 * or a @c null value is passed. @n
599 * Note that, it is also possible that the data inside a registry instance is
600 * corrupted due to its usage in a multi-threaded environment without
602 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
603 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
604 * @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.
605 * @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).
606 * @remarks This method does not depend on system locale.
608 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double& retVal) const;
611 * Gets the @c float value of the specified entry.
615 * @return An error code
616 * @param[in] sectionName The section name
617 * @param[in] entryName The name of entry where its value will be fetched
618 * @param[out] retVal The return value obtained from the registry
619 * @exception E_SUCCESS The method is successful.
620 * @exception E_INVALID_ARG Either the length of the specified string for a section
621 * or an entry is less than or equal to @c 0,
622 * or a @c null value is passed. @n
623 * Note that, it is also possible that the data inside a registry instance is
624 * corrupted due to its usage in a multi-threaded environment without
626 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
627 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
628 * @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.
629 * @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).
630 * @remarks This method does not depend on system locale.
632 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float& retVal) const;
635 * Gets the String value of a specific entry.
639 * @return An error code
640 * @param[in] sectionName The section name
641 * @param[in] entryName The name of entry where its value will be fetched
642 * @param[out] retVal The return value obtained from the registry
643 * @exception E_SUCCESS The method is successful.
644 * @exception E_INVALID_ARG Either the length of the specified string for a section
645 * or an entry is less than or equal to @c 0,
646 * or a @c null value is passed. @n
647 * Note that, it is also possible that the data inside a registry instance is
648 * corrupted due to its usage in a multi-threaded environment without
650 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
651 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
652 * @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.
653 * @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).
655 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::String& retVal) const;
658 * Gets the UuId value of the specified entry.
662 * @return An error code
663 * @param[in] sectionName The section name
664 * @param[in] entryName The name of entry where its value will be fetched
665 * @param[out] retVal The return value obtained from the registry
666 * @exception E_SUCCESS The method is successful.
667 * @exception E_INVALID_ARG Either the length of the specified string for a section
668 * or an entry is less than or equal to @c 0,
669 * or a @c null value is passed. @n
670 * Note that, it is also possible that the data inside a registry instance is
671 * corrupted due to its usage in a multi-threaded environment without
673 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
674 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
675 * @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.
676 * @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).
678 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::UuId& retVal) const;
681 * Gets the ByteBuffer value of the specified entry.
685 * @return An error code
686 * @param[in] sectionName The section name
687 * @param[in] entryName The name of entry where its value will be fetched
688 * @param[out] retVal The return value obtained from the registry
689 * @exception E_SUCCESS The method is successful.
690 * @exception E_INVALID_ARG Either the length of the specified string for a section
691 * or an entry is less than or equal to @c 0,
692 * or a @c null value is passed. @n
693 * Note that, it is also possible that the data inside a registry instance is
694 * corrupted due to its usage in a multi-threaded environment without
696 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
697 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
698 * @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.
699 * @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).
700 * @remarks The ByteBuffer should be constructed before passing it to the method.
701 * That is, the size of the binary data to be fetched should be decided beforehand.
702 * When the %ByteBuffer capacity is less than the actual binary data stored in the registry,
703 * this method reads the data as much as the %ByteBuffer capacity. The position of the %ByteBuffer and
704 * limit are not changed. When the %ByteBuffer capacity is greater than the actual data size,
705 * the method reads the whole data and adjusts the limit of the buffer accordingly.
706 * @see Tizen::Base::ByteBuffer
708 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::ByteBuffer& retVal) const;
711 * Modifies the value of the specified entry using the specified @c int value.
715 * @return An error code
716 * @param[in] sectionName The section name
717 * @param[in] entryName The entry name to modify
718 * @param[in] newValue The @c int value
719 * @exception E_SUCCESS The method is successful.
720 * @exception E_INVALID_ARG Either the length of the specified string for a section
721 * or an entry is less than or equal to @c 0,
722 * or a @c null value is passed. @n
723 * Note that, it is also possible that the data inside a registry instance is
724 * corrupted due to its usage in a multi-threaded environment without
726 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
727 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
728 * @remarks This method will not add a name-value pair as an entry of a specific section
729 * if no entry with the specified name exists.
730 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
733 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int newValue);
736 * Modifies the value of the specified entry using the specified @c double value.
740 * @return An error code
741 * @param[in] sectionName The section name
742 * @param[in] entryName The entry name to modify
743 * @param[in] newValue The @c double value
744 * @exception E_SUCCESS The method is successful.
745 * @exception E_INVALID_ARG Either the length of the specified string for a section
746 * or an entry is less than or equal to @c 0,
747 * or a @c null value is passed. @n
748 * Note that, it is also possible that the data inside a registry instance is
749 * corrupted due to its usage in a multi-threaded environment without
751 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
752 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
753 * @remarks This method will not add a name-value pair as an entry of a specific section
754 * if no entry with the specified name exists.
755 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
756 * @remarks This method converts the specified double type @c newValue to string value using "%lg" format specifier. @n
757 * Also, it does not depend on system locale.
760 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double newValue);
763 * Modifies the value of the specified entry using the specified @c float value.
767 * @return An error code
768 * @param[in] sectionName The section name
769 * @param[in] entryName The entry name to modify
770 * @param[in] newValue The @c float value
771 * @exception E_SUCCESS The method is successful.
772 * @exception E_INVALID_ARG Either the length of the specified string for a section
773 * or an entry is less than or equal to @c 0,
774 * or a @c null value is passed. @n
775 * Note that, it is also possible that the data inside a registry instance is
776 * corrupted due to its usage in a multi-threaded environment without
778 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
779 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
780 * @remarks This method will not add a name-value pair as an entry of a specific section
781 * if no entry with the specified name exists.
782 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
783 * @remarks This method converts the specified float type @c newValue to string value using "%g" format specifier. @n
784 * Also, it does not depend on system locale.
787 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float newValue);
790 * Modifies the value of the specified entry using the specified String value.
794 * @return An error code
795 * @param[in] sectionName The section name
796 * @param[in] entryName The entry name to modify
797 * @param[in] newValue The String value
798 * @exception E_SUCCESS The method is successful.
799 * @exception E_INVALID_ARG Either the length of the specified string for a section
800 * or an entry is less than or equal to @c 0.
801 * Note that, it is also possible that the data inside a registry instance is
802 * corrupted due to its usage in a multi-threaded environment without
804 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
805 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
806 * @remarks This method will not add a name-value pair as an entry of a specific section
807 * if no entry with the specified name exists.
808 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
811 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& newValue);
814 * Modifies the value of the specified entry using the specified UuID value.
818 * @return An error code
819 * @param[in] sectionName The section name
820 * @param[in] entryName The entry name to modify
821 * @param[in] newValue The UuId value
822 * @exception E_SUCCESS The method is successful.
823 * @exception E_INVALID_ARG Either the length of the specified string for a section
824 * or an entry is less than or equal to @c 0,
825 * or a @c null value is passed. @n
826 * Note that, it is also possible that the data inside a registry instance is
827 * corrupted due to its usage in a multi-threaded environment without
829 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
830 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
831 * @remarks This method will not add a name-value pair as an entry of a specific section if no
832 * entry with the specified name exists.
833 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
836 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& newValue);
839 * Modifies the value of the specified entry using the specified ByteBuffer value.
843 * @return An error code
844 * @param[in] sectionName The section name
845 * @param[in] entryName The entry name to modify
846 * @param[in] newValue The @c ByteBuffer value
847 * @exception E_SUCCESS The method is successful.
848 * @exception E_INVALID_ARG Either the length of the specified string for a section
849 * or an entry is less than or equal to @c 0,
850 * or a @c null value is passed. @n
851 * Note that, it is also possible that the data inside a registry instance is
852 * corrupted due to its usage in a multi-threaded environment without
854 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
855 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
856 * @remarks This method will not add a name-value pair as an entry of a specific section
857 * if no entry with the specified name exists.
858 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
861 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& newValue);
864 * Removes the name-value pair entry from specific section.
868 * @return An error code
869 * @param[in] sectionName The section name
870 * @param[in] entryName The entry name to remove
871 * @exception E_SUCCESS The method is successful.
872 * @exception E_INVALID_ARG The length of the specified string for a section or entry is less
873 * than or equal to @c 0.
874 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
875 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
877 result RemoveValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName);
880 * Acquires the file lock on the current opened whole file if it is not acquired.
881 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
886 * @return The pointer to %FileLock instance, @n
887 * else @c null pointer in case of failure
888 * @param[in] lockType The type of file lock to be created
889 * @exception E_SUCCESS The method is successful.
890 * @exception E_INVALID_ARG The specified @c lockType is invalid.
891 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
892 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
893 * file is not open for reading. @n
894 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
895 * file is not open for writing. @n
896 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
897 * The lock is blocked by a lock from another process, and putting the
898 * calling process to sleep to wait for that lock to become free would
900 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
901 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
902 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
903 * The specific error code can be accessed using the GetLastResult() method.
904 * @see Tizen::Io::File::FileLockType
906 FileLock* LockN(FileLockType lockType);
909 * Tries to acquire the file lock on the current opened whole file.
910 * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned.
914 * @return The pointer to %FileLock instance, @n
915 * else @c null pointer in case of failure
916 * @param[in] lockType The type of file lock to be created
917 * @exception E_SUCCESS The method is successful.
918 * @exception E_INVALID_ARG The specified @c lockType is invalid.
919 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
920 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
921 * file is not open for reading. @n
922 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
923 * file is not open for writing. @n
924 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n
925 * - The file lock is already held by another process. @n
926 * - The file to be locked has been memory-mapped by another process.
927 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
928 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
929 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
930 * The specific error code can be accessed using the GetLastResult() method.
931 * @see Tizen::Io::File::FileLockType
933 FileLock* TryToLockN(FileLockType lockType);
936 * Removes the specified registry file.
939 * @brief <i> [Compatibility] </i>
943 * @compatibility This method has compatibility issues with OSP compatible applications. @n
944 * For more information, see @ref CompIoPathPage "here".
947 * @return An error code
948 * @param[in] regPath The path of the registry file to remove
949 * @exception E_SUCCESS The method is successful.
950 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
951 * - The length of the specified string of a file path is less
952 * than or equal to @c 0. @n
953 * - The translated overall length of the specified path exceeds the
954 * system limitation. @n
955 * - The specified path is invalid. @n
956 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
957 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
958 * @exception E_IO Either of the following conditions has occurred: @n
959 * - An unexpected device failure has occurred as the media ejected suddenly. @n
960 * - %File corruption is detected.
962 static result Remove(const Tizen::Base::String& regPath);
965 * Converts a normal registry file to a secure registry file. @n
966 * A secure registry file that is converted by this method can be shared among applications with the same key value.
969 * @brief <i> [Compatibility] </i>
973 * @compatibility This method has compatibility issues with OSP compatible applications. @n
974 * For more information, see @ref CompIoPathPage "here".
977 * @return An error code
978 * @param[in] plainRegPath The normal (non-encrypted) registry file path
979 * @param[in] secureRegPath The secure (encrypted) registry file path to create
980 * @param[in] key A key that encrypts a secure registry file @n
981 * If the secure registry file is converted with a specific key value,
982 * applications can access the same secure registry file with the identical key value.
983 * @exception E_SUCCESS The method is successful.
984 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
985 * - The length of the specified string of a file path is less
986 * than or equal to @c 0. @n
987 * - The translated overall length of the specified path exceeds the
988 * system limitation. @n
989 * - The specified path is invalid. @n
990 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
991 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
992 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
993 * @exception E_INVALID_FORMAT The input registry file contains '0x00' in the middle of the file.
994 * @exception E_PARSING_FAILED The method has failed to parse the registry file.
995 * @exception E_STORAGE_FULL The disk space is full.
996 * @exception E_IO Either of the following conditions has occurred: @n
997 * - An unexpected device failure has occurred as the media ejected suddenly. @n
998 * - %File corruption is detected. @n
999 * - The number of opened files has exceeded the maximum limit.
1001 static result ConvertToSecureRegistry(const Tizen::Base::String& plainRegPath, const Tizen::Base::String& secureRegPath, const Tizen::Base::ByteBuffer& key);
1005 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1009 Registry(const Registry& source);
1012 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1016 Registry& operator =(const Registry& source);
1018 class _RegistryImpl* __pRegistryImpl;
1020 friend class _RegistryImpl;
1026 #endif //_FIO_REGISTRY_H_