2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
20 * @brief This is the header file for the %Registry class.
22 * This header file contains the declarations of the %Registry class.
25 #ifndef _FIO_REGISTRY_H_
26 #define _FIO_REGISTRY_H_
28 #include <FBaseObject.h>
29 #include <FBaseUuId.h>
30 #include <FBaseByteBuffer.h>
31 #include <FBaseColArrayList.h>
32 #include <FBaseResult.h>
33 #include <FBaseColIMap.h>
34 #include <FIoFileLock.h>
36 namespace Tizen {namespace Base
42 namespace Tizen { namespace Io
45 static const long REG_OPEN_READ_ONLY = 0x00000001L;
46 static const long REG_OPEN_READ_WRITE = 0x00000002L;
47 static const long REG_OPEN_CREATE = 0x00000004L;
51 * @brief This class provides a mechanism to access and manipulate registry files.
55 * @final This class is not intended for extension.
57 * The %Registry class provides a mechanism to access and manipulate registry files.
59 * For more information on the class features,
60 * see <a href="../org.tizen.native.appprogramming/html/guide/io/io_namespace.htm">Io Guide</a>.
62 * The following example demonstrates how to use the %Registry class.
69 using namespace Tizen::Base;
70 using namespace Tizen::Io;
71 using namespace Tizen::App;
77 String regPathName(L"regTest.ini");
80 String sect1(L"section1");
81 String sect2(L"section2");
82 String sect3(L"section3");
85 String entry1(L"entry1");
86 String entry2(L"entry2");
91 r = reg.Construct(App::GetInstance()->GetAppDataPath() + regPathName, "a+");
98 r = reg.AddSection(sect1);
99 r = reg.AddSection(sect2);
100 r = reg.AddSection(sect3);
102 // Add value: section1 { entry1 = 999 }
103 r = reg.AddValue(sect1, entry1, 999);
109 // Change value: section1 { entry1 = 3 }
110 r = reg.SetValue(sect1, entry1, 3);
116 // Add value: section2 { entry2 = 1.1234599 }
117 r = reg.AddValue(sect2, entry2, 1.1234599);
123 // Get value: section1 { entry1 = ? }
124 r = reg.GetValue(sect1, entry1, iVal);
140 // Do some error handling
146 class _OSP_EXPORT_ Registry
147 : public Tizen::Base::Object
152 * 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.
159 * This destructor overrides Tizen::Base::Object::~Object().
163 virtual ~Registry(void);
168 * Initializes this instance of %Registry with the specified parameters. @n
169 * This method loads a registry file in the read-write mode.
172 * @brief <i> [Deprecated] [Compatibility] </i>
174 * @deprecated This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
175 * bool createParentDirectories=false) and Registry::Construct(const Tizen::Base::String& regPath, const Tizen::Base::String& openMode).
178 * @compatibility This method has compatibility issues with OSP compatible applications. @n
179 * For more information, see @ref CompIoPathPage "here".
182 * @return An error code
183 * @param[in] regPath The path of the registry file to open or create
184 * @param[in] createIfNotExist Set to @c true to create a registry file, @n
185 * else @c false to open an existing registry file
186 * @exception E_SUCCESS The method is successful.
187 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
188 * - The length of the specified string of a file path is less
189 * than or equal to @c 0. @n
190 * - The translated overall length of the specified path exceeds the
191 * system limitation. @n
192 * - The specified path is invalid. @n
193 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
194 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
195 * @exception E_END_OF_FILE The file pointer has reached end-of-file.
196 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
197 * @exception E_STORAGE_FULL The disk space is full.
198 * @exception E_IO Either of the following conditions has occurred: @n
199 * - An unexpected device failure has occurred as the media ejected suddenly. @n
200 * - %File corruption is detected.
201 * @exception E_INVALID_FORMAT The input registry file contains '0x00' in the middle of the file.
202 * @exception E_PARSING_FAILED The method has failed to parse the registry file.
203 * @remarks To load the registry in read-only mode, use the Registry::Construct(const Tizen::Base::String& regPath,
204 * long openMode, long option) method with REG_OPEN_READ_ONLY as a value for the open mode flag.
208 result Construct(const Tizen::Base::String& regPath, bool createIfNotExist);
213 * Initializes this instance of %Registry with the specified parameters. @n
214 * This method loads a registry file in the read-only or the read-write mode.
217 * @brief <i> [Deprecated] [Compatibility] </i>
219 * @deprecated This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
220 * bool createParentDirectories=false) and Registry::Construct(const Tizen::Base::String& regPath, const Tizen::Base::String& openMode).
223 * @compatibility This method has compatibility issues with OSP compatible applications. @n
224 * For more information, see @ref CompIoPathPage "here".
227 * @return An error code
228 * @param[in] regPath The path of the registry file to open or create
229 * @param[in] openMode An open mode flag @n
230 * Currently, the following flags can be used in combination with
231 * the logical OR operator: @n
232 * (1) REG_OPEN_READ_ONLY @n
233 * (2) REG_OPEN_READ_WRITE @n
234 * (3) REG_OPEN_READ_WRITE | REG_OPEN_CREATE
235 * @param[in] option This argument is reserved for further use @n It is recommended to use @c 0.
236 * @exception E_SUCCESS The method is successful.
237 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
238 * - The length of the specified string of a file path is less
239 * than or equal to @c 0. @n
240 * - The translated overall length of the specified path exceeds the
241 * system limitation. @n
242 * - The specified path is invalid. @n
243 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
244 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
245 * @exception E_END_OF_FILE The file pointer has reached end-of-file.
246 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
247 * @exception E_STORAGE_FULL The disk space is full.
248 * @exception E_IO Either of the following conditions has occurred: @n
249 * - An unexpected device failure has occurred as the media ejected suddenly. @n
250 * - %File corruption is detected.
251 * @exception E_INVALID_FORMAT The input registry file contains '0x00' in the middle of the file.
252 * @exception E_PARSING_FAILED The method has failed to parse the registry file.
256 result Construct(const Tizen::Base::String& regPath, long openMode, long option);
259 * Initializes this instance of %Registry with the specified parameters. @n
260 * This method opens an existing registry file or creates a new one according to the specified file opening mode.
261 * And this method loads data of the registry file to system memory and flushes the data to the storage when this instance
262 * is released or Registry::Flush() is called.
266 * @return An error code
267 * @param[in] regPath The path of the registry file to open or create
268 * @param[in] pOpenMode The file opening mode @n
269 * It can be one of the following:
270 * - r : Open for reading.
271 * - r+: Open for reading and writing.
272 * - w : Open for writing. The registry file is created if it does not exist,
273 * otherwise it is truncated to zero length.
274 * - w+: Open for writing and reading. The registry file is created if it does not exist,
275 * otherwise it is truncated to zero length.
276 * - a : Open for writing. The registry file is created if it does not exist.
277 * - a+: Open for writing and reading. The registry file is created if it does not exist.
278 * @exception E_SUCCESS The method is successful.
279 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
280 * - The overall length of the specified @c regPath is equal to @c 0 or
281 * exceeds system limitations. @n
282 * - The combination of the specified @c pOpenMode is not allowed. @n
283 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
284 * @exception E_FILE_NOT_FOUND The specified @c regPath cannot be found.
285 * @exception E_INVALID_FORMAT Either of the following conditions has occurred: @n
286 * - The section or entry name of the registry file includes one of the following characters:
287 * '\0', '\n', '#' and '='.
288 * - The entry value of the registry file includes one of the following characters:
290 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
291 * @exception E_STORAGE_FULL The disk space is full.
292 * @exception E_IO Either of the following conditions has occurred: @n
293 * - An unexpected device failure has occurred as the media ejected suddenly. @n
294 * - %File corruption is detected.
295 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
297 result Construct(const Tizen::Base::String& regPath, const char* pOpenMode);
300 * Initializes this instance of %Registry with the specified parameters. @n
301 * This method opens an existing secure registry file or creates a new one according to the specified file opening mode.
302 * And this method loads data of the secure registry file to system memory and flushes the data to the storage when this instance
303 * is released or Registry::Flush() is called.
304 * The contents written to the secure registry file is automatically encrypted and the contents read from the secure registry
305 * file is automatically decrypted by the platform. @n
306 * Applications using this method can access the same secure registry files that are created by other applications with the
307 * identical key value in same device. However, the secure registry files created by this method cannot be accessed in other devices.
311 * @return An error code
312 * @param[in] regPath The path of the registry file to open or create
313 * @param[in] pOpenMode The file opening mode @n
314 * It can be one of the following:
315 * - r : Open for reading.
316 * - r+: Open for reading and writing.
317 * - w : Open for writing. The registry file is created if it does not exist,
318 * otherwise it is truncated to zero length.
319 * - w+: Open for writing and reading. The registry file is created if it does not exist,
320 * otherwise it is truncated to zero length.
321 * - a : Open for writing. The registry file is created if it does not exist.
322 * - a+: Open for writing and reading. The registry file is created if it does not exist.
323 * @param[in] secretKey A key used to encrypt data of a registry file or decrypt a secure registry file @n
324 * If a secure registry file is created with a specific key value,
325 * other applications can access the same secure registry file with the identical key value.
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
328 * - The overall length of the specified path is equal to @c 0 or
329 * exceeds system limitations.
330 * - The combination of the specified @c pOpenMode is not allowed. @n
331 * - The specified @c secretKey is incorrect or the secure registry file is corrupted.
332 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
333 * @exception E_FILE_NOT_FOUND The specified @c regPath cannot be found.
334 * @exception E_INVALID_FORMAT Either of the following conditions has occurred: @n
335 * - The section or entry name of the registry file includes one of the following characters:
336 * '\0', '\n', '#' and '='.
337 * - The entry value of the registry file includes one of the following characters:
339 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
340 * @exception E_STORAGE_FULL The disk space is full.
341 * @exception E_IO Either of the following conditions has occurred: @n
342 * - An unexpected device failure has occurred as the media ejected suddenly. @n
343 * - %File corruption is detected. @n
344 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
346 result Construct(const Tizen::Base::String& regPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
349 * Flushes the current contents of a registry in memory. @n
350 * If the secure mode is set to be @c true, the contents of the registry are automatically encrypted
351 * and saved by the platform.
355 * @return An error code
356 * @exception E_SUCCESS The method is successful.
357 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
358 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
359 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
360 * @exception E_STORAGE_FULL The disk space is full.
361 * @exception E_IO Either of the following conditions has occurred: @n
362 * - An unexpected device failure has occurred as the media ejected suddenly. @n
363 * - %File corruption is detected. @n
368 * Creates the specified section then adds it into the registry.
372 * @return An error code
373 * @param[in] sectionName The section name
374 * @exception E_SUCCESS The method is successful.
375 * @exception E_INVALID_ARG The length of the specified string for a section name is less than
377 * @exception E_SECTION_ALREADY_EXIST A section with the specified name already exists.
379 result AddSection(const Tizen::Base::String& sectionName);
382 * Removes the section from %Registry.
386 * @return An error code
387 * @param[in] sectionName The section name to remove
388 * @exception E_SUCCESS The method is successful.
389 * @exception E_INVALID_ARG The length of the specified string for a section is less than
391 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
393 result RemoveSection(const Tizen::Base::String& sectionName);
396 * Gets all section names in the registry.
400 * @return A list of section names @n
401 * If this method fails, @c null value is returned. @n
402 * The specific error code can be accessed using the GetLastResult() method. @n
403 * When there are no sections at all, the method returns an empty list instance. @n
404 * Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of elements in the list.
405 * @exception E_SUCCESS The method is successful.
406 * @remarks Do not forget to delete not only the returned IList instance, but also its
407 * contents by invoking IList::RemoveAll(). @n
408 * The specific error code can be accessed using the GetLastResult() method.
410 Tizen::Base::Collection::IList* GetAllSectionNamesN(void) const;
413 * Gets all entry names in the specified section of the registry.
417 * @return A list of entry names @n
418 * If this method fails, @c null value is returned. @n
419 * When there are no entries at all, the method returns an empty list instance. @n
420 * Use the Tizen::Base::Collection::ICollection::GetCount() method to check the number of element in the list.
421 * @param[in] sectionName The section name
422 * @exception E_SUCCESS The method is successful.
423 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
424 * @exception E_IO A system error has occurred.
425 * @remarks Do not forget to delete not only the returned IList instance, but also its
426 * contents by invoking IList::RemoveAll(). @n
427 * The specific error code can be accessed using the GetLastResult() method.
429 Tizen::Base::Collection::IList* GetAllEntryNamesN(const Tizen::Base::String& sectionName) const;
432 * Adds the name-value pair of type integer as an entry of the specific section.
436 * @return An error code
437 * @param[in] sectionName The section name
438 * @param[in] entryName The entry name
439 * @param[in] value The @c int value
440 * @exception E_SUCCESS The method is successful.
441 * @exception E_INVALID_ARG Either the length of the specified string for a section
442 * or an entry is less than or equal to @c 0,
443 * or a @c null value is passed. @n
444 * Note that, it is also possible that the data inside a registry instance is
445 * corrupted due to its usage in a multi-threaded environment without
447 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
448 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
450 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int value);
453 * Adds the name-value pair of type double as an entry of the specific section.
457 * @return An error code
458 * @param[in] sectionName The section name
459 * @param[in] entryName The entry name
460 * @param[in] value The @c double value
461 * @exception E_SUCCESS The method is successful.
462 * @exception E_INVALID_ARG Either the length of the specified string for a section
463 * or an entry is less than or equal to @c 0,
464 * or a @c null value is passed. @n
465 * Note that, it is also possible that the data inside a registry instance is
466 * corrupted due to its usage in a multi-threaded environment without
468 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
469 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
470 * @remarks This method converts the specified double type @c value to string value using "%lg" format specifier. @n
471 * Also, it does not depend on system locale.
473 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double value);
476 * Adds the name-value pair of type float as an entry of the specific section.
480 * @return An error code
481 * @param[in] sectionName The section name
482 * @param[in] entryName The entry name
483 * @param[in] value The @c float value
484 * @exception E_SUCCESS The method is successful.
485 * @exception E_INVALID_ARG Either the length of the specified string for a section
486 * or an entry is less than or equal to @c 0,
487 * or a @c null value is passed. @n
488 * Note that, it is also possible that the data inside a registry instance is
489 * corrupted due to its usage in a multi-threaded environment without
491 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
492 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
493 * @remarks This method converts the specified float type @c value to string value using "%g" format specifier. @n
494 * Also, it does not depend on system locale.
496 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float value);
499 * Adds the name-value pair of type String as an entry of the specific section.
503 * @return An error code
504 * @param[in] sectionName The section name
505 * @param[in] entryName The entry name
506 * @param[in] value The String value
507 * @exception E_SUCCESS The method is successful.
508 * @exception E_INVALID_ARG Either the length of the specified string for a section
509 * or an entry is less than or equal to @c 0.
510 * Note that, it is also possible that the data inside a registry instance is
511 * corrupted due to its usage in a multi-threaded environment without
513 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
514 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
516 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& value);
519 * Adds the name-value pair of type UuId as an entry for the specified section.
523 * @return An error code
524 * @param[in] sectionName The section name
525 * @param[in] entryName The entry name
526 * @param[in] value The UuId value
527 * @exception E_SUCCESS The method is successful.
528 * @exception E_INVALID_ARG Either the length of the specified string for a section
529 * or an entry is less than or equal to @c 0,
530 * or a @c null value is passed. @n
531 * Note that, it is also possible that the data inside a registry instance is
532 * corrupted due to its usage in a multi-threaded environment without
534 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
535 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
537 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& value);
540 * Adds the name-value pair of type ByteBuffer as an entry for the specified section.
544 * @return An error code
545 * @param[in] sectionName The section name
546 * @param[in] entryName The entry name
547 * @param[in] value The @c ByteBuffer value @n
548 * Note that, it should be constructed before being passed to the method.
549 * @exception E_SUCCESS The method is successful.
550 * @exception E_INVALID_ARG Either the length of the specified string for a section
551 * or an entry is less than or equal to @c 0,
552 * or a @c null value is passed. @n
553 * Note that, it is also possible that the data inside a registry instance is
554 * corrupted due to its usage in a multi-threaded environment without
556 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
557 * @exception E_KEY_ALREADY_EXIST The specified @c entryName already exists in this section.
558 * @remarks Note that all the contents of @c ByteBuffer are saved as an entry value.
559 * That is, byte data from @c 0 up to the buffer limit is saved.
560 * @see Tizen::Base::ByteBuffer
562 result AddValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& value);
565 * Gets the @c int value of the specified entry.
569 * @return An error code
570 * @param[in] sectionName The section name
571 * @param[in] entryName The name of entry where its value will be fetched
572 * @param[out] retVal The return value obtained from the registry
573 * @exception E_SUCCESS The method is successful.
574 * @exception E_INVALID_ARG Either the length of the specified string for a section
575 * or an entry is less than or equal to @c 0,
576 * or a @c null value is passed. @n
577 * Note that, it is also possible that the data inside a registry instance is
578 * corrupted due to its usage in a multi-threaded environment without
580 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
581 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
582 * @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.
583 * @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).
585 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int& retVal) const;
588 * Gets the @c double value of the specified entry.
592 * @return An error code
593 * @param[in] sectionName The section name
594 * @param[in] entryName The name of entry where its value will be fetched
595 * @param[out] retVal The return value obtained from the registry
596 * @exception E_SUCCESS The method is successful.
597 * @exception E_INVALID_ARG Either the length of the specified string for a section
598 * or an entry is less than or equal to @c 0,
599 * or a @c null value is passed. @n
600 * Note that, it is also possible that the data inside a registry instance is
601 * corrupted due to its usage in a multi-threaded environment without
603 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
604 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
605 * @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.
606 * @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).
607 * @remarks This method does not depend on system locale.
609 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double& retVal) const;
612 * Gets the @c float value of the specified entry.
616 * @return An error code
617 * @param[in] sectionName The section name
618 * @param[in] entryName The name of entry where its value will be fetched
619 * @param[out] retVal The return value obtained from the registry
620 * @exception E_SUCCESS The method is successful.
621 * @exception E_INVALID_ARG Either the length of the specified string for a section
622 * or an entry is less than or equal to @c 0,
623 * or a @c null value is passed. @n
624 * Note that, it is also possible that the data inside a registry instance is
625 * corrupted due to its usage in a multi-threaded environment without
627 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
628 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
629 * @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.
630 * @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).
631 * @remarks This method does not depend on system locale.
633 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float& retVal) const;
636 * Gets the String value of a specific entry.
640 * @return An error code
641 * @param[in] sectionName The section name
642 * @param[in] entryName The name of entry where its value will be fetched
643 * @param[out] retVal The return value obtained from the registry
644 * @exception E_SUCCESS The method is successful.
645 * @exception E_INVALID_ARG Either the length of the specified string for a section
646 * or an entry is less than or equal to @c 0,
647 * or a @c null value is passed. @n
648 * Note that, it is also possible that the data inside a registry instance is
649 * corrupted due to its usage in a multi-threaded environment without
651 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
652 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
653 * @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.
654 * @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).
656 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::String& retVal) const;
659 * Gets the UuId value of the specified entry.
663 * @return An error code
664 * @param[in] sectionName The section name
665 * @param[in] entryName The name of entry where its value will be fetched
666 * @param[out] retVal The return value obtained from the registry
667 * @exception E_SUCCESS The method is successful.
668 * @exception E_INVALID_ARG Either the length of the specified string for a section
669 * or an entry is less than or equal to @c 0,
670 * or a @c null value is passed. @n
671 * Note that, it is also possible that the data inside a registry instance is
672 * corrupted due to its usage in a multi-threaded environment without
674 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
675 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
676 * @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.
677 * @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).
679 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::UuId& retVal) const;
682 * Gets the ByteBuffer value of the specified entry.
686 * @return An error code
687 * @param[in] sectionName The section name
688 * @param[in] entryName The name of entry where its value will be fetched
689 * @param[out] retVal The return value obtained from the registry
690 * @exception E_SUCCESS The method is successful.
691 * @exception E_INVALID_ARG Either the length of the specified string for a section
692 * or an entry is less than or equal to @c 0,
693 * or a @c null value is passed. @n
694 * Note that, it is also possible that the data inside a registry instance is
695 * corrupted due to its usage in a multi-threaded environment without
697 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
698 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
699 * @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.
700 * @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).
701 * @remarks The ByteBuffer should be constructed before passing it to the method.
702 * That is, the size of the binary data to be fetched should be decided beforehand.
703 * When the %ByteBuffer capacity is less than the actual binary data stored in the registry,
704 * this method reads the data as much as the %ByteBuffer capacity. The position of the %ByteBuffer and
705 * limit are not changed. When the %ByteBuffer capacity is greater than the actual data size,
706 * the method reads the whole data and adjusts the limit of the buffer accordingly.
707 * @see Tizen::Base::ByteBuffer
709 result GetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, Tizen::Base::ByteBuffer& retVal) const;
712 * Modifies the value of the specified entry using the specified @c int value.
716 * @return An error code
717 * @param[in] sectionName The section name
718 * @param[in] entryName The entry name to modify
719 * @param[in] newValue The @c int value
720 * @exception E_SUCCESS The method is successful.
721 * @exception E_INVALID_ARG Either the length of the specified string for a section
722 * or an entry is less than or equal to @c 0,
723 * or a @c null value is passed. @n
724 * Note that, it is also possible that the data inside a registry instance is
725 * corrupted due to its usage in a multi-threaded environment without
727 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
728 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
729 * @remarks This method will not add a name-value pair as an entry of a specific section
730 * if no entry with the specified name exists.
731 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
734 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, int newValue);
737 * Modifies the value of the specified entry using the specified @c double value.
741 * @return An error code
742 * @param[in] sectionName The section name
743 * @param[in] entryName The entry name to modify
744 * @param[in] newValue The @c double value
745 * @exception E_SUCCESS The method is successful.
746 * @exception E_INVALID_ARG Either the length of the specified string for a section
747 * or an entry is less than or equal to @c 0,
748 * or a @c null value is passed. @n
749 * Note that, it is also possible that the data inside a registry instance is
750 * corrupted due to its usage in a multi-threaded environment without
752 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
753 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
754 * @remarks This method will not add a name-value pair as an entry of a specific section
755 * if no entry with the specified name exists.
756 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
757 * @remarks This method converts the specified double type @c newValue to string value using "%lg" format specifier. @n
758 * Also, it does not depend on system locale.
761 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, double newValue);
764 * Modifies the value of the specified entry using the specified @c float value.
768 * @return An error code
769 * @param[in] sectionName The section name
770 * @param[in] entryName The entry name to modify
771 * @param[in] newValue The @c float value
772 * @exception E_SUCCESS The method is successful.
773 * @exception E_INVALID_ARG Either the length of the specified string for a section
774 * or an entry is less than or equal to @c 0,
775 * or a @c null value is passed. @n
776 * Note that, it is also possible that the data inside a registry instance is
777 * corrupted due to its usage in a multi-threaded environment without
779 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
780 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
781 * @remarks This method will not add a name-value pair as an entry of a specific section
782 * if no entry with the specified name exists.
783 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
784 * @remarks This method converts the specified float type @c newValue to string value using "%g" format specifier. @n
785 * Also, it does not depend on system locale.
788 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, float newValue);
791 * Modifies the value of the specified entry using the specified String value.
795 * @return An error code
796 * @param[in] sectionName The section name
797 * @param[in] entryName The entry name to modify
798 * @param[in] newValue The String value
799 * @exception E_SUCCESS The method is successful.
800 * @exception E_INVALID_ARG Either the length of the specified string for a section
801 * or an entry is less than or equal to @c 0.
802 * Note that, it is also possible that the data inside a registry instance is
803 * corrupted due to its usage in a multi-threaded environment without
805 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
806 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
807 * @remarks This method will not add a name-value pair as an entry of a specific section
808 * if no entry with the specified name exists.
809 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
812 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::String& newValue);
815 * Modifies the value of the specified entry using the specified UuID value.
819 * @return An error code
820 * @param[in] sectionName The section name
821 * @param[in] entryName The entry name to modify
822 * @param[in] newValue The UuId value
823 * @exception E_SUCCESS The method is successful.
824 * @exception E_INVALID_ARG Either the length of the specified string for a section
825 * or an entry is less than or equal to @c 0,
826 * or a @c null value is passed. @n
827 * Note that, it is also possible that the data inside a registry instance is
828 * corrupted due to its usage in a multi-threaded environment without
830 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
831 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
832 * @remarks This method will not add a name-value pair as an entry of a specific section if no
833 * entry with the specified name exists.
834 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
837 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::UuId& newValue);
840 * Modifies the value of the specified entry using the specified ByteBuffer value.
844 * @return An error code
845 * @param[in] sectionName The section name
846 * @param[in] entryName The entry name to modify
847 * @param[in] newValue The @c ByteBuffer value
848 * @exception E_SUCCESS The method is successful.
849 * @exception E_INVALID_ARG Either the length of the specified string for a section
850 * or an entry is less than or equal to @c 0,
851 * or a @c null value is passed. @n
852 * Note that, it is also possible that the data inside a registry instance is
853 * corrupted due to its usage in a multi-threaded environment without
855 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
856 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
857 * @remarks This method will not add a name-value pair as an entry of a specific section
858 * if no entry with the specified name exists.
859 * In such a case, it returns E_KEY_NOT_FOUND. Use AddValue() to insert a new entry.
862 result SetValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName, const Tizen::Base::ByteBuffer& newValue);
865 * Removes the name-value pair entry from specific section.
869 * @return An error code
870 * @param[in] sectionName The section name
871 * @param[in] entryName The entry name to remove
872 * @exception E_SUCCESS The method is successful.
873 * @exception E_INVALID_ARG The length of the specified string for a section or entry is less
874 * than or equal to @c 0.
875 * @exception E_SECTION_NOT_FOUND The specified @c sectionName is not found within the registry.
876 * @exception E_KEY_NOT_FOUND The specified @c entryName is not found within the registry.
878 result RemoveValue(const Tizen::Base::String& sectionName, const Tizen::Base::String& entryName);
881 * Acquires the file lock on the current opened whole file if it is not acquired.
882 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
887 * @return The pointer to %FileLock instance, @n
888 * else @c null pointer in case of failure
889 * @param[in] lockType The type of file lock to be created
890 * @exception E_SUCCESS The method is successful.
891 * @exception E_INVALID_ARG The specified @c lockType is invalid.
892 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
893 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
894 * file is not open for reading. @n
895 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
896 * file is not open for writing. @n
897 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
898 * The lock is blocked by a lock from another process, and putting the
899 * calling process to sleep to wait for that lock to become free would
901 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
902 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
903 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
904 * The specific error code can be accessed using the GetLastResult() method.
905 * @see Tizen::Io::File::FileLockType
907 FileLock* LockN(FileLockType lockType);
910 * Tries to acquire the file lock on the current opened whole file.
911 * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned.
915 * @return The pointer to %FileLock instance, @n
916 * else @c null pointer in case of failure
917 * @param[in] lockType The type of file lock to be created
918 * @exception E_SUCCESS The method is successful.
919 * @exception E_INVALID_ARG The specified @c lockType is invalid.
920 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
921 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
922 * file is not open for reading. @n
923 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
924 * file is not open for writing. @n
925 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n
926 * - The file lock is already held by another process. @n
927 * - The file to be locked has been memory-mapped by another process.
928 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
929 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
930 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
931 * The specific error code can be accessed using the GetLastResult() method.
932 * @see Tizen::Io::File::FileLockType
934 FileLock* TryToLockN(FileLockType lockType);
937 * Removes the specified registry file.
940 * @brief <i> [Compatibility] </i>
944 * @compatibility This method has compatibility issues with OSP compatible applications. @n
945 * For more information, see @ref CompIoPathPage "here".
948 * @return An error code
949 * @param[in] regPath The path of the registry file to remove
950 * @exception E_SUCCESS The method is successful.
951 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
952 * - The length of the specified string of a file path is less
953 * than or equal to @c 0. @n
954 * - The translated overall length of the specified path exceeds the
955 * system limitation. @n
956 * - The specified path is invalid. @n
957 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
958 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
959 * @exception E_IO Either of the following conditions has occurred: @n
960 * - An unexpected device failure has occurred as the media ejected suddenly. @n
961 * - %File corruption is detected.
963 static result Remove(const Tizen::Base::String& regPath);
966 * Converts a normal registry file to a secure registry file. @n
967 * A secure registry file that is converted by this method can be shared among applications with the same key value.
970 * @brief <i> [Compatibility] </i>
974 * @compatibility This method has compatibility issues with OSP compatible applications. @n
975 * For more information, see @ref CompIoPathPage "here".
978 * @return An error code
979 * @param[in] plainRegPath The normal (non-encrypted) registry file path
980 * @param[in] secureRegPath The secure (encrypted) registry file path to create
981 * @param[in] key A key that encrypts a secure registry file @n
982 * If the secure registry file is converted with a specific key value,
983 * applications can access the same secure registry file with the identical key value.
984 * @exception E_SUCCESS The method is successful.
985 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
986 * - The length of the specified string of a file path is less
987 * than or equal to @c 0. @n
988 * - The translated overall length of the specified path exceeds the
989 * system limitation. @n
990 * - The specified path is invalid. @n
991 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
992 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
993 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
994 * @exception E_INVALID_FORMAT The input registry file contains '0x00' in the middle of the file.
995 * @exception E_PARSING_FAILED The method has failed to parse the registry file.
996 * @exception E_STORAGE_FULL The disk space is full.
997 * @exception E_IO Either of the following conditions has occurred: @n
998 * - An unexpected device failure has occurred as the media ejected suddenly. @n
999 * - %File corruption is detected. @n
1000 * - The number of opened files has exceeded the maximum limit.
1002 static result ConvertToSecureRegistry(const Tizen::Base::String& plainRegPath, const Tizen::Base::String& secureRegPath, const Tizen::Base::ByteBuffer& key);
1006 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1010 Registry(const Registry& source);
1013 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1017 Registry& operator =(const Registry& source);
1019 class _RegistryImpl* __pRegistryImpl;
1021 friend class _RegistryImpl;
1027 #endif //_FIO_REGISTRY_H_