inc/FIoFile.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FIoFile.h
  20  * @brief       This is the header file for the %File class.
  21  *
  22  * This header file contains the declarations of the %File class.
  23  */
  24
  25 #ifndef _FIO_FILE_H_
  26 #define _FIO_FILE_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseString.h>
  30 #include <FBaseByteBuffer.h>
  31 #include <FBaseDateTime.h>
  32 #include <FBaseColIList.h>
  33 #include <FBaseResult.h>
  34 #include <FIoFileAttributes.h>
  35
  36 namespace Tizen { namespace Io
  37 {
  38
  39 /**
  40  * @enum FileSeekPosition
  41  *
  42  * Defines the file seek position.
  43  *
  44  * @since       2.0
  45  */
  46 enum FileSeekPosition
  47 {
  48         FILESEEKPOSITION_BEGIN,         /**<The beginning of the file */
  49         FILESEEKPOSITION_CURRENT,       /**<The current position of the file */
  50         FILESEEKPOSITION_END            /**<The end of the file */
  51 };
  52
  53 /**
  54  * @class       File
  55  * @brief       This class provides the basic file I/O operations, such as read, write, create, and remove.
  56  *
  57  * @since       2.0
  58  *
  59  * @final       This class is not intended for extension.
  60  *
  61  * The %File class provides the basic file I/O operations, such as read, write, create, and remove.
  62  * It only provides synchronous file read-write with raw data bytes (UTF-8) or string data.
  63  * It is constructed using the Construct() method to access files and control file I/O operations.
  64  * There is no method like Close() to close the opened file instances.
  65  * The only way to close an opened file is by invoking the destructor of the %File class.
  66  * Therefore, if the %File class is instantiated as a local variable, it is not closed until it goes out of scope.
  67  * To get a detailed information on a file or directory, use the FileAttributes and Directory classes.
  68  *
  69  * When an application is installed, the application has its own storage area, which is application root directory.
  70  * The application root directory path can be obtained by calling Tizen::App::App::GetAppRootPath().
  71  * The following are some of the sub-directories of the application root directory:
  72  * - data - Used to store and access private data of an application (read-write permission) @n
  73  *                      To access this directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"data"
  74  *                      or Tizen::App::App::GetInstance()->GetAppDataPath().
  75  * - res - Used to read resource files that are delivered with the application package (read-only permission) @n
  76  *                      To access this directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"res"
  77  *                      or Tizen::App::App::GetInstance()->GetAppResourcePath().
  78  * - shared - Used to share data and resource files with other applications @n
  79  *                      There are data and res directories under the shared directory.
  80  *                      Use Tizen::App::App::GetInstance()->GetAppRootPath() + L"shared" to access its own shared directory and
  81  *                      use Tizen::App::AppManager::GetAppSharedPath() to access other application's shared directory.  @n
  82  *
  83  * For more information on the path,
  84  * see <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/io_overview.htm">I/O Overview</a>.
  85  *
  86  * For more information on class features,
  87  * see <a href="../org.tizen.native.appprogramming/html/guide/io/io_namespace.htm">Io Guide</a>.
  88  *
  89  * The following example demonstrates how to use the %File class.
  90  *
  91  * @code
  92
  93 #include <FBase.h>
  94 #include <FIo.h>
  95 #include <FApp.h>
  96
  97 using namespace Tizen::Base;
  98 using namespace Tizen::Io;
  99 using namespace Tizen::App;
 100
 101 int main(void)
 102 {
 103         String fileName(L"test.txt");
 104         File file;
 105         char buffer[10];
 106         char buffer2[5];
 107         int i;
 108         int readCnt;
 109         result r = E_SUCCESS;
 110
 111         // Creates file
 112         r = file.Construct(App::GetInstance()->GetAppDataPath() + fileName, "w+");
 113         if (IsFailed(r))
 114         {
 115                 goto CATCH;
 116         }
 117
 118         for (i = 0; i < 10; i++)
 119         {
 120                 buffer[i] = (char) i;
 121         }
 122
 123         // Writes to the file
 124         r = file.Write(buffer, 10);
 125         if (IsFailed(r))
 126         {
 127                 goto CATCH;
 128         }
 129
 130         // Repositions the file pointer
 131         r = file.Seek(FILESEEKPOSITION_CURRENT, -5);
 132         if (IsFailed(r))
 133         {
 134                 goto CATCH;
 135         }
 136
 137         // Reads
 138         readCnt = file.Read(buffer2, 5);
 139         r = GetLastResult();
 140         if (IsFailed(r))
 141         {
 142                 goto CATCH;
 143         }
 144         if (readCnt != 5)
 145         {
 146                 goto CATCH;
 147         }
 148
 149         // Checks the correctness of the read data
 150         for (i = 0; i < readCnt; i++)
 151         {
 152                 char m, n;
 153                 m = buffer2[i];
 154                 n = buffer[i + 5];
 155                 if (m != n)
 156                 {
 157                         goto CATCH;
 158                 }
 159         }
 160         AppLog("Succeeded!");
 161         return 0;
 162
 163 CATCH:
 164         AppLog("Failed...");
 165         return -1;
 166 }
 167
 168  * @endcode
 169  */
 170
 171 /**
 172  * @if OSPCOMPAT
 173  * @page        CompIoPathPage Compatibility for path
 174  * @section CompIoPathPageIssueSection Issues
 175  *                      The path argument of this method in OSP compatible applications has the following issue: @n
 176  *
 177  * -# The path should begin with an allowed path prefix such as '/Home', '/Home/Share', '/Res', '/Share/[@e appid]',
 178  * '/Media', and '/Storagecard/Media'.
 179  *
 180  * @section CompIoPathPageSolutionSection Resolutions
 181  *
 182  * - There are no specific allowed path prefixes in Tizen.
 183  *
 184  * @par When working in Tizen:
 185  *  - For accessing its own data directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"data" @n
 186  *    or Tizen::App::App::GetInstance()->GetAppDataPath().
 187  *  - For accessing its own resource directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"res" @n
 188  *    or Tizen::App::App::GetInstance()->GetAppResourcePath().
 189  *  - For accessing its own shared directory, use Tizen::App::App::GetInstance()->GetAppRootPath() + L"shared/data".
 190  *  - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 191  *  - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 192  *
 193  * For more information on the path,
 194  * see <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/io_overview.htm">I/O Overview</a>.
 195  * @endif
 196  */
 197
 198 class _OSP_EXPORT_ File
 199         : public Tizen::Base::Object
 200 {
 201
 202 public:
 203         /**
 204         * 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.
 205         *
 206         * @since                2.0
 207         */
 208         File(void);
 209
 210         /**
 211         * This destructor overrides Tizen::Base::Object::~Object().
 212         *
 213         * @since        2.0
 214         */
 215         virtual ~File(void);
 216
 217         /**
 218         * @if OSPDEPREC
 219         * @{
 220         * Initializes this instance of %File with the specified parameters. @n
 221         * This method opens an existing file or creates a new one according to the specified file opening mode.
 222         *
 223         * @if OSPCOMPAT
 224         * @brief                        <i> [Deprecated] [Compatibility] </i>
 225         * @endif
 226         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 227         *                                       bool createParentDirectories=false) and File::Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode).
 228         * @since                        2.0
 229         * @if OSPCOMPAT
 230         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 231         *                                       For more information, see @ref CompIoPathPage "here".
 232         * @endif
 233         *
 234         * @return               An error code
 235         * @param[in]    filePath                                The path of the file to open or create
 236         * @param[in]    openMode                                The file opening mode @n
 237         *                                                                               It can be one of the following:
 238         *                                                                               - r : Open for reading.
 239         *                                                                               - r+: Open for reading and writing.
 240         *                                                                               - w : Open for writing. The file is created if it does not exist,
 241         *                                                                                         otherwise it is truncated to zero length.
 242         *                                                                               - w+: Open for writing and reading. The file is created if it does not exist,
 243         *                                                                                         otherwise it is truncated to zero length.
 244         *                                                                               - a : Open for appending. The file is created if it does not exist.
 245         *                                                                               - a+: Open for appending and reading. The file is created if it does not exist.
 246         * @param[in]    createParentDirectories Set to @c true to automatically create non-existent parent directories up to destination, @n
 247         *                                                                               else @c false @n
 248         *                                                                               This parameter is useful only if the specified @c openMode allows creation of an absent
 249         *                                                                               file. For example, the following modes: "w", "w+", "a" and "a+". @n
 250         *                                                                               If the value of @c openMode is not any one of these, E_INVALID_ARG exception is thrown.
 251         * @exception    E_SUCCESS                               The method is successful.
 252         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 253         *                                                                               - The overall length of the specified path is equal to @c 0 or
 254         *                                                                                 exceeds system limitations. @n
 255         *                                                                               - The combination of the specified @c openMode is not allowed. @n
 256         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission. @n
 257         *                                                                               For example, opening a read-only file in the write mode such as "w" or "a".
 258         * @exception    E_FILE_NOT_FOUND                The specified @c filePath cannot be found.
 259         * @exception    E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 260         * @exception    E_STORAGE_FULL                  The disk space is full.
 261         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 262         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 263         *                                                                               - %File corruption is detected.
 264         * @remarks              The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
 265         *                               "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
 266         *                               Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
 267         * @}
 268         * @endif
 269         */
 270         result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode, bool createParentDirectories);
 271
 272         /**
 273         * Initializes this instance of %File with the specified parameters. @n
 274         * This method opens an existing file or creates a new one according to the specified file opening mode.
 275         *
 276         * @if OSPCOMPAT
 277         * @brief                        <i> [Compatibility] </i>
 278         * @endif
 279         * @since                        2.0
 280         * @if OSPCOMPAT
 281         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 282         *                                       For more information, see @ref CompIoPathPage "here".
 283         * @endif
 284         *
 285         * @return               An error code
 286         * @param[in]    filePath                        The path of the file to open or create
 287         * @param[in]    openMode                        The file opening mode @n
 288         *                                                                       It can be one of the following:
 289         *                                                                       - r : Open for reading.
 290         *                                                                       - r+: Open for reading and writing.
 291         *                                                                       - w : Open for writing. The file is created if it does not exist,
 292         *                                                                                 otherwise it is truncated to zero length.
 293         *                                                                       - w+: Open for writing and reading. The file is created if it does not exist,
 294         *                                                                                 otherwise it is truncated to zero length.
 295         *                                                                       - a : Open for appending. The file is created if it does not exist.
 296         *                                                                       - a+: Open for appending and reading. The file is created if it does not exist.
 297         * @exception    E_SUCCESS                       The method is successful.
 298         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 299         *                                                                       - The overall length of the specified path is equal to @c 0 or
 300         *                                                                         exceeds system limitations. @n
 301         *                                                                       - The combination of the specified @c openMode is not allowed. @n
 302         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission. @n
 303         *                                                                       For example, opening a read-only file in the write mode such as "w" or "a".
 304         * @exception    E_FILE_NOT_FOUND        The specified @c filePath cannot be found.
 305         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 306         * @exception    E_STORAGE_FULL          The disk space is full.
 307         * @exception    E_IO                            Either of the following conditions has occurred: @n
 308         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 309         *                                                                       - %File corruption is detected.
 310         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 311         * @remarks              The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
 312         *                               "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
 313         *                               Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
 314         */
 315         result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode);
 316
 317         /**
 318         * Initializes this instance of %File with the specified parameters. @n
 319         * This method opens an existing file or creates a new one according to the specified file opening mode.
 320         *
 321         * @since                2.0
 322         *
 323         * @return               An error code
 324         * @param[in]    filePath                        The path of the file to open or create
 325         * @param[in]    pOpenMode                       The file opening mode @n
 326         *                                                                       It can be one of the following:
 327         *                                                                       - r : Open for reading.
 328         *                                                                       - r+: Open for reading and writing.
 329         *                                                                       - w : Open for writing. The file is created if it does not exist,
 330         *                                                                                 otherwise it is truncated to zero length.
 331         *                                                                       - w+: Open for writing and reading. The file is created if it does not exist,
 332         *                                                                                 otherwise it is truncated to zero length.
 333         *                                                                       - a : Open for appending. The file is created if it does not exist.
 334         *                                                                       - a+: Open for appending and reading. The file is created if it does not exist.
 335         * @exception    E_SUCCESS                       The method is successful.
 336         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 337         *                                                                       - The overall length of the specified path is equal to @c 0 or
 338         *                                                                         exceeds system limitations. @n
 339         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 340         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission. @n
 341         *                                                                       For example, opening a read-only file in the write mode such as "w" or "a".
 342         * @exception    E_FILE_NOT_FOUND        The specified @c filePath cannot be found.
 343         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 344         * @exception    E_STORAGE_FULL          The disk space is full.
 345         * @exception    E_IO                            Either of the following conditions has occurred: @n
 346         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 347         *                                                                       - %File corruption is detected.
 348         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 349         * @remarks              The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
 350         *                               "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
 351         *                               Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
 352         */
 353         result Construct(const Tizen::Base::String& filePath, const char* pOpenMode);
 354
 355         /**
 356         * Initializes this instance of %File with the specified parameters. @n
 357         * This method opens an existing secure file or creates a new one according to the specified file opening mode. @n
 358         * The contents written to the secure file is automatically encrypted and the contents read from the secure file is automatically
 359         * decrypted by the platform. @n
 360         * Applications using this method can access the secure files that are created by other applications with the identical key value
 361         * in same device. However, the secure files created by this method cannot be accessed in other devices.
 362         *
 363         * @since                2.0
 364         *
 365         * @return               An error code
 366         * @param[in]    filePath                        The path of the file to open or create
 367         * @param[in]    pOpenMode                       The file opening mode @n
 368         *                                                                       It can be one of the following:
 369         *                                                                       - r : Open for reading.
 370         *                                                                       - r+: Open for reading and writing.
 371         *                                                                       - w : Open for writing. The file is created if it does not exist,
 372         *                                                                                 otherwise it is truncated to zero length.
 373         *                                                                       - w+: Open for writing and reading. The file is created if it does not exist,
 374         *                                                                                 otherwise it is truncated to zero length.
 375         *                                                                       - a : Open for appending. The file is created if it does not exist.
 376         *                                                                       - a+: Open for appending and reading. The file is created if it does not exist.
 377         * @param[in]    secretKey                       A key used to encrypt data of a file or decrypt a secure file @n
 378         *                                                                       If a secure file is created with a specific key value,
 379         *                                                                       other applications can access the same secure file with the identical key value.
 380         * @exception    E_SUCCESS                       The method is successful.
 381         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 382         *                                                                       - The overall length of the specified path is equal to @c 0 or
 383         *                                                                         exceeds system limitations.
 384         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 385         *                                                                       - The specified @c secretKey is incorrect or the secure file is corrupted.
 386         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission. @n
 387         *                                                                       For example, opening a read-only file in the write mode such as "w" or "a".
 388         * @exception    E_FILE_NOT_FOUND        The specified @c filePath cannot be found.
 389         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 390         * @exception    E_STORAGE_FULL          The disk space is full.
 391         * @exception    E_IO                            Either of the following conditions has occurred: @n
 392         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 393         *                                                                       - %File corruption is detected. @n
 394         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 395         * @remarks              The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
 396         *                               "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
 397         *                               Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
 398         */
 399         result Construct(const Tizen::Base::String& filePath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
 400
 401         /**
 402         * Reads the byte data from the current file pointer. @n
 403         * The user-specified ByteBuffer is filled with the byte data from the current position in the file.
 404         * The read operation continues until the specified ByteBuffer is filled or end-of-file is met. @n
 405         * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
 406         *
 407         * @since                        2.0
 408         *
 409         * @return                       An error code
 410         * @param[in, out]       buffer                          A reference to the buffer that is used to receive the byte data read from the file
 411         * @exception            E_SUCCESS                       The method is successful.
 412         * @exception            E_INVALID_ARG           The specified @c buffer has no space to store the read data.
 413         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 414         *                                                                               - The file is not opened for read operation. @n
 415         *                                                                               - Access is denied due to insufficient permission.
 416         * @exception            E_END_OF_FILE           The file pointer has reached end-of-file.
 417         * @exception            E_IO                            Either of the following conditions has occurred: @n
 418         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 419         *                                                                               - %File corruption is detected.
 420         * @remarks                      The ByteBuffer should be constructed before being passed to the method.
 421         */
 422         result Read(Tizen::Base::ByteBuffer& buffer);
 423
 424         /**
 425         * Reads the byte data from the current file pointer and copies it into the specified buffer. @n
 426         * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
 427         *
 428         * @since                        2.0
 429         *
 430         * @return                       The length of the data read in bytes, @n
 431         *                                       else @c 0 in case of failure
 432         * @param[out]           buffer                          A pointer to the user-supplied buffer where the read data is copied
 433         * @param[in]            length                          The buffer length in bytes
 434         * @exception            E_SUCCESS                       The method is successful.
 435         * @exception            E_INVALID_ARG           Either of the following conditions has occurred: @n
 436         *                                                                               - The specified @c buffer contains a @c null pointer. @n
 437         *                                                                               - The length of the specified @c buffer is equal to or smaller than @c 0. @n
 438         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 439         *                                                                               - The file is not opened for read operation. @n
 440         *                                                                               - Access is denied due to insufficient permission.
 441         * @exception            E_END_OF_FILE           The file pointer has reached end-of-file.
 442         * @exception            E_IO                            Either of the following conditions has occurred: @n
 443         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 444         *                                                                               - %File corruption is detected.
 445         * @remarks                      The specific error code can be accessed using the GetLastResult() method.
 446         */
 447         int Read(void* buffer, int length);
 448
 449         /**
 450         * Reads the string data from the current file pointer and copies the string to the specified buffer (it is assumed that the
 451         * file is in the UTF-8 format). @n
 452         * The read operation continues until new line character or end-of-file is met. @n
 453         * In the secure mode, the string data read from the secure file is automatically decrypted by a platform security module.
 454         *
 455         * @since                        2.0
 456         *
 457         * @return                       An error code
 458         * @param[out]           buffer                          A reference to the buffer where the data is copied
 459         * @exception            E_SUCCESS                       The method is successful.
 460         * @exception            E_INVALID_ARG           The file handle is invalid (either the file is closed by another method, or the
 461         *                                                                               memory is corrupted).
 462         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 463         *                                                                               - The file is not opened for read operation. @n
 464         *                                                                               - Access is denied due to insufficient permission.
 465         * @exception            E_END_OF_FILE           The file pointer reached end-of-file.
 466         * @exception            E_IO                            Either of the following conditions has occurred:
 467         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 468         *                                                                               - %File corruption is detected.
 469         * @remarks                      To get the expected string value
 470         *                                       from a file, which is not in the UTF-8 format (Unicode or any other format),
 471         *                                       user should use other encoding or decoding methods of the Tizen::Text namespace after reading the content of
 472         *                                       a file in binary format. @n
 473         *                                       The maximum length of characters read by this method is defined as 4096. @n
 474         *                                       Therefore, if the length of a single line (considering new line character or end-of-file) from the current
 475         *                                       file position is longer than 4096, the rest of the characters remain as not read. @n
 476         *                                       'ByteBuffer' or 'void*' version of the File::Read() API can be used to overcome this limitation.
 477         */
 478         result Read(Tizen::Base::String& buffer);
 479
 480         /**
 481         * Writes the byte data from the specified ByteBuffer into a file beginning at the current position to the limit of the
 482         * %ByteBuffer. @n
 483         * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n
 484         * The size of a secure file can be greater than the size of a normal (original) file
 485         * because of the encryption.
 486         * However, the file pointer for the secure file is equal to the file pointer for the original file.
 487         *
 488         * @since                        2.0
 489         *
 490         * @return                       An error code
 491         * @param[in]            buffer                          A reference to the buffer that contains byte data to write
 492         * @exception            E_SUCCESS                       The method is successful.
 493         * @exception            E_INVALID_ARG           The file handle is invalid (either the file is closed by another method, or the
 494         *                                                                               memory is corrupted).
 495         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 496         *                                                                               - The file is not opened for write operation. @n
 497         *                                                                               - Access is denied due to insufficient permission.
 498         * @exception            E_STORAGE_FULL          The disk space is full.
 499         * @exception            E_IO                            Either of the following conditions has occurred: @n
 500         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 501         *                                                                               - %File corruption is detected.
 502         */
 503         result Write(const Tizen::Base::ByteBuffer& buffer);
 504
 505         /**
 506         * Writes the byte data into a file. @n
 507         * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n
 508         * The size of a secure file can be greater than the size of a normal (original) file
 509         * because of the encryption.
 510         * However, the file pointer for the secure file is equal to the file pointer for the original file.
 511         *
 512         * @since                        2.0
 513         *
 514         * @return                       An error code
 515         * @param[in]            buffer                          A pointer to the user-supplied buffer that contains @c byte data to write
 516         * @param[in]            length                          The buffer length in bytes
 517         * @exception            E_SUCCESS                       The method is successful.
 518         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 519         *                                                                               - The file is not opened for write operation. @n
 520         *                                                                               - Access is denied due to insufficient permission.
 521         * @exception            E_INVALID_ARG           Either of the following conditions has occurred: @n
 522         *                                                                               - The specified @c buffer contains a @c null pointer. @n
 523         *                                                                               - The specified @c buffer length is equal or smaller than @c 0. @n
 524         * @exception            E_STORAGE_FULL          The disk space is full.
 525         * @exception            E_IO                            Either of the following conditions has occurred: @n
 526         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 527         *                                                                               - %File corruption is detected.
 528         */
 529         result Write(const void* buffer, int length);
 530
 531         /**
 532         * Writes the string data into a file. @n
 533         * In the secure mode, the string data written by a user is automatically encrypted to the secure file by a platform security
 534         * module. @n
 535         * The size of a secure file can be greater than the size of a normal (original) file
 536         * because of the encryption.
 537         * However, the file pointer for the secure file is equal to the file pointer for the original file.
 538         *
 539         * @since                        2.0
 540         *
 541         * @return                       An error code
 542         * @param[in]            buffer                          A reference to the buffer that contains string data to write
 543         * @exception            E_SUCCESS                       The method is successful.
 544         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 545         *                                                                               - The file is not opened for write operation. @n
 546         *                                                                               - Access is denied due to insufficient permission.
 547         * @exception            E_INVALID_ARG           The specified @c buffer contains an empty string.
 548         * @exception            E_STORAGE_FULL          The disk space is full.
 549         * @exception            E_IO                            Either of the following conditions has occurred: @n
 550         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 551         *                                                                               - %File corruption is detected.
 552         */
 553         result Write(const Tizen::Base::String& buffer);
 554
 555         /**
 556         * Flushes the internally buffered data into a permanent storage immediately.
 557         *
 558         * @since                        2.0
 559         *
 560         * @return                       An error code
 561         * @exception            E_SUCCESS                       The method is successful.
 562         * @exception            E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 563         * @exception            E_INVALID_ARG           The file handle is invalid (either the file is closed by another method, or the
 564         *                                                                               memory is corrupted).
 565         * @exception        E_IO                                Either of the following conditions has occurred: @n
 566         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 567         *                                                                               - %File corruption is detected.
 568         */
 569         result Flush(void);
 570
 571         /**
 572         * Gets the offset of the current file pointer relative to the beginning of the file. @n
 573         * The size of a secure file can be greater than the size of a normal (original) file
 574         * because of the encryption.
 575         * However, the file pointer for the secure file is equal to the file pointer for the original file.
 576         *
 577         * @since                        2.0
 578         *
 579         * @return                       The offset of the current file pointer, @n
 580         *                                       else @c -1L if an error occurs
 581         * @exception        E_SUCCESS                   The method is successful.
 582         * @exception            E_INVALID_ARG           The file handle is invalid (either the file is closed by another method, or the
 583         *                                                                               memory is corrupted).
 584         * @exception        E_IO                                Either of the following conditions has occurred: @n
 585         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 586         *                                                                               - %File corruption is detected.
 587         * @remarks                      The specific error code can be accessed using the GetLastResult() method.
 588         * @see                          Seek()
 589         */
 590         int Tell(void) const;
 591
 592         /**
 593         * Repositions the file pointer associated with an opened file. @n
 594         * Each opened file has its own file pointer, and it points to the next byte to be read or written in the file.
 595         * The repositioning offset can be specified with respect to the beginning of file, current position, or end of the file.
 596         * If the file pointer is over the end-of-file, it expands the file size to the specified position and the expanded area is
 597         * filled with zero. @n
 598         * The size of a secure file can be greater than the size of a normal (original) file
 599         * because of the encryption.
 600         * However, the file pointer for the secure file is equal to the file pointer for the original file.
 601         *
 602         * @since                        2.0
 603         *
 604         * @return                       An error code
 605         * @param[in]            position                        The origin from where to start the repositioning a file pointer
 606         * @param[in]            offset              The number of bytes to move a file pointer @n
 607         *                                                                               A negative offset moves the pointer backwards.
 608         * @exception            E_SUCCESS                       The method is successful.
 609         * @exception            E_INVALID_ARG           The specified @c position or @c offset is invalid.
 610         * @exception            E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 611         * @exception        E_STORAGE_FULL              The disk space is full.
 612         * @exception        E_IO                                Either of the following conditions has occurred: @n
 613         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 614         *                                                                               - %File corruption is detected.
 615         * @see                          FileSeekPosition
 616         */
 617         result Seek(FileSeekPosition position, long offset);
 618
 619         /**
 620         * Truncates the file size to the specified length. @n
 621         * If the specified length is less than the length of file, the bytes present between the @c length and size of a file are
 622         * removed.
 623         * If the file size is small, its size is increased. @n
 624         * The size of a secure file can be greater than the size of a normal (original) file
 625         * because of the encryption.
 626         * However, the file pointer for a secure file is equal to the file pointer for an original file.
 627         *
 628         * @since                        2.0
 629         *
 630         * @return                       An error code
 631         * @param[in]            length                          The required file size in bytes after this method is executed
 632         * @exception            E_SUCCESS                       The method is successful.
 633         * @exception            E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 634         *                                                                               - The file is not opened for write operation. @n
 635         *                                                                               - Access is denied due to insufficient permission.
 636         * @exception            E_INVALID_ARG           The specified @c length has a negative value.
 637         * @exception        E_STORAGE_FULL              The disk space is full.
 638         * @exception        E_IO                                Either of the following conditions has occurred: @n
 639         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 640         *                                                                               - %File corruption is detected.
 641         */
 642         result Truncate(int length);
 643
 644         /**
 645         * Gets the path associated with a constructed %File.
 646         *
 647         * @since                        2.0
 648         *
 649         * @return                       The file path to the currently constructed %File if successful, @n
 650         *                                       else an empty string in case of failure
 651         */
 652         Tizen::Base::String GetName(void) const;
 653
 654         /**
 655         * Deletes the file specified. @n
 656         * The opened file cannot be deleted. This method is static.
 657         *
 658         * @if OSPCOMPAT
 659         * @brief <i> [Compatibility] </i>
 660         * @endif
 661         * @since                        2.0
 662         * @if OSPCOMPAT
 663         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 664         *                                       For more information, see @ref CompIoPathPage "here".
 665         * @endif
 666         *
 667         * @return                       An error code
 668         * @param[in]            filePath                        The path of the file to delete
 669         * @exception        E_SUCCESS                   The method is successful.
 670         * @exception            E_INVALID_ARG           Either of the following conditions has occurred: @n
 671         *                                                                               - The overall length of the specified path is equal to @c 0 or
 672         *                                                                                 exceeds system limitations. @n
 673         *                                                                               - The specified path is invalid.
 674         * @exception            E_ILLEGAL_ACCESS        Access is denied due to insufficient permission. @n
 675         *                                                                               For example, opening a read-only file in the write mode.
 676         * @exception            E_FILE_NOT_FOUND        An entry for the specified file or path cannot be found.
 677         * @exception        E_IO                                Either of the following conditions has occurred: @n
 678         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 679         *                                                                               - %File corruption is detected.
 680         * @remarks          The opened file cannot be deleted.
 681         */
 682         static result Remove(const Tizen::Base::String& filePath);
 683
 684         /**
 685         * Moves the specified file to another location. @n
 686         * The opened files cannot be moved. This method is static.
 687         *
 688         * @if OSPCOMPAT
 689         * @brief <i> [Compatibility] </i>
 690         * @endif
 691         * @since                        2.0
 692         * @if OSPCOMPAT
 693         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 694         *                                       For more information, see @ref CompIoPathPage "here".
 695         * @endif
 696         *
 697         * @return                       An error code
 698         * @param[in]            oldFilePath                             The old file path
 699         * @param[in]            newFilePath                             The new file path
 700         * @exception            E_SUCCESS                               The method is successful.
 701         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred: @n
 702         *                                                                                       - The overall length of the specified path is equal to @c 0 or
 703         *                                                                                         exceeds system limitations. @n
 704         *                                                                                       - The specified path is invalid.
 705         * @exception            E_ILLEGAL_ACCESS                Access is denied due to insufficient permission. @n
 706         *                                                                                       For example, opening a read-only file in the write mode.
 707         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 708         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 709         * @exception            E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 710         * @exception        E_STORAGE_FULL                      The disk space is full.
 711         * @exception        E_IO                                        Either of the following conditions has occurred: @n
 712         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 713         *                                                                                       - %File corruption is detected.
 714         * @see                  Copy()
 715        * @see                   Remove()
 716         */
 717         static result Move(const Tizen::Base::String& oldFilePath, const Tizen::Base::String& newFilePath);
 718
 719         /**
 720         * Copies the existing source file to the destined location. @n
 721         * This method is static.
 722         *
 723         * @since                        2.0
 724         *
 725         * @return                       An error code
 726         * @param[in]            srcFilePath                     The source file path
 727         * @param[in]            destFilePath            The destination file path
 728         * @param[in]            failIfExist                             Set to @c true to return an error if the destination file already exists, @n
 729         *                                                                                       else @c false
 730         * @exception            E_SUCCESS                               The method is successful.
 731         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred: @n
 732         *                                                                                       - The overall length of the specified path is equal to @c 0 or
 733         *                                                                                         exceeds system limitations. @n
 734         *                                                                                       - The specified path is invalid.
 735         * @exception            E_ILLEGAL_ACCESS                Access is denied due to insufficient permission. @n
 736         *                                                                                       For example, opening a read-only file in the write mode.
 737         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 738         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 739         * @exception            E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 740         * @exception        E_STORAGE_FULL                      The disk space is full.
 741         * @exception        E_IO                                        Either of the following conditions has occurred: @n
 742         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 743         *                                                                                       - %File corruption is detected.
 744         * @see                  Move()
 745         * @see                  Remove()
 746         */
 747         static result Copy(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath, bool failIfExist);
 748
 749         /**
 750         * Reads the file information such as size, attribute, creation date, and so on. @n
 751         * This method is static.
 752         *
 753         * @if OSPCOMPAT
 754         * @brief <i> [Compatibility] </i>
 755         * @endif
 756         * @since                2.0
 757         * @if OSPCOMPAT
 758         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 759         *                                       For more information, see @ref CompIoPathPage "here".
 760         * @endif
 761         *
 762         * @return               An error code
 763         * @param[in]    filePath                        The path of the file @n
 764         * @param[out]   attribute                       A %File attribute instance
 765         * @exception    E_SUCCESS                       The method is successful.
 766         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 767         *                                                                       - The overall length of the specified path is equal to @c 0 or
 768         *                                                                         exceeds system limitations. @n
 769         *                                                                       - The specified path is invalid.
 770         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 771         * @exception    E_FILE_NOT_FOUND        An entry for the specified file or path cannot be found.
 772         * @exception    E_IO                            Either of the following conditions has occurred: @n
 773         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 774         *                                                                       - %File corruption is detected.
 775         */
 776         static result GetAttributes(const Tizen::Base::String& filePath, FileAttributes& attribute);
 777
 778         /**
 779         * Gets only the file name from the specified file path. @n
 780         * For example, if the file path passed is 'xxx/file.txt', 'file.txt' is returned.
 781         *
 782         * @if OSPCOMPAT
 783         * @brief <i> [Compatibility] </i>
 784         * @endif
 785         * @since                2.0
 786         * @if OSPCOMPAT
 787         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 788         *                                       For more information, see @ref CompIoPathPage "here".
 789         * @endif
 790         *
 791         * @return               The file name of type String
 792         * @param[in]    filePath                The path of the file
 793         * @exception    E_SUCCESS               The method is successful.
 794         * @exception    E_INVALID_ARG   The length of the specified path is @c 0 or exceeds system limitations.
 795         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 796         * @see                  GetFileExtension()
 797         */
 798         static Tizen::Base::String GetFileName(const Tizen::Base::String& filePath);
 799
 800         /**
 801         * Gets the file extension of the specified file path.
 802         *
 803         * @if OSPCOMPAT
 804         * @brief <i> [Compatibility] </i>
 805         * @endif
 806         * @since                2.0
 807         * @if OSPCOMPAT
 808         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 809         *                                       For more information, see @ref CompIoPathPage "here".
 810         * @endif
 811         *
 812         * @return               The file extension, @n
 813         *                               else an empty string if the file has no extension
 814         * @param[in]    filePath                The path of the file
 815         * @exception    E_SUCCESS               The method is successful.
 816         * @exception    E_INVALID_ARG   The length of the specified path is @c 0 or exceeds system limitations.
 817         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 818         * @see                  GetFileName()
 819         */
 820         static Tizen::Base::String GetFileExtension(const Tizen::Base::String& filePath);
 821
 822         /**
 823         * Checks whether the specified file or directory exists.
 824         *
 825         * @if OSPCOMPAT
 826         * @brief <i> [Compatibility] </i>
 827         * @endif
 828         * @since                2.0
 829         * @if OSPCOMPAT
 830         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 831         *                                       For more information, see @ref CompIoPathPage "here".
 832         * @endif
 833         *
 834         * @return               @c true if file or directory exists, @n
 835         *                               else @c false
 836         * @param[in]    filePath                        The path of the file or directory
 837         * @exception    E_SUCCESS                       The method is successful.
 838         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 839         *                                                                       - The overall length of the specified path is equal to @c 0 or
 840         *                                                                         exceeds system limitations. @n
 841         *                                                                       - The specified path is invalid.
 842         * @exception    E_ILLEGAL_ACCESS        The specified path is not permitted, or
 843         *                                                                       access is denied due to insufficient permission.
 844         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 845         */
 846         static bool IsFileExist(const Tizen::Base::String& filePath);
 847
 848         /**
 849         * Converts a normal file to a secure file. @n
 850         * A secure file that is converted by this method can be shared among applications with the same key value.
 851         * This method is static.
 852         *
 853         * @if OSPCOMPAT
 854         * @brief <i> [Compatibility] </i>
 855         * @endif
 856         * @since 2.0
 857         * @if OSPCOMPAT
 858         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 859         *                                       For more information, see @ref CompIoPathPage "here".
 860         * @endif
 861         *
 862         * @return               An error code
 863         * @param[in]    plainFilePath                   The normal (non-encrypted) file path
 864         * @param[in]    secureFilePath                  The secure (encrypted) file path to create
 865         * @param[in]    key                                             A key that encrypts a secure file @n
 866         *                                                                               If the secure file is converted with a specific key value,
 867         *                                                                               applications can access the same secure file with the identical key value.
 868         * @exception    E_SUCCESS                               The method is successful.
 869         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 870         *                                                                               - The overall length of the specified path is equal to @c 0 or
 871         *                                                                                 exceeds system limitations. @n
 872         *                                                                               - The specified path is invalid. @n
 873         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 874         * @exception    E_FILE_ALREADY_EXIST    The specified file already exists.
 875         * @exception    E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 876         * @exception    E_STORAGE_FULL                  The disk space is full.
 877         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 878         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 879         *                                                                               - %File corruption is detected. @n
 880         *                                                                               - The number of opened files has exceeded the maximum limit.
 881         */
 882         static result ConvertToSecureFile(const Tizen::Base::String& plainFilePath, const Tizen::Base::String& secureFilePath, const Tizen::Base::ByteBuffer& key);
 883
 884 private:
 885         /**
 886         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 887         *
 888         * @since        2.0
 889         */
 890         File(const File& rhs);
 891
 892         /**
 893         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 894         *
 895         * @since        2.0
 896         */
 897         File& operator =(const File& rhs);
 898
 899         class _FileImpl* __pFileImpl;
 900
 901         friend class _FileImpl;
 902
 903 }; // File
 904
 905 }} // Tizen::Io
 906
 907 #endif // _FIO_FILE_H_
 908