2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
19 * @brief This is the header file for the %File class.
21 * This header file contains the declarations of the %File class.
27 #include <FBaseObject.h>
28 #include <FBaseString.h>
29 #include <FBaseByteBuffer.h>
30 #include <FBaseDateTime.h>
31 #include <FBaseColIList.h>
32 #include <FBaseResult.h>
33 #include <FIoFileAttributes.h>
34 #include <FIoFileLock.h>
36 namespace Tizen { namespace Io
40 * @enum FileSeekPosition
42 * Defines the file seek position.
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 */
55 * @brief This class provides the basic file I/O operations, such as read, write, create, and remove.
59 * @final This class is not intended for extension.
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.
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
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>.
86 * For more information on class features,
87 * see <a href="../org.tizen.native.appprogramming/html/guide/io/io_namespace.htm">Io Guide</a>.
89 * The following example demonstrates how to use the %File class.
97 using namespace Tizen::Base;
98 using namespace Tizen::Io;
99 using namespace Tizen::App;
103 String fileName(L"test.txt");
109 result r = E_SUCCESS;
112 r = file.Construct(App::GetInstance()->GetAppDataPath() + fileName, "w+");
118 for (i = 0; i < 10; i++)
120 buffer[i] = (char) i;
123 // Writes to the file
124 r = file.Write(buffer, 10);
130 // Repositions the file pointer
131 r = file.Seek(FILESEEKPOSITION_CURRENT, -5);
138 readCnt = file.Read(buffer2, 5);
149 // Checks the correctness of the read data
150 for (i = 0; i < readCnt; i++)
160 AppLog("Succeeded!");
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
177 * -# The path should begin with an allowed path prefix such as '/Home', '/Home/Share', '/Res', '/Share/[@e appid]',
178 * '/Media', and '/Storagecard/Media'.
180 * @section CompIoPathPageSolutionSection Resolutions
182 * - There are no specific allowed path prefixes in Tizen.
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().
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>.
198 class _OSP_EXPORT_ File
199 : public Tizen::Base::Object
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.
211 * This destructor overrides Tizen::Base::Object::~Object().
219 * Initializes this instance of %File with the specified parameters. @n
220 * This method opens an existing file or creates a new one according to the specified file opening mode.
223 * @brief <i> [Deprecated] [Compatibility] </i>
225 * @deprecated This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
226 * bool createParentDirectories=false) and File::Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode).
229 * @compatibility This method has compatibility issues with OSP compatible applications. @n
230 * For more information, see @ref CompIoPathPage "here".
233 * @return An error code
234 * @param[in] filePath The path of the file to open or create
235 * @param[in] openMode The file opening mode @n
236 * It can be one of the following:
237 * - r : Open for reading.
238 * - r+: Open for reading and writing.
239 * - w : Open for writing. The file is created if it does not exist,
240 * otherwise it is truncated to zero length.
241 * - w+: Open for writing and reading. The file is created if it does not exist,
242 * otherwise it is truncated to zero length.
243 * - a : Open for appending. The file is created if it does not exist.
244 * - a+: Open for appending and reading. The file is created if it does not exist.
245 * @param[in] createParentDirectories Set to @c true to automatically create non-existent parent directories up to destination, @n
247 * This parameter is useful only if the specified @c openMode allows creation of an absent
248 * file. For example, the following modes: "w", "w+", "a" and "a+". @n
249 * If the value of @c openMode is not any one of these, E_INVALID_ARG exception is thrown.
250 * @exception E_SUCCESS The method is successful.
251 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
252 * - The overall length of the specified path is equal to @c 0 or
253 * exceeds system limitations. @n
254 * - The combination of the specified @c openMode is not allowed. @n
255 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
256 * For example, opening a read-only file in the write mode such as "w" or "a".
257 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
258 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
259 * @exception E_STORAGE_FULL The disk space is full.
260 * @exception E_IO Either of the following conditions has occurred: @n
261 * - An unexpected device failure has occurred as the media ejected suddenly. @n
262 * - %File corruption is detected.
263 * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
264 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
265 * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
268 result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode, bool createParentDirectories);
271 * Initializes this instance of %File with the specified parameters. @n
272 * This method opens an existing file or creates a new one according to the specified file opening mode.
275 * @brief <i> [Compatibility] </i>
279 * @compatibility This method has compatibility issues with OSP compatible applications. @n
280 * For more information, see @ref CompIoPathPage "here".
283 * @return An error code
284 * @param[in] filePath The path of the file to open or create
285 * @param[in] openMode The file opening mode @n
286 * It can be one of the following:
287 * - r : Open for reading.
288 * - r+: Open for reading and writing.
289 * - w : Open for writing. The file is created if it does not exist,
290 * otherwise it is truncated to zero length.
291 * - w+: Open for writing and reading. The file is created if it does not exist,
292 * otherwise it is truncated to zero length.
293 * - a : Open for appending. The file is created if it does not exist.
294 * - a+: Open for appending and reading. The file is created if it does not exist.
295 * @exception E_SUCCESS The method is successful.
296 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
297 * - The overall length of the specified path is equal to @c 0 or
298 * exceeds system limitations. @n
299 * - The combination of the specified @c openMode is not allowed. @n
300 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
301 * For example, opening a read-only file in the write mode such as "w" or "a".
302 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
303 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
304 * @exception E_STORAGE_FULL The disk space is full.
305 * @exception E_IO Either of the following conditions has occurred: @n
306 * - An unexpected device failure has occurred as the media ejected suddenly. @n
307 * - %File corruption is detected.
308 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
309 * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
310 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
311 * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
313 result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode);
316 * Initializes this instance of %File with the specified parameters. @n
317 * This method opens an existing file or creates a new one according to the specified file opening mode.
321 * @return An error code
322 * @param[in] filePath The path of the file to open or create
323 * @param[in] pOpenMode The file opening mode @n
324 * It can be one of the following:
325 * - r : Open for reading.
326 * - r+: Open for reading and writing.
327 * - w : Open for writing. The file is created if it does not exist,
328 * otherwise it is truncated to zero length.
329 * - w+: Open for writing and reading. The file is created if it does not exist,
330 * otherwise it is truncated to zero length.
331 * - a : Open for appending. The file is created if it does not exist.
332 * - a+: Open for appending and reading. The file is created if it does not exist.
333 * @exception E_SUCCESS The method is successful.
334 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
335 * - The overall length of the specified path is equal to @c 0 or
336 * exceeds system limitations. @n
337 * - The combination of the specified @c pOpenMode is not allowed. @n
338 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
339 * For example, opening a read-only file in the write mode such as "w" or "a".
340 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
341 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
342 * @exception E_STORAGE_FULL The disk space is full.
343 * @exception E_IO Either of the following conditions has occurred: @n
344 * - An unexpected device failure has occurred as the media ejected suddenly. @n
345 * - %File corruption is detected.
346 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
347 * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
348 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
349 * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
351 result Construct(const Tizen::Base::String& filePath, const char* pOpenMode);
354 * Initializes this instance of %File with the specified parameters. @n
355 * This method opens an existing secure file or creates a new one according to the specified file opening mode. @n
356 * The contents written to the secure file is automatically encrypted and the contents read from the secure file is automatically
357 * decrypted by the platform. @n
358 * Applications using this method can access the secure files that are created by other applications with the identical key value
359 * in same device. However, the secure files created by this method cannot be accessed in other devices.
363 * @return An error code
364 * @param[in] filePath The path of the file to open or create
365 * @param[in] pOpenMode The file opening mode @n
366 * It can be one of the following:
367 * - r : Open for reading.
368 * - r+: Open for reading and writing.
369 * - w : Open for writing. The file is created if it does not exist,
370 * otherwise it is truncated to zero length.
371 * - w+: Open for writing and reading. The file is created if it does not exist,
372 * otherwise it is truncated to zero length.
373 * - a : Open for appending. The file is created if it does not exist.
374 * - a+: Open for appending and reading. The file is created if it does not exist.
375 * @param[in] secretKey A key used to encrypt data of a file or decrypt a secure file @n
376 * If a secure file is created with a specific key value,
377 * other applications can access the same secure file with the identical key value.
378 * @exception E_SUCCESS The method is successful.
379 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
380 * - The overall length of the specified path is equal to @c 0 or
381 * exceeds system limitations.
382 * - The combination of the specified @c pOpenMode is not allowed. @n
383 * - The specified @c secretKey is incorrect or the secure file is corrupted.
384 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
385 * For example, opening a read-only file in the write mode such as "w" or "a".
386 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
387 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
388 * @exception E_STORAGE_FULL The disk space is full.
389 * @exception E_IO Either of the following conditions has occurred: @n
390 * - An unexpected device failure has occurred as the media ejected suddenly. @n
391 * - %File corruption is detected. @n
392 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
393 * @remarks The following file opening mode strings are recognized by this method: "w+", "wb+", "w+b", "w", "wb", "a+",
394 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", "rb". @n
395 * Other strings lead to E_INVALID_ARG. However, "b"(binary) open mode is ignored internally.
397 result Construct(const Tizen::Base::String& filePath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
400 * Reads the byte data from the current file pointer. @n
401 * The user-specified ByteBuffer is filled with the byte data from the current position in the file.
402 * The read operation continues until the specified ByteBuffer is filled or end-of-file is met. @n
403 * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
407 * @return An error code
408 * @param[in, out] buffer A reference to the buffer that is used to receive the byte data read from the file
409 * @exception E_SUCCESS The method is successful.
410 * @exception E_INVALID_ARG The specified @c buffer has no space to store the read data.
411 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
412 * - The file is not opened for read operation. @n
413 * - Access is denied due to insufficient permission.
414 * @exception E_END_OF_FILE The file pointer has reached end-of-file.
415 * @exception E_IO Either of the following conditions has occurred: @n
416 * - An unexpected device failure has occurred as the media ejected suddenly. @n
417 * - %File corruption is detected.
418 * @remarks The ByteBuffer should be constructed before being passed to the method.
420 result Read(Tizen::Base::ByteBuffer& buffer);
423 * Reads the byte data from the current file pointer and copies it into the specified buffer. @n
424 * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
428 * @return The length of the data read in bytes, @n
429 * else @c 0 in case of failure
430 * @param[out] buffer A pointer to the user-supplied buffer where the read data is copied
431 * @param[in] length The buffer length in bytes
432 * @exception E_SUCCESS The method is successful.
433 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
434 * - The specified @c buffer contains a @c null pointer. @n
435 * - The length of the specified @c buffer is equal to or smaller than @c 0. @n
436 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
437 * - The file is not opened for read operation. @n
438 * - Access is denied due to insufficient permission.
439 * @exception E_END_OF_FILE The file pointer has reached end-of-file.
440 * @exception E_IO Either of the following conditions has occurred: @n
441 * - An unexpected device failure has occurred as the media ejected suddenly. @n
442 * - %File corruption is detected.
443 * @remarks The specific error code can be accessed using the GetLastResult() method.
445 int Read(void* buffer, int length);
448 * Reads the string data from the current file pointer and copies the string to the specified buffer (it is assumed that the
449 * file is in the UTF-8 format). @n
450 * The read operation continues until new line character or end-of-file is met. @n
451 * In the secure mode, the string data read from the secure file is automatically decrypted by a platform security module.
455 * @return An error code
456 * @param[out] buffer A reference to the buffer where the data is copied
457 * @exception E_SUCCESS The method is successful.
458 * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the
459 * memory is corrupted).
460 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
461 * - The file is not opened for read operation. @n
462 * - Access is denied due to insufficient permission.
463 * @exception E_END_OF_FILE The file pointer reached end-of-file.
464 * @exception E_IO Either of the following conditions has occurred:
465 * - An unexpected device failure has occurred as the media ejected suddenly. @n
466 * - %File corruption is detected.
467 * @remarks To get the expected string value
468 * from a file, which is not in the UTF-8 format (Unicode or any other format),
469 * user should use other encoding or decoding methods of the Tizen::Text namespace after reading the content of
470 * a file in binary format. @n
471 * The maximum length of characters read by this method is defined as 4096. @n
472 * Therefore, if the length of a single line (considering new line character or end-of-file) from the current
473 * file position is longer than 4096, the rest of the characters remain as not read. @n
474 * 'ByteBuffer' or 'void*' version of the File::Read() API can be used to overcome this limitation.
476 result Read(Tizen::Base::String& buffer);
479 * Writes the byte data from the specified ByteBuffer into a file beginning at the current position to the limit of the
481 * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n
482 * The size of a secure file can be greater than the size of a normal (original) file
483 * because of the encryption.
484 * However, the file pointer for the secure file is equal to the file pointer for the original file.
488 * @return An error code
489 * @param[in] buffer A reference to the buffer that contains byte data to write
490 * @exception E_SUCCESS The method is successful.
491 * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the
492 * memory is corrupted).
493 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
494 * - The file is not opened for write operation. @n
495 * - Access is denied due to insufficient permission.
496 * @exception E_STORAGE_FULL The disk space is full.
497 * @exception E_IO Either of the following conditions has occurred: @n
498 * - An unexpected device failure has occurred as the media ejected suddenly. @n
499 * - %File corruption is detected.
501 result Write(const Tizen::Base::ByteBuffer& buffer);
504 * Writes the byte data into a file. @n
505 * In the secure mode, the byte data written by a user is automatically encrypted to the secure file by a platform security module. @n
506 * The size of a secure file can be greater than the size of a normal (original) file
507 * because of the encryption.
508 * However, the file pointer for the secure file is equal to the file pointer for the original file.
512 * @return An error code
513 * @param[in] buffer A pointer to the user-supplied buffer that contains @c byte data to write
514 * @param[in] length The buffer length in bytes
515 * @exception E_SUCCESS The method is successful.
516 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
517 * - The file is not opened for write operation. @n
518 * - Access is denied due to insufficient permission.
519 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
520 * - The specified @c buffer contains a @c null pointer. @n
521 * - The specified @c buffer length is equal or smaller than @c 0. @n
522 * @exception E_STORAGE_FULL The disk space is full.
523 * @exception E_IO Either of the following conditions has occurred: @n
524 * - An unexpected device failure has occurred as the media ejected suddenly. @n
525 * - %File corruption is detected.
527 result Write(const void* buffer, int length);
530 * Writes the string data into a file. @n
531 * In the secure mode, the string data written by a user is automatically encrypted to the secure file by a platform security
533 * The size of a secure file can be greater than the size of a normal (original) file
534 * because of the encryption.
535 * However, the file pointer for the secure file is equal to the file pointer for the original file.
539 * @return An error code
540 * @param[in] buffer A reference to the buffer that contains string data to write
541 * @exception E_SUCCESS The method is successful.
542 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
543 * - The file is not opened for write operation. @n
544 * - Access is denied due to insufficient permission.
545 * @exception E_INVALID_ARG The specified @c buffer contains an empty string.
546 * @exception E_STORAGE_FULL The disk space is full.
547 * @exception E_IO Either of the following conditions has occurred: @n
548 * - An unexpected device failure has occurred as the media ejected suddenly. @n
549 * - %File corruption is detected.
551 result Write(const Tizen::Base::String& buffer);
554 * Flushes the internally buffered data.
558 * @return An error code
559 * @exception E_SUCCESS The method is successful.
560 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
561 * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the
562 * memory is corrupted).
563 * @exception E_IO Either of the following conditions has occurred: @n
564 * - An unexpected device failure has occurred as the media ejected suddenly. @n
565 * - %File corruption is detected.
570 * Gets the offset of the current file pointer relative to the beginning of the file. @n
571 * The size of a secure file can be greater than the size of a normal (original) file
572 * because of the encryption.
573 * However, the file pointer for the secure file is equal to the file pointer for the original file.
577 * @return The offset of the current file pointer, @n
578 * else @c -1L if an error occurs
579 * @exception E_SUCCESS The method is successful.
580 * @exception E_INVALID_ARG The file handle is invalid (either the file is closed by another method, or the
581 * memory is corrupted).
582 * @exception E_IO Either of the following conditions has occurred: @n
583 * - An unexpected device failure has occurred as the media ejected suddenly. @n
584 * - %File corruption is detected.
585 * @remarks The specific error code can be accessed using the GetLastResult() method.
588 int Tell(void) const;
591 * Repositions the file pointer associated with an opened file. @n
592 * Each opened file has its own file pointer, and it points to the next byte to be read or written in the file.
593 * The repositioning offset can be specified with respect to the beginning of file, current position, or end of the file.
594 * If the file pointer is over the end-of-file, it expands the file size to the specified position and the expanded area is
595 * filled with zero. @n
596 * The size of a secure file can be greater than the size of a normal (original) file
597 * because of the encryption.
598 * However, the file pointer for the secure file is equal to the file pointer for the original file.
602 * @return An error code
603 * @param[in] position The origin from where to start the repositioning a file pointer
604 * @param[in] offset The number of bytes to move a file pointer @n
605 * A negative offset moves the pointer backwards.
606 * @exception E_SUCCESS The method is successful.
607 * @exception E_INVALID_ARG The specified @c position or @c offset is invalid.
608 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
609 * @exception E_STORAGE_FULL The disk space is full.
610 * @exception E_IO Either of the following conditions has occurred: @n
611 * - An unexpected device failure has occurred as the media ejected suddenly. @n
612 * - %File corruption is detected.
613 * @see FileSeekPosition
615 result Seek(FileSeekPosition position, long offset);
618 * Truncates the file size to the specified length. @n
619 * If the specified length is less than the length of file, the bytes present between the @c length and size of a file are
621 * If the file size is small, its size is increased. @n
622 * The size of a secure file can be greater than the size of a normal (original) file
623 * because of the encryption.
624 * However, the file pointer for a secure file is equal to the file pointer for an original file.
628 * @return An error code
629 * @param[in] length The required file size in bytes after this method is executed
630 * @exception E_SUCCESS The method is successful.
631 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
632 * - The file is not opened for write operation. @n
633 * - Access is denied due to insufficient permission.
634 * @exception E_INVALID_ARG The specified @c length has a negative value.
635 * @exception E_STORAGE_FULL The disk space is full.
636 * @exception E_IO Either of the following conditions has occurred: @n
637 * - An unexpected device failure has occurred as the media ejected suddenly. @n
638 * - %File corruption is detected.
640 result Truncate(int length);
643 * Gets the path associated with a constructed %File.
647 * @return The file path to the currently constructed %File if successful, @n
648 * else an empty string in case of failure
650 Tizen::Base::String GetName(void) const;
653 * Acquires the file lock on the current opened whole file if it is not acquired.
654 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
659 * @return The pointer to %FileLock instance, @n
660 * else @c null pointer in case of failure
661 * @param[in] lockType The type of file lock to be created
662 * @exception E_SUCCESS The method is successful.
663 * @exception E_INVALID_ARG The specified @c lockType is invalid.
664 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
665 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
666 * file is not open for reading. @n
667 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
668 * file is not open for writing. @n
669 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
670 * The lock is blocked by a lock from another process, and putting the
671 * calling process to sleep to wait for that lock to become free would
673 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
674 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
675 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
676 * The specific error code can be accessed using the GetLastResult() method.
677 * @see Tizen::Io::File::FileLockType
679 FileLock* LockN(FileLockType lockType);
682 * Acquires the file lock on the specified region of the current opened file if it is not acquired.
683 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
688 * @return The pointer to %FileLock instance, @n
689 * else @c null pointer in case of failure
690 * @param[in] lockType The type of file lock to be created
691 * @param[in] offset The starting offset for the locked region
692 * @param[in] length The length of the locked region in bytes
693 * @exception E_SUCCESS The method is successful.
694 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
695 * - The specified @c lockType is invalid.
696 * - The specified @c offset or @c length is negative or is greater than
697 * the system limitation.
698 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
699 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
700 * file is not open for reading. @n
701 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
702 * file is not open for writing. @n
703 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
704 * The lock is blocked by a lock from another process, and putting the
705 * calling process to sleep to wait for that lock to become free would
707 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
708 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
709 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
710 * The specific error code can be accessed using the GetLastResult() method.
711 * @see Tizen::Io::File::FileLockType
713 FileLock* LockN(FileLockType lockType, int offset, int length);
716 * Tries to acquire the file lock on the current opened whole file.
717 * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned.
721 * @return The pointer to %FileLock instance, @n
722 * else @c null pointer in case of failure
723 * @param[in] lockType The type of file lock to be created
724 * @exception E_SUCCESS The method is successful.
725 * @exception E_INVALID_ARG The specified @c lockType is invalid.
726 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
727 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
728 * file is not open for reading. @n
729 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
730 * file is not open for writing. @n
731 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n
732 * - The file lock is already held by another process. @n
733 * - The file to be locked has been memory-mapped by another process.
734 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
735 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
736 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
737 * The specific error code can be accessed using the GetLastResult() method.
738 * @see Tizen::Io::File::FileLockType
740 FileLock* TryToLockN(FileLockType lockType);
743 * Tries to acquire the file lock on the specified region of the current opened file.
744 * If the file lock is already acquired by another process, E_OBJECT_LOCKED is returned.
748 * @return The pointer to %FileLock instance, @n
749 * else @c null pointer in case of failure
750 * @param[in] lockType The type of file lock to be created
751 * @param[in] offset The starting offset for the locked region
752 * @param[in] length The length of the locked region in bytes
753 * @exception E_SUCCESS The method is successful.
754 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
755 * - The specified @c lockType is invalid.
756 * - The specified @c offset or @c length is negative or is greater than
757 * the system limitation.
758 * @exception E_INVALID_OPERATION Either of the following conditions has occurred: @n
759 * - The specified @c lockType cannot be FILE_LOCK_SHARED if the current
760 * file is not open for reading. @n
761 * - The specified @c lockType cannot be FILE_LOCK_EXCLUSIVE if the current
762 * file is not open for writing. @n
763 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred: @n
764 * - The file lock is already held by another process. @n
765 * - The file to be locked has been memory-mapped by another process.
766 * @exception E_MAX_EXCEEDED The number of file lock exceeds system limitations.
767 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
768 * @remarks The %FileLock instance is invalid if the associated %File instance is deleted. @n
769 * The specific error code can be accessed using the GetLastResult() method.
770 * @see Tizen::Io::File::FileLockType
772 FileLock* TryToLockN(FileLockType lockType, int offset, int length);
775 * Deletes the file specified. @n
776 * The opened file cannot be deleted. This method is static.
779 * @brief <i> [Compatibility] </i>
783 * @compatibility This method has compatibility issues with OSP compatible applications. @n
784 * For more information, see @ref CompIoPathPage "here".
787 * @return An error code
788 * @param[in] filePath The path of the file to delete
789 * @exception E_SUCCESS The method is successful.
790 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
791 * - The overall length of the specified path is equal to @c 0 or
792 * exceeds system limitations. @n
793 * - The specified path is invalid.
794 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
795 * For example, opening a read-only file in the write mode.
796 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
797 * @exception E_IO Either of the following conditions has occurred: @n
798 * - An unexpected device failure has occurred as the media ejected suddenly. @n
799 * - %File corruption is detected.
800 * @remarks The opened file cannot be deleted.
802 static result Remove(const Tizen::Base::String& filePath);
805 * Moves the specified file to another location. @n
806 * The opened files cannot be moved. This method is static.
809 * @brief <i> [Compatibility] </i>
813 * @compatibility This method has compatibility issues with OSP compatible applications. @n
814 * For more information, see @ref CompIoPathPage "here".
817 * @return An error code
818 * @param[in] oldFilePath The old file path
819 * @param[in] newFilePath The new file path
820 * @exception E_SUCCESS The method is successful.
821 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
822 * - The overall length of the specified path is equal to @c 0 or
823 * exceeds system limitations. @n
824 * - The specified path is invalid.
825 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
826 * For example, opening a read-only file in the write mode.
827 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
828 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
829 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
830 * @exception E_STORAGE_FULL The disk space is full.
831 * @exception E_IO Either of the following conditions has occurred: @n
832 * - An unexpected device failure has occurred as the media ejected suddenly. @n
833 * - %File corruption is detected.
837 static result Move(const Tizen::Base::String& oldFilePath, const Tizen::Base::String& newFilePath);
840 * Copies the existing source file to the destined location. @n
841 * This method is static.
845 * @return An error code
846 * @param[in] srcFilePath The source file path
847 * @param[in] destFilePath The destination file path
848 * @param[in] failIfExist Set to @c true to return an error if the destination file already exists, @n
850 * @exception E_SUCCESS The method is successful.
851 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
852 * - The overall length of the specified path is equal to @c 0 or
853 * exceeds system limitations. @n
854 * - The specified path is invalid.
855 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission. @n
856 * For example, opening a read-only file in the write mode.
857 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
858 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
859 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
860 * @exception E_STORAGE_FULL The disk space is full.
861 * @exception E_IO Either of the following conditions has occurred: @n
862 * - An unexpected device failure has occurred as the media ejected suddenly. @n
863 * - %File corruption is detected.
867 static result Copy(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath, bool failIfExist);
870 * Reads the file information such as size, attribute, creation date, and so on. @n
871 * This method is static.
874 * @brief <i> [Compatibility] </i>
878 * @compatibility This method has compatibility issues with OSP compatible applications. @n
879 * For more information, see @ref CompIoPathPage "here".
882 * @return An error code
883 * @param[in] filePath The path of the file @n
884 * @param[out] attribute A %File attribute instance
885 * @exception E_SUCCESS The method is successful.
886 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
887 * - The overall length of the specified path is equal to @c 0 or
888 * exceeds system limitations. @n
889 * - The specified path is invalid.
890 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
891 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
892 * @exception E_IO Either of the following conditions has occurred: @n
893 * - An unexpected device failure has occurred as the media ejected suddenly. @n
894 * - %File corruption is detected.
896 static result GetAttributes(const Tizen::Base::String& filePath, FileAttributes& attribute);
899 * Gets only the file name from the specified file path. @n
900 * For example, if the file path passed is 'xxx/file.txt', 'file.txt' is returned.
903 * @brief <i> [Compatibility] </i>
907 * @compatibility This method has compatibility issues with OSP compatible applications. @n
908 * For more information, see @ref CompIoPathPage "here".
911 * @return The file name of type String
912 * @param[in] filePath The path of the file
913 * @exception E_SUCCESS The method is successful.
914 * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations.
915 * @remarks The specific error code can be accessed using the GetLastResult() method.
916 * @see GetFileExtension()
918 static Tizen::Base::String GetFileName(const Tizen::Base::String& filePath);
921 * Gets the file extension of the specified file path.
924 * @brief <i> [Compatibility] </i>
928 * @compatibility This method has compatibility issues with OSP compatible applications. @n
929 * For more information, see @ref CompIoPathPage "here".
932 * @return The file extension, @n
933 * else an empty string if the file has no extension
934 * @param[in] filePath The path of the file
935 * @exception E_SUCCESS The method is successful.
936 * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations.
937 * @remarks The specific error code can be accessed using the GetLastResult() method.
940 static Tizen::Base::String GetFileExtension(const Tizen::Base::String& filePath);
943 * Checks whether the specified file or directory exists.
946 * @brief <i> [Compatibility] </i>
950 * @compatibility This method has compatibility issues with OSP compatible applications. @n
951 * For more information, see @ref CompIoPathPage "here".
954 * @return @c true if file or directory exists, @n
956 * @param[in] filePath The path of the file or directory
957 * @exception E_SUCCESS The method is successful.
958 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
959 * - The overall length of the specified path is equal to @c 0 or
960 * exceeds system limitations. @n
961 * - The specified path is invalid.
962 * @exception E_ILLEGAL_ACCESS The specified path is not permitted, or
963 * access is denied due to insufficient permission.
964 * @remarks The specific error code can be accessed using the GetLastResult() method.
966 static bool IsFileExist(const Tizen::Base::String& filePath);
969 * Converts a normal file to a secure file. @n
970 * A secure file that is converted by this method can be shared among applications with the same key value.
971 * This method is static.
974 * @brief <i> [Compatibility] </i>
978 * @compatibility This method has compatibility issues with OSP compatible applications. @n
979 * For more information, see @ref CompIoPathPage "here".
982 * @return An error code
983 * @param[in] plainFilePath The normal (non-encrypted) file path
984 * @param[in] secureFilePath The secure (encrypted) file path to create
985 * @param[in] key A key that encrypts a secure file @n
986 * If the secure file is converted with a specific key value,
987 * applications can access the same secure file with the identical key value.
988 * @exception E_SUCCESS The method is successful.
989 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
990 * - The overall length of the specified path is equal to @c 0 or
991 * exceeds system limitations. @n
992 * - The specified path is invalid. @n
993 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
994 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
995 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
996 * @exception E_STORAGE_FULL The disk space is full.
997 * @exception E_IO Either of the following conditions has occurred: @n
998 * - An unexpected device failure has occurred as the media ejected suddenly. @n
999 * - %File corruption is detected. @n
1000 * - The number of opened files has exceeded the maximum limit.
1002 static result ConvertToSecureFile(const Tizen::Base::String& plainFilePath, const Tizen::Base::String& secureFilePath, const Tizen::Base::ByteBuffer& key);
1006 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1010 File(const File& rhs);
1013 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1017 File& operator =(const File& rhs);
1019 class _FileImpl* __pFileImpl;
1021 friend class _FileImpl;
1027 #endif // _FIO_FILE_H_