X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFIoFile.h;h=50b179f30172e0815887dd37aac36b8077d15c91;hb=HEAD;hp=57b9b2ee6740404c7337fcef1c275533788d277b;hpb=f35aaec65fcf10d247f9b1bb74c36e75f7cf2fa7;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FIoFile.h b/inc/FIoFile.h index 57b9b2e..50b179f 100644 --- a/inc/FIoFile.h +++ b/inc/FIoFile.h @@ -1,5 +1,4 @@ // -// Open Service Platform // Copyright (c) 2012 Samsung Electronics Co., Ltd. // // Licensed under the Apache License, Version 2.0 (the License); @@ -47,13 +46,13 @@ namespace Tizen { namespace Io enum FileSeekPosition { FILESEEKPOSITION_BEGIN, /**GetAppRootPath() + L"data" - * or Tizen::App::App::GetInstance()->GetAppDataPath(). - * - res - Used to read resource files that are delivered with the application package (read-only permission) @n - * To access this directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"res" - * or Tizen::App::App::GetInstance()->GetAppResourcePath(). - * - shared - Used to share data and resource files with other applications @n - * There are data and res directories under the shared directory. - * Use Tizen::App::App::GetInstance()->GetAppRootPath() + L"shared" to access its own shared directory and - * use Tizen::App::AppManager::GetAppSharedPath() to access other application's shared directory. @n + * - data - Used to store and access private data of an application (read-write permission) @n + * To access this directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"data" + * or Tizen::App::App::GetInstance()->GetAppDataPath(). + * - res - Used to read resource files that are delivered with the application package (read-only permission) @n + * To access this directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"res" + * or Tizen::App::App::GetInstance()->GetAppResourcePath(). + * - shared - Used to share data and resource files with other applications @n + * Shared directory has data and res directories. + * Use Tizen::App::App::GetInstance()->GetAppRootPath() + L"shared" to access its own shared directory and + * use Tizen::App::AppManager::GetAppSharedPath() to access other application's shared directory. * * For more information on the path, * see I/O Overview. * - * For more information on class features, + * For more information on the class features, * see Io Guide. * * The following example demonstrates how to use the %File class. @@ -173,7 +172,7 @@ CATCH: * @if OSPCOMPAT * @page CompIoPathPage Compatibility for path * @section CompIoPathPageIssueSection Issues - * The path argument of this method in OSP compatible applications has the following issue: @n + * The path argument of this method in OSP compatible applications has the following issue: * * -# The path should begin with an allowed path prefix such as '/Home', '/Home/Share', '/Res', '/Share/[@e appid]', * '/Media', and '/Storagecard/Media'. @@ -202,7 +201,8 @@ class _OSP_EXPORT_ File public: /** - * 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. + * The object is not fully constructed after this constructor is called. @n + * For full construction, the Construct() method must be called right after calling this constructor. * * @since 2.0 */ @@ -216,8 +216,7 @@ public: virtual ~File(void); /** - * @{ - * @if OSPDEPREC + * @cond OSPDEPREC * Initializes this instance of %File with the specified parameters. @n * This method opens an existing file or creates a new one according to the specified file opening mode. * @@ -246,27 +245,27 @@ public: * - a+: Open for appending and reading. The file is created if it does not exist. * @param[in] createParentDirectories Set to @c true to automatically create non-existent parent directories up to destination, @n * else @c false @n - * This parameter is useful only if the specified @c openMode allows creation of an absent - * file. For example, the following modes: "w", "w+", "a" and "a+". @n + * This parameter is useful only if the specified @c openMode is "w", "w+", "a" or "a+" + * that allows the creation of an absent file. @n * If the value of @c openMode is not any one of these, E_INVALID_ARG exception is thrown. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n - * - The combination of the specified @c openMode is not allowed. @n - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * exceeds system limitations. + * - The combination of the specified @c openMode is not allowed. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode such as "w" or "a". * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. - * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+", - * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n - * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally. - * @endif - * @} + * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+", + * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n + * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored + * internally. + * @endcond */ result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode, bool createParentDirectories); @@ -296,22 +295,23 @@ public: * - a : Open for appending. The file is created if it does not exist. * - a+: Open for appending and reading. The file is created if it does not exist. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n - * - The combination of the specified @c openMode is not allowed. @n - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * exceeds system limitations. + * - The combination of the specified @c openMode is not allowed. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode such as "w" or "a". * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+", - * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n - * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally. + * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+", + * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n + * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored + * internally. */ result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode); @@ -334,22 +334,23 @@ public: * - a : Open for appending. The file is created if it does not exist. * - a+: Open for appending and reading. The file is created if it does not exist. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n - * - The combination of the specified @c pOpenMode is not allowed. @n - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * exceeds system limitations. + * - The combination of the specified @c pOpenMode is not allowed. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode such as "w" or "a". * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+", - * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n - * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally. + * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+", + * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n + * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored + * internally. */ result Construct(const Tizen::Base::String& filePath, const char* pOpenMode); @@ -358,8 +359,8 @@ public: * This method opens an existing secure file or creates a new one according to the specified file opening mode. @n * The contents written to the secure file is automatically encrypted and the contents read from the secure file is automatically * decrypted by the platform. @n - * Applications using this method can access the secure files that are created by other applications with the identical key value - * in same device. However, the secure files created by this method cannot be accessed in other devices. + * Applications using this method can access the secure files that are created by other applications with an identical key value + * in the same device. However, the secure files created by this method cannot be accessed in other devices. * * @since 2.0 * @@ -375,215 +376,205 @@ public: * otherwise it is truncated to zero length. * - a : Open for appending. The file is created if it does not exist. * - a+: Open for appending and reading. The file is created if it does not exist. - * @param[in] secretKey A key used to encrypt data of a file or decrypt a secure file @n - * If a secure file is created with a specific key value, - * other applications can access the same secure file with the identical key value. + * @param[in] secretKey The key used to encrypt the data of the file or decrypt the secure file @n + * If the secure file is created with a specific key value, + * other applications can access the secure file with an identical key value. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or * exceeds system limitations. - * - The combination of the specified @c pOpenMode is not allowed. @n + * - The combination of the specified @c pOpenMode is not allowed. * - The specified @c secretKey is incorrect or the secure file is corrupted. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode such as "w" or "a". * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n - * - %File corruption is detected. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. + * - %File corruption is detected. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+", - * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n - * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally. + * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+", + * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n + * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored + * internally. */ result Construct(const Tizen::Base::String& filePath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey); /** * Reads the byte data from the current file pointer. @n * The user-specified ByteBuffer is filled with the byte data from the current position in the file. - * The read operation continues until the specified ByteBuffer is filled or end-of-file is met. @n + * The read operation continues until the specified ByteBuffer is filled or the end of file is reached. @n * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module. * * @since 2.0 * * @return An error code - * @param[in, out] buffer A reference to the buffer that is used to receive the byte data read from the file + * @param[in, out] buffer The reference to the buffer to copy the byte data * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c buffer has no space to store the read data. - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for read operation. @n - * - Access is denied due to insufficient permission. - * @exception E_END_OF_FILE The file pointer has reached end-of-file. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for read operation. + * - The access is denied due to insufficient permission. + * @exception E_END_OF_FILE The file pointer has reached the end of file. + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. - * @remarks The ByteBuffer should be constructed before being passed to the method. + * @remarks The ByteBuffer should be constructed before being passed to this method. */ result Read(Tizen::Base::ByteBuffer& buffer); /** - * Reads the byte data from the current file pointer and copies it into the specified buffer. @n + * Reads the byte data from the current file pointer and copies it to the specified buffer. @n * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module. * * @since 2.0 * * @return The length of the data read in bytes, @n * else @c 0 in case of failure - * @param[out] buffer A pointer to the user-supplied buffer where the read data is copied + * @param[out] buffer The pointer to the buffer to copy the byte data * @param[in] length The buffer length in bytes * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n - * - The specified @c buffer contains a @c null pointer. @n - * - The length of the specified @c buffer is equal to or smaller than @c 0. @n - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for read operation. @n - * - Access is denied due to insufficient permission. - * @exception E_END_OF_FILE The file pointer has reached end-of-file. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified @c buffer contains a @c null pointer. + * - The length of the specified @c buffer is equal to or smaller than @c 0. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for read operation. + * - The access is denied due to insufficient permission. + * @exception E_END_OF_FILE The file pointer has reached the end of file. + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @remarks The specific error code can be accessed using the GetLastResult() method. */ int Read(void* buffer, int length); /** - * Reads the string data from the current file pointer and copies the string to the specified buffer (it is assumed that the - * file is in the UTF-8 format). @n - * The read operation continues until new line character or end-of-file is met. @n + * Reads the string data from the current file pointer and copies it to the specified buffer. @n + * It is assumed that the file is in the UTF-8 format. + * The read operation continues until a new line character or end-of-file is reached. @n * In the secure mode, the string data read from the secure file is automatically decrypted by a platform security module. * * @since 2.0 * * @return An error code - * @param[out] buffer A reference to the buffer where the data is copied + * @param[out] buffer A reference to the buffer to copy the string data * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the - * memory is corrupted). - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for read operation. @n - * - Access is denied due to insufficient permission. - * @exception E_END_OF_FILE The file pointer reached end-of-file. + * @exception E_INVALID_ARG The specified @c buffer is invalid. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for read operation. + * - The access is denied due to insufficient permission. + * @exception E_END_OF_FILE The file pointer reached the end of file. * @exception E_IO Either of the following conditions has occurred: - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. - * @remarks To get the expected string value - * from a file, which is not in the UTF-8 format (Unicode or any other format), - * user should use other encoding or decoding methods of the Tizen::Text namespace after reading the content of - * a file in binary format. @n - * The maximum length of characters read by this method is defined as 4096. @n - * Therefore, if the length of a single line (considering new line character or end-of-file) from the current + * @remarks To get the expected string value from a file, which is not in the UTF-8 format + * (Unicode or any other format), the user should use other encoding or decoding methods of the + * Tizen::Text namespace after reading the content of the file in binary format. @n + * The maximum length of characters read by this method is defined as @c 4096. @n + * Therefore, if the length of a single line (till a new line character or end-of-file is reached) from the current * file position is longer than 4096, the rest of the characters remain as not read. @n - * 'ByteBuffer' or 'void*' version of the File::Read() API can be used to overcome this limitation. + * The 'ByteBuffer' or 'void*' version of the File::Read() API can be used to overcome this limitation. */ result Read(Tizen::Base::String& buffer); /** - * Writes the byte data from the specified ByteBuffer into a file beginning at the current position to the limit of the - * %ByteBuffer. @n - * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. - * However, the file pointer for the secure file is equal to the file pointer for the original file. + * Writes the byte data from the specified Tizen::Base::ByteBuffer beginning at the current position to the limit of the %Tizen::Base::ByteBuffer + * to a file . @n + * In the secure mode, the byte data written is automatically encrypted to a secure file by the platform security module. @n + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. + * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 * * @return An error code - * @param[in] buffer A reference to the buffer that contains byte data to write + * @param[in] buffer A reference to the buffer that contains the byte data to write * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the - * memory is corrupted). - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for write operation. @n - * - Access is denied due to insufficient permission. + * @exception E_INVALID_ARG The specified @c buffer is invalid. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for write operation. + * - The access is denied due to insufficient permission. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ result Write(const Tizen::Base::ByteBuffer& buffer); /** - * Writes the byte data into a file. @n - * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. - * However, the file pointer for the secure file is equal to the file pointer for the original file. + * Writes the byte data from the specified buffer to a file. @n + * In the secure mode, the byte data written is automatically encrypted to a secure file by the platform security module. @n + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. + * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 * * @return An error code - * @param[in] buffer A pointer to the user-supplied buffer that contains @c byte data to write + * @param[in] buffer A pointer to the buffer that contains the @c byte data to write * @param[in] length The buffer length in bytes * @exception E_SUCCESS The method is successful. - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for write operation. @n - * - Access is denied due to insufficient permission. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n - * - The specified @c buffer contains a @c null pointer. @n - * - The specified @c buffer length is equal or smaller than @c 0. @n + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for write operation. + * - The access is denied due to insufficient permission. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified @c buffer contains a @c null pointer. + * - The specified @c buffer length is equal or smaller than @c 0. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ result Write(const void* buffer, int length); /** - * Writes the string data into a file. @n - * In the secure mode, the string data written by a user is automatically encrypted to the secure file by a platform security - * module. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. - * However, the file pointer for the secure file is equal to the file pointer for the original file. + * Writes the string data from the specified buffer to a file. @n + * In the secure mode, the string data written is automatically encrypted to a secure file by the platform security module. @n + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. + * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 * * @return An error code - * @param[in] buffer A reference to the buffer that contains string data to write + * @param[in] buffer A reference to the buffer that contains the string data to write * @exception E_SUCCESS The method is successful. - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for write operation. @n - * - Access is denied due to insufficient permission. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for write operation. + * - The access is denied due to insufficient permission. * @exception E_INVALID_ARG The specified @c buffer contains an empty string. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ result Write(const Tizen::Base::String& buffer); /** - * Flushes the internally buffered data. + * Flushes the internally buffered data to the kernel memory of the underlying operating system. * * @since 2.0 * * @return An error code * @exception E_SUCCESS The method is successful. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. - * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the - * memory is corrupted). - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. + * @exception E_STORAGE_FULL The disk space is full. + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ result Flush(void); /** * Gets the offset of the current file pointer relative to the beginning of the file. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. - * However, the file pointer for the secure file is equal to the file pointer for the original file. + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. + * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 * * @return The offset of the current file pointer, @n * else @c -1L if an error occurs * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the - * memory is corrupted). - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @remarks The specific error code can be accessed using the GetLastResult() method. * @see Seek() @@ -591,27 +582,26 @@ public: int Tell(void) const; /** - * Repositions the file pointer associated with an opened file. @n + * Repositions the file pointer associated with the opened file. @n * Each opened file has its own file pointer, and it points to the next byte to be read or written in the file. * The repositioning offset can be specified with respect to the beginning of file, current position, or end of the file. * If the file pointer is over the end-of-file, it expands the file size to the specified position and the expanded area is * filled with zero. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. - * However, the file pointer for the secure file is equal to the file pointer for the original file. + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. + * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 * * @return An error code - * @param[in] position The origin from where to start the repositioning a file pointer + * @param[in] position The starting position to reposition the file pointer * @param[in] offset The number of bytes to move a file pointer @n * A negative offset moves the pointer backwards. * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c position or @c offset is invalid. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @see FileSeekPosition */ @@ -619,11 +609,9 @@ public: /** * Truncates the file size to the specified length. @n - * If the specified length is less than the length of file, the bytes present between the @c length and size of a file are - * removed. - * If the file size is small, its size is increased. @n - * The size of a secure file can be greater than the size of a normal (original) file - * because of the encryption. + * If the specified length is less than the length of file, the bytes present between the specified @c length and size of + * the file are removed. If the file size is small, its size is increased. @n + * The size of a secure file can be greater than the size of a normal (original) file because of the encryption. * However, the file pointer for a secure file is equal to the file pointer for an original file. * * @since 2.0 @@ -631,146 +619,146 @@ public: * @return An error code * @param[in] length The required file size in bytes after this method is executed * @exception E_SUCCESS The method is successful. - * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n - * - The file is not opened for write operation. @n - * - Access is denied due to insufficient permission. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The file is not opened for write operation. + * - The access is denied due to insufficient permission. * @exception E_INVALID_ARG The specified @c length has a negative value. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ result Truncate(int length); /** - * Gets the path associated with a constructed %File. + * Gets the path associated with the %File. * * @since 2.0 * - * @return The file path to the currently constructed %File if successful, @n + * @return The path of the currently constructed %File, @n * else an empty string in case of failure */ Tizen::Base::String GetName(void) const; /** - * Acquires the file lock on the current opened whole file if it is not acquired. + * Acquires the file lock on the current opened whole file if it is not acquired. @n * If the file lock is already acquired by another process, the current process is blocked until the file lock is * released. * * @since 2.1 * - * @return The pointer to %FileLock instance, @n - * else @c null pointer in case of failure - * @param[in] lockType The type of file lock to be created + * @return The pointer to the FileLock instance, @n + * else @c null pointer in case of failure + * @param[in] lockType The type of the file lock to be created * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c lockType is invalid. - * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n - * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current - * file is not open for reading. @n - * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current - * file is not open for writing. @n + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current + * file is not open for reading. + * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current + * file is not open for writing. * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n - * The lock is blocked by a lock from another process, and putting the - * calling process to sleep to wait for that lock to become free would - * cause a deadlock. - * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations. + * The lock is blocked by a lock from another process, and putting the + * calling process to sleep to wait for that lock to become free would + * cause a deadlock. + * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n - * The specific error code can be accessed using the GetLastResult() method. - * @see Tizen::Io::File::FileLockType + * @remarks + * - The FileLock instance is invalid if the associated %File instance is deleted. + * - The specific error code can be accessed using the GetLastResult() method. */ FileLock* LockN(FileLockType lockType); /** - * Acquires the file lock on the specified region of the current opened file if it is not acquired. + * Acquires the file lock on the specified region of the current opened file if it is not acquired. @n * If the file lock is already acquired by another process, the current process is blocked until the file lock is * released. * * @since 2.1 * - * @return The pointer to %FileLock instance, @n - * else @c null pointer in case of failure + * @return The pointer to the FileLock instance, @n + * else @c null pointer in case of failure * @param[in] lockType The type of file lock to be created * @param[in] offset The starting offset for the locked region * @param[in] length The length of the locked region in bytes * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The specified @c lockType is invalid. * - The specified @c offset or @c length is negative or is greater than * the system limitation. - * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n - * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current - * file is not open for reading. @n - * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current - * file is not open for writing. @n + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current + * file is not open for reading. + * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current + * file is not open for writing. * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n - * The lock is blocked by a lock from another process, and putting the - * calling process to sleep to wait for that lock to become free would - * cause a deadlock. - * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations. + * The lock is blocked by a lock from another process, and putting the + * calling process to sleep to wait for that lock to become free would + * cause a deadlock. + * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n - * The specific error code can be accessed using the GetLastResult() method. - * @see Tizen::Io::File::FileLockType + * @remarks + * - The FileLock instance is invalid if the associated %File instance is deleted. + * - The specific error code can be accessed using the GetLastResult() method. */ FileLock* LockN(FileLockType lockType, int offset, int length); /** - * Tries to acquire the file lock on the current opened whole file. - * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned. + * Tries to acquire the file lock on the current opened whole file. @n + * If the file lock is already acquired by another process, @c E_OBJECT_LOCKED is returned. * * @since 2.1 * - * @return The pointer to %FileLock instance, @n - * else @c null pointer in case of failure + * @return The pointer to the FileLock instance, @n + * else @c null pointer in case of failure * @param[in] lockType The type of file lock to be created * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The specified @c lockType is invalid. - * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n - * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current - * file is not open for reading. @n - * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current - * file is not open for writing. @n - * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n - * - The file lock is already held by another process. @n - * - The file to be locked has been memory-mapped by another process. - * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current + * file is not open for reading. + * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current + * file is not open for writing. + * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: + * - The file lock is already held by another process. + * - The file to be locked has been memory-mapped by another process. + * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n - * The specific error code can be accessed using the GetLastResult() method. - * @see Tizen::Io::File::FileLockType + * @remarks + * - The FileLock instance is invalid if the associated %File instance is deleted. + * - The specific error code can be accessed using the GetLastResult() method. */ FileLock* TryToLockN(FileLockType lockType); /** - * Tries to acquire the file lock on the specified region of the current opened file. - * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned. + * Tries to acquire the file lock on the specified region of the current opened file. @n + * If the file lock is already acquired by another process, @c E_OBJECT_LOCKED is returned. * * @since 2.1 * - * @return The pointer to %FileLock instance, @n - * else @c null pointer in case of failure + * @return The pointer to the FileLock instance, @n + * else @c null pointer in case of failure * @param[in] lockType The type of file lock to be created * @param[in] offset The starting offset for the locked region * @param[in] length The length of the locked region in bytes * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n - * - The specified @c lockType is invalid. - * - The specified @c offset or @c length is negative or is greater than - * the system limitation. - * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n - * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current - * file is not open for reading. @n - * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current - * file is not open for writing. @n - * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n - * - The file lock is already held by another process. @n - * - The file to be locked has been memory-mapped by another process. - * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations. + * @exception E_INVALID_ARG Either of the following conditions has occurred: + * - The specified @c lockType is invalid. + * - The specified @c offset or @c length is negative or is greater than + * the system limitation. + * @exception E_INVALID_OPERATION Either of the following conditions has occurred: + * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current + * file is not open for reading. + * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current + * file is not open for writing. + * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: + * - The file lock is already held by another process. + * - The file to be locked has been memory-mapped by another process. + * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations. * @exception E_SYSTEM The method cannot proceed due to a severe system error. - * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n - * The specific error code can be accessed using the GetLastResult() method. - * @see Tizen::Io::File::FileLockType + * @remarks + * - The FileLock instance is invalid if the associated %File instance is deleted. + * - The specific error code can be accessed using the GetLastResult() method. */ FileLock* TryToLockN(FileLockType lockType, int offset, int length); @@ -790,22 +778,22 @@ public: * @return An error code * @param[in] filePath The path of the file to delete * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n + * exceeds system limitations. * - The specified path is invalid. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode. * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @remarks The opened file cannot be deleted. */ static result Remove(const Tizen::Base::String& filePath); /** - * Moves the specified file to another location. @n + * Moves the specified file to the specified location. @n * The opened files cannot be moved. This method is static. * * @if OSPCOMPAT @@ -821,26 +809,26 @@ public: * @param[in] oldFilePath The old file path * @param[in] newFilePath The new file path * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n + * exceeds system limitations. * - The specified path is invalid. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode. - * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found. + * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_FILE_ALREADY_EXIST The specified file already exists. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @see Copy() - * @see Remove() + * @see Remove() */ static result Move(const Tizen::Base::String& oldFilePath, const Tizen::Base::String& newFilePath); /** - * Copies the existing source file to the destined location. @n + * Copies the existing source file to the specified destination file path. @n * This method is static. * * @since 2.0 @@ -851,26 +839,26 @@ public: * @param[in] failIfExist Set to @c true to return an error if the destination file already exists, @n * else @c false * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n + * exceeds system limitations. * - The specified path is invalid. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n * For example, opening a read-only file in the write mode. - * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found. + * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_FILE_ALREADY_EXIST The specified file already exists. * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. * @see Move() - * @see Remove() + * @see Remove() */ static result Copy(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath, bool failIfExist); /** - * Reads the file information such as size, attribute, creation date, and so on. @n + * Gets the attributes of the specified file such as size, attribute, creation date, and so on. @n * This method is static. * * @if OSPCOMPAT @@ -883,23 +871,23 @@ public: * @endif * * @return An error code - * @param[in] filePath The path of the file @n + * @param[in] filePath The path of the file * @param[out] attribute A %File attribute instance * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n + * exceeds system limitations. * - The specified path is invalid. - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. - * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. + * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. * - %File corruption is detected. */ static result GetAttributes(const Tizen::Base::String& filePath, FileAttributes& attribute); /** - * Gets only the file name from the specified file path. @n + * Gets the file name from the specified file path. @n * For example, if the file path passed is 'xxx/file.txt', 'file.txt' is returned. * * @if OSPCOMPAT @@ -912,7 +900,7 @@ public: * @endif * * @return The file name of type String - * @param[in] filePath The path of the file + * @param[in] filePath The file path * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations. * @remarks The specific error code can be accessed using the GetLastResult() method. @@ -934,7 +922,7 @@ public: * * @return The file extension, @n * else an empty string if the file has no extension - * @param[in] filePath The path of the file + * @param[in] filePath The file path * @exception E_SUCCESS The method is successful. * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations. * @remarks The specific error code can be accessed using the GetLastResult() method. @@ -954,16 +942,17 @@ public: * For more information, see @ref CompIoPathPage "here". * @endif * - * @return @c true if file or directory exists, @n + * @return @c true if the file or directory exists, @n * else @c false * @param[in] filePath The path of the file or directory * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n + * exceeds system limitations. * - The specified path is invalid. - * @exception E_ILLEGAL_ACCESS The specified path is not permitted, or - * access is denied due to insufficient permission. + * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: + * - The specified path is not permitted. + * - Access is denied due to insufficient permission. * @remarks The specific error code can be accessed using the GetLastResult() method. */ static bool IsFileExist(const Tizen::Base::String& filePath); @@ -985,21 +974,21 @@ public: * @return An error code * @param[in] plainFilePath The normal (non-encrypted) file path * @param[in] secureFilePath The secure (encrypted) file path to create - * @param[in] key A key that encrypts a secure file @n - * If the secure file is converted with a specific key value, - * applications can access the same secure file with the identical key value. + * @param[in] key The key that encrypts the secure file @n + * If the secure file is converted with the specific key value, + * applications can access the secure file with an identical key value. * @exception E_SUCCESS The method is successful. - * @exception E_INVALID_ARG Either of the following conditions has occurred: @n + * @exception E_INVALID_ARG Either of the following conditions has occurred: * - The overall length of the specified path is equal to @c 0 or - * exceeds system limitations. @n - * - The specified path is invalid. @n - * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. + * exceeds system limitations. + * - The specified path is invalid. + * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. * @exception E_FILE_ALREADY_EXIST The specified file already exists. - * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found. + * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found. * @exception E_STORAGE_FULL The disk space is full. - * @exception E_IO Either of the following conditions has occurred: @n - * - An unexpected device failure has occurred as the media ejected suddenly. @n - * - %File corruption is detected. @n + * @exception E_IO Either of the following conditions has occurred: + * - An unexpected device failure has occurred as the media ejected suddenly. + * - %File corruption is detected. * - The number of opened files has exceeded the maximum limit. */ static result ConvertToSecureFile(const Tizen::Base::String& plainFilePath, const Tizen::Base::String& secureFilePath, const Tizen::Base::ByteBuffer& key);