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 in the file */
50 FILESEEKPOSITION_END /**<The end of the file */
55 * @brief This class provides the 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 * It does not provide a Close() method 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 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 the 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 * Shared directory has data and res directories.
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.
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 the 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:
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. @n
205 * For full construction, the Construct() method must be called right after calling this constructor.
212 * This destructor overrides Tizen::Base::Object::~Object().
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.
224 * @brief <i> [Deprecated] [Compatibility] </i>
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).
230 * @compatibility This method has compatibility issues with OSP compatible applications. @n
231 * For more information, see @ref CompIoPathPage "here".
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
248 * This parameter is useful only if the specified @c openMode is "w", "w+", "a" or "a+"
249 * that allows the creation of an absent file. @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:
253 * - The overall length of the specified path is equal to @c 0 or
254 * exceeds system limitations.
255 * - The combination of the specified @c openMode is not allowed.
256 * @exception E_ILLEGAL_ACCESS The 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:
262 * - An unexpected device failure has occurred as the media ejected suddenly.
263 * - %File corruption is detected.
264 * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+",
265 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n
266 * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored
270 result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode, bool createParentDirectories);
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.
277 * @brief <i> [Compatibility] </i>
281 * @compatibility This method has compatibility issues with OSP compatible applications. @n
282 * For more information, see @ref CompIoPathPage "here".
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:
299 * - The overall length of the specified path is equal to @c 0 or
300 * exceeds system limitations.
301 * - The combination of the specified @c openMode is not allowed.
302 * @exception E_ILLEGAL_ACCESS The 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:
308 * - An unexpected device failure has occurred as the media ejected suddenly.
309 * - %File corruption is detected.
310 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
311 * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+",
312 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n
313 * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored
316 result Construct(const Tizen::Base::String& filePath, const Tizen::Base::String& openMode);
319 * Initializes this instance of %File with the specified parameters. @n
320 * This method opens an existing file or creates a new one according to the specified file opening mode.
324 * @return An error code
325 * @param[in] filePath The path of the file to open or create
326 * @param[in] pOpenMode The file opening mode @n
327 * It can be one of the following:
328 * - r : Open for reading.
329 * - r+: Open for reading and writing.
330 * - w : Open for writing. The file is created if it does not exist,
331 * otherwise it is truncated to zero length.
332 * - w+: Open for writing and reading. The file is created if it does not exist,
333 * otherwise it is truncated to zero length.
334 * - a : Open for appending. The file is created if it does not exist.
335 * - a+: Open for appending and reading. The file is created if it does not exist.
336 * @exception E_SUCCESS The method is successful.
337 * @exception E_INVALID_ARG Either of the following conditions has occurred:
338 * - The overall length of the specified path is equal to @c 0 or
339 * exceeds system limitations.
340 * - The combination of the specified @c pOpenMode is not allowed.
341 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n
342 * For example, opening a read-only file in the write mode such as "w" or "a".
343 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
344 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
345 * @exception E_STORAGE_FULL The disk space is full.
346 * @exception E_IO Either of the following conditions has occurred:
347 * - An unexpected device failure has occurred as the media ejected suddenly.
348 * - %File corruption is detected.
349 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
350 * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+",
351 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n
352 * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored
355 result Construct(const Tizen::Base::String& filePath, const char* pOpenMode);
358 * Initializes this instance of %File with the specified parameters. @n
359 * This method opens an existing secure file or creates a new one according to the specified file opening mode. @n
360 * The contents written to the secure file is automatically encrypted and the contents read from the secure file is automatically
361 * decrypted by the platform. @n
362 * Applications using this method can access the secure files that are created by other applications with an identical key value
363 * in the same device. However, the secure files created by this method cannot be accessed in other devices.
367 * @return An error code
368 * @param[in] filePath The path of the file to open or create
369 * @param[in] pOpenMode The file opening mode @n
370 * It can be one of the following:
371 * - r : Open for reading.
372 * - r+: Open for reading and writing.
373 * - w : Open for writing. The file is created if it does not exist,
374 * otherwise it is truncated to zero length.
375 * - w+: Open for writing and reading. The file is created if it does not exist,
376 * otherwise it is truncated to zero length.
377 * - a : Open for appending. The file is created if it does not exist.
378 * - a+: Open for appending and reading. The file is created if it does not exist.
379 * @param[in] secretKey The key used to encrypt the data of the file or decrypt the secure file @n
380 * If the secure file is created with a specific key value,
381 * other applications can access the secure file with an identical key value.
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_INVALID_ARG Either of the following conditions has occurred:
384 * - The overall length of the specified path is equal to @c 0 or
385 * exceeds system limitations.
386 * - The combination of the specified @c pOpenMode is not allowed.
387 * - The specified @c secretKey is incorrect or the secure file is corrupted.
388 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n
389 * For example, opening a read-only file in the write mode such as "w" or "a".
390 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
391 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
392 * @exception E_STORAGE_FULL The disk space is full.
393 * @exception E_IO Either of the following conditions has occurred:
394 * - An unexpected device failure has occurred as the media ejected suddenly.
395 * - %File corruption is detected.
396 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
397 * @remarks The valid file opening modes for this method are: "w+", "wb+", "w+b", "w", "wb", "a+",
398 * "ab+", "a+b", "a", "ab", "r+", "rb+", "r+b", "r", and "rb". @n
399 * If any other value is passed, this method throws @c E_INVALID_ARG. However, "b"(binary) open mode is ignored
402 result Construct(const Tizen::Base::String& filePath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
405 * Reads the byte data from the current file pointer. @n
406 * The user-specified ByteBuffer is filled with the byte data from the current position in the file.
407 * The read operation continues until the specified ByteBuffer is filled or the end of file is reached. @n
408 * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
412 * @return An error code
413 * @param[in, out] buffer The reference to the buffer to copy the byte data
414 * @exception E_SUCCESS The method is successful.
415 * @exception E_INVALID_ARG The specified @c buffer has no space to store the read data.
416 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
417 * - The file is not opened for read operation.
418 * - The access is denied due to insufficient permission.
419 * @exception E_END_OF_FILE The file pointer has reached the end of file.
420 * @exception E_IO Either of the following conditions has occurred:
421 * - An unexpected device failure has occurred as the media ejected suddenly.
422 * - %File corruption is detected.
423 * @remarks The ByteBuffer should be constructed before being passed to this method.
425 result Read(Tizen::Base::ByteBuffer& buffer);
428 * Reads the byte data from the current file pointer and copies it to the specified buffer. @n
429 * In the secure mode, the byte data read from the secure file is automatically decrypted by a platform security module.
433 * @return The length of the data read in bytes, @n
434 * else @c 0 in case of failure
435 * @param[out] buffer The pointer to the buffer to copy the byte data
436 * @param[in] length The buffer length in bytes
437 * @exception E_SUCCESS The method is successful.
438 * @exception E_INVALID_ARG Either of the following conditions has occurred:
439 * - The specified @c buffer contains a @c null pointer.
440 * - The length of the specified @c buffer is equal to or smaller than @c 0.
441 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
442 * - The file is not opened for read operation.
443 * - The access is denied due to insufficient permission.
444 * @exception E_END_OF_FILE The file pointer has reached the end of file.
445 * @exception E_IO Either of the following conditions has occurred:
446 * - An unexpected device failure has occurred as the media ejected suddenly.
447 * - %File corruption is detected.
448 * @remarks The specific error code can be accessed using the GetLastResult() method.
450 int Read(void* buffer, int length);
453 * Reads the string data from the current file pointer and copies it to the specified buffer. @n
454 * It is assumed that the file is in the UTF-8 format.
455 * The read operation continues until a new line character or end-of-file is reached. @n
456 * In the secure mode, the string data read from the secure file is automatically decrypted by a platform security module.
460 * @return An error code
461 * @param[out] buffer A reference to the buffer to copy the string data
462 * @exception E_SUCCESS The method is successful.
463 * @exception E_INVALID_ARG The specified @c buffer is invalid.
464 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
465 * - The file is not opened for read operation.
466 * - The access is denied due to insufficient permission.
467 * @exception E_END_OF_FILE The file pointer reached the end of file.
468 * @exception E_IO Either of the following conditions has occurred:
469 * - An unexpected device failure has occurred as the media ejected suddenly.
470 * - %File corruption is detected.
471 * @remarks To get the expected string value from a file, which is not in the UTF-8 format
472 * (Unicode or any other format), the user should use other encoding or decoding methods of the
473 * Tizen::Text namespace after reading the content of the file in binary format. @n
474 * The maximum length of characters read by this method is defined as @c 4096. @n
475 * Therefore, if the length of a single line (till a new line character or end-of-file is reached) from the current
476 * file position is longer than 4096, the rest of the characters remain as not read. @n
477 * The 'ByteBuffer' or 'void*' version of the File::Read() API can be used to overcome this limitation.
479 result Read(Tizen::Base::String& buffer);
482 * Writes the byte data from the specified Tizen::Base::ByteBuffer beginning at the current position to the limit of the %Tizen::Base::ByteBuffer
484 * In the secure mode, the byte data written is automatically encrypted to a secure file by the platform security module. @n
485 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
486 * However, the file pointer for a secure file is equal to the file pointer for an original file.
490 * @return An error code
491 * @param[in] buffer A reference to the buffer that contains the byte data to write
492 * @exception E_SUCCESS The method is successful.
493 * @exception E_INVALID_ARG The specified @c buffer is invalid.
494 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
495 * - The file is not opened for write operation.
496 * - The access is denied due to insufficient permission.
497 * @exception E_STORAGE_FULL The disk space is full.
498 * @exception E_IO Either of the following conditions has occurred:
499 * - An unexpected device failure has occurred as the media ejected suddenly.
500 * - %File corruption is detected.
502 result Write(const Tizen::Base::ByteBuffer& buffer);
505 * Writes the byte data from the specified buffer to a file. @n
506 * In the secure mode, the byte data written is automatically encrypted to a secure file by the platform security module. @n
507 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
508 * However, the file pointer for a secure file is equal to the file pointer for an original file.
512 * @return An error code
513 * @param[in] buffer A pointer to the buffer that contains the @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:
517 * - The file is not opened for write operation.
518 * - The access is denied due to insufficient permission.
519 * @exception E_INVALID_ARG Either of the following conditions has occurred:
520 * - The specified @c buffer contains a @c null pointer.
521 * - The specified @c buffer length is equal or smaller than @c 0.
522 * @exception E_STORAGE_FULL The disk space is full.
523 * @exception E_IO Either of the following conditions has occurred:
524 * - An unexpected device failure has occurred as the media ejected suddenly.
525 * - %File corruption is detected.
527 result Write(const void* buffer, int length);
530 * Writes the string data from the specified buffer to a file. @n
531 * In the secure mode, the string data written is automatically encrypted to a secure file by the platform security module. @n
532 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
533 * However, the file pointer for a secure file is equal to the file pointer for an original file.
537 * @return An error code
538 * @param[in] buffer A reference to the buffer that contains the string data to write
539 * @exception E_SUCCESS The method is successful.
540 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
541 * - The file is not opened for write operation.
542 * - The access is denied due to insufficient permission.
543 * @exception E_INVALID_ARG The specified @c buffer contains an empty string.
544 * @exception E_STORAGE_FULL The disk space is full.
545 * @exception E_IO Either of the following conditions has occurred:
546 * - An unexpected device failure has occurred as the media ejected suddenly.
547 * - %File corruption is detected.
549 result Write(const Tizen::Base::String& buffer);
552 * Flushes the internally buffered data to the kernel memory of the underlying operating system.
556 * @return An error code
557 * @exception E_SUCCESS The method is successful.
558 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
559 * @exception E_STORAGE_FULL The disk space is full.
560 * @exception E_IO Either of the following conditions has occurred:
561 * - An unexpected device failure has occurred as the media ejected suddenly.
562 * - %File corruption is detected.
567 * Gets the offset of the current file pointer relative to the beginning of the file. @n
568 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
569 * However, the file pointer for a secure file is equal to the file pointer for an original file.
573 * @return The offset of the current file pointer, @n
574 * else @c -1L if an error occurs
575 * @exception E_SUCCESS The method is successful.
576 * @exception E_IO Either of the following conditions has occurred:
577 * - An unexpected device failure has occurred as the media ejected suddenly.
578 * - %File corruption is detected.
579 * @remarks The specific error code can be accessed using the GetLastResult() method.
582 int Tell(void) const;
585 * Repositions the file pointer associated with the opened file. @n
586 * Each opened file has its own file pointer, and it points to the next byte to be read or written in the file.
587 * The repositioning offset can be specified with respect to the beginning of file, current position, or end of the file.
588 * If the file pointer is over the end-of-file, it expands the file size to the specified position and the expanded area is
589 * filled with zero. @n
590 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
591 * However, the file pointer for a secure file is equal to the file pointer for an original file.
595 * @return An error code
596 * @param[in] position The starting position to reposition the file pointer
597 * @param[in] offset The number of bytes to move a file pointer @n
598 * A negative offset moves the pointer backwards.
599 * @exception E_SUCCESS The method is successful.
600 * @exception E_INVALID_ARG The specified @c position or @c offset is invalid.
601 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
602 * @exception E_STORAGE_FULL The disk space is full.
603 * @exception E_IO Either of the following conditions has occurred:
604 * - An unexpected device failure has occurred as the media ejected suddenly.
605 * - %File corruption is detected.
606 * @see FileSeekPosition
608 result Seek(FileSeekPosition position, long offset);
611 * Truncates the file size to the specified length. @n
612 * If the specified length is less than the length of file, the bytes present between the specified @c length and size of
613 * the file are removed. If the file size is small, its size is increased. @n
614 * The size of a secure file can be greater than the size of a normal (original) file because of the encryption.
615 * However, the file pointer for a secure file is equal to the file pointer for an original file.
619 * @return An error code
620 * @param[in] length The required file size in bytes after this method is executed
621 * @exception E_SUCCESS The method is successful.
622 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
623 * - The file is not opened for write operation.
624 * - The access is denied due to insufficient permission.
625 * @exception E_INVALID_ARG The specified @c length has a negative value.
626 * @exception E_STORAGE_FULL The disk space is full.
627 * @exception E_IO Either of the following conditions has occurred:
628 * - An unexpected device failure has occurred as the media ejected suddenly.
629 * - %File corruption is detected.
631 result Truncate(int length);
634 * Gets the path associated with the %File.
638 * @return The path of the currently constructed %File, @n
639 * else an empty string in case of failure
641 Tizen::Base::String GetName(void) const;
644 * Acquires the file lock on the current opened whole file if it is not acquired. @n
645 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
650 * @return The pointer to the FileLock instance, @n
651 * else @c null pointer in case of failure
652 * @param[in] lockType The type of the file lock to be created
653 * @exception E_SUCCESS The method is successful.
654 * @exception E_INVALID_ARG The specified @c lockType is invalid.
655 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
656 * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
657 * file is not open for reading.
658 * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
659 * file is not open for writing.
660 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
661 * The lock is blocked by a lock from another process, and putting the
662 * calling process to sleep to wait for that lock to become free would
664 * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations.
665 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
667 * - The FileLock instance is invalid if the associated %File instance is deleted.
668 * - The specific error code can be accessed using the GetLastResult() method.
670 FileLock* LockN(FileLockType lockType);
673 * Acquires the file lock on the specified region of the current opened file if it is not acquired. @n
674 * If the file lock is already acquired by another process, the current process is blocked until the file lock is
679 * @return The pointer to the FileLock instance, @n
680 * else @c null pointer in case of failure
681 * @param[in] lockType The type of file lock to be created
682 * @param[in] offset The starting offset for the locked region
683 * @param[in] length The length of the locked region in bytes
684 * @exception E_SUCCESS The method is successful.
685 * @exception E_INVALID_ARG Either of the following conditions has occurred:
686 * - The specified @c lockType is invalid.
687 * - The specified @c offset or @c length is negative or is greater than
688 * the system limitation.
689 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
690 * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
691 * file is not open for reading.
692 * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
693 * file is not open for writing.
694 * @exception E_WOULD_DEADLOCK The method would cause a deadlock. @n
695 * The lock is blocked by a lock from another process, and putting the
696 * calling process to sleep to wait for that lock to become free would
698 * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations.
699 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
701 * - The FileLock instance is invalid if the associated %File instance is deleted.
702 * - The specific error code can be accessed using the GetLastResult() method.
704 FileLock* LockN(FileLockType lockType, int offset, int length);
707 * Tries to acquire the file lock on the current opened whole file. @n
708 * If the file lock is already acquired by another process, @c E_OBJECT_LOCKED is returned.
712 * @return The pointer to the FileLock instance, @n
713 * else @c null pointer in case of failure
714 * @param[in] lockType The type of file lock to be created
715 * @exception E_SUCCESS The method is successful.
716 * @exception E_INVALID_ARG The specified @c lockType is invalid.
717 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
718 * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
719 * file is not open for reading.
720 * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
721 * file is not open for writing.
722 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred:
723 * - The file lock is already held by another process.
724 * - The file to be locked has been memory-mapped by another process.
725 * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations.
726 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
728 * - The FileLock instance is invalid if the associated %File instance is deleted.
729 * - The specific error code can be accessed using the GetLastResult() method.
731 FileLock* TryToLockN(FileLockType lockType);
734 * Tries to acquire the file lock on the specified region of the current opened file. @n
735 * If the file lock is already acquired by another process, @c E_OBJECT_LOCKED is returned.
739 * @return The pointer to the FileLock instance, @n
740 * else @c null pointer in case of failure
741 * @param[in] lockType The type of file lock to be created
742 * @param[in] offset The starting offset for the locked region
743 * @param[in] length The length of the locked region in bytes
744 * @exception E_SUCCESS The method is successful.
745 * @exception E_INVALID_ARG Either of the following conditions has occurred:
746 * - The specified @c lockType is invalid.
747 * - The specified @c offset or @c length is negative or is greater than
748 * the system limitation.
749 * @exception E_INVALID_OPERATION Either of the following conditions has occurred:
750 * - The specified @c lockType cannot be @c FILE_LOCK_SHARED if the current
751 * file is not open for reading.
752 * - The specified @c lockType cannot be @c FILE_LOCK_EXCLUSIVE if the current
753 * file is not open for writing.
754 * @exception E_OBJECT_LOCKED Either of the following conditions has occurred:
755 * - The file lock is already held by another process.
756 * - The file to be locked has been memory-mapped by another process.
757 * @exception E_MAX_EXCEEDED The number of file locks has exceeded system limitations.
758 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
760 * - The FileLock instance is invalid if the associated %File instance is deleted.
761 * - The specific error code can be accessed using the GetLastResult() method.
763 FileLock* TryToLockN(FileLockType lockType, int offset, int length);
766 * Deletes the file specified. @n
767 * The opened file cannot be deleted. This method is static.
770 * @brief <i> [Compatibility] </i>
774 * @compatibility This method has compatibility issues with OSP compatible applications. @n
775 * For more information, see @ref CompIoPathPage "here".
778 * @return An error code
779 * @param[in] filePath The path of the file to delete
780 * @exception E_SUCCESS The method is successful.
781 * @exception E_INVALID_ARG Either of the following conditions has occurred:
782 * - The overall length of the specified path is equal to @c 0 or
783 * exceeds system limitations.
784 * - The specified path is invalid.
785 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n
786 * For example, opening a read-only file in the write mode.
787 * @exception E_FILE_NOT_FOUND An entry for the specified file or path cannot be found.
788 * @exception E_IO Either of the following conditions has occurred:
789 * - An unexpected device failure has occurred as the media ejected suddenly.
790 * - %File corruption is detected.
791 * @remarks The opened file cannot be deleted.
793 static result Remove(const Tizen::Base::String& filePath);
796 * Moves the specified file to the specified location. @n
797 * The opened files cannot be moved. This method is static.
800 * @brief <i> [Compatibility] </i>
804 * @compatibility This method has compatibility issues with OSP compatible applications. @n
805 * For more information, see @ref CompIoPathPage "here".
808 * @return An error code
809 * @param[in] oldFilePath The old file path
810 * @param[in] newFilePath The new file path
811 * @exception E_SUCCESS The method is successful.
812 * @exception E_INVALID_ARG Either of the following conditions has occurred:
813 * - The overall length of the specified path is equal to @c 0 or
814 * exceeds system limitations.
815 * - The specified path is invalid.
816 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n
817 * For example, opening a read-only file in the write mode.
818 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
819 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
820 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
821 * @exception E_STORAGE_FULL The disk space is full.
822 * @exception E_IO Either of the following conditions has occurred:
823 * - An unexpected device failure has occurred as the media ejected suddenly.
824 * - %File corruption is detected.
828 static result Move(const Tizen::Base::String& oldFilePath, const Tizen::Base::String& newFilePath);
831 * Copies the existing source file to the specified destination file path. @n
832 * This method is static.
836 * @return An error code
837 * @param[in] srcFilePath The source file path
838 * @param[in] destFilePath The destination file path
839 * @param[in] failIfExist Set to @c true to return an error if the destination file already exists, @n
841 * @exception E_SUCCESS The method is successful.
842 * @exception E_INVALID_ARG Either of the following conditions has occurred:
843 * - The overall length of the specified path is equal to @c 0 or
844 * exceeds system limitations.
845 * - The specified path is invalid.
846 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission. @n
847 * For example, opening a read-only file in the write mode.
848 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
849 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
850 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
851 * @exception E_STORAGE_FULL The disk space is full.
852 * @exception E_IO Either of the following conditions has occurred:
853 * - An unexpected device failure has occurred as the media ejected suddenly.
854 * - %File corruption is detected.
858 static result Copy(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath, bool failIfExist);
861 * Gets the attributes of the specified file such as size, attribute, creation date, and so on. @n
862 * This method is static.
865 * @brief <i> [Compatibility] </i>
869 * @compatibility This method has compatibility issues with OSP compatible applications. @n
870 * For more information, see @ref CompIoPathPage "here".
873 * @return An error code
874 * @param[in] filePath The path of the file
875 * @param[out] attribute A %File attribute instance
876 * @exception E_SUCCESS The method is successful.
877 * @exception E_INVALID_ARG Either of the following conditions has occurred:
878 * - The overall length of the specified path is equal to @c 0 or
879 * exceeds system limitations.
880 * - The specified path is invalid.
881 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
882 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
883 * @exception E_IO Either of the following conditions has occurred:
884 * - An unexpected device failure has occurred as the media ejected suddenly.
885 * - %File corruption is detected.
887 static result GetAttributes(const Tizen::Base::String& filePath, FileAttributes& attribute);
890 * Gets the file name from the specified file path. @n
891 * For example, if the file path passed is 'xxx/file.txt', 'file.txt' is returned.
894 * @brief <i> [Compatibility] </i>
898 * @compatibility This method has compatibility issues with OSP compatible applications. @n
899 * For more information, see @ref CompIoPathPage "here".
902 * @return The file name of type String
903 * @param[in] filePath The file path
904 * @exception E_SUCCESS The method is successful.
905 * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations.
906 * @remarks The specific error code can be accessed using the GetLastResult() method.
907 * @see GetFileExtension()
909 static Tizen::Base::String GetFileName(const Tizen::Base::String& filePath);
912 * Gets the file extension of the specified file path.
915 * @brief <i> [Compatibility] </i>
919 * @compatibility This method has compatibility issues with OSP compatible applications. @n
920 * For more information, see @ref CompIoPathPage "here".
923 * @return The file extension, @n
924 * else an empty string if the file has no extension
925 * @param[in] filePath The file path
926 * @exception E_SUCCESS The method is successful.
927 * @exception E_INVALID_ARG The length of the specified path is @c 0 or exceeds system limitations.
928 * @remarks The specific error code can be accessed using the GetLastResult() method.
931 static Tizen::Base::String GetFileExtension(const Tizen::Base::String& filePath);
934 * Checks whether the specified file or directory exists.
937 * @brief <i> [Compatibility] </i>
941 * @compatibility This method has compatibility issues with OSP compatible applications. @n
942 * For more information, see @ref CompIoPathPage "here".
945 * @return @c true if the file or directory exists, @n
947 * @param[in] filePath The path of the file or directory
948 * @exception E_SUCCESS The method is successful.
949 * @exception E_INVALID_ARG Either of the following conditions has occurred:
950 * - The overall length of the specified path is equal to @c 0 or
951 * exceeds system limitations.
952 * - The specified path is invalid.
953 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
954 * - The specified path is not permitted.
955 * - Access is denied due to insufficient permission.
956 * @remarks The specific error code can be accessed using the GetLastResult() method.
958 static bool IsFileExist(const Tizen::Base::String& filePath);
961 * Converts a normal file to a secure file. @n
962 * A secure file that is converted by this method can be shared among applications with the same key value.
963 * This method is static.
966 * @brief <i> [Compatibility] </i>
970 * @compatibility This method has compatibility issues with OSP compatible applications. @n
971 * For more information, see @ref CompIoPathPage "here".
974 * @return An error code
975 * @param[in] plainFilePath The normal (non-encrypted) file path
976 * @param[in] secureFilePath The secure (encrypted) file path to create
977 * @param[in] key The key that encrypts the secure file @n
978 * If the secure file is converted with the specific key value,
979 * applications can access the secure file with an identical key value.
980 * @exception E_SUCCESS The method is successful.
981 * @exception E_INVALID_ARG Either of the following conditions has occurred:
982 * - The overall length of the specified path is equal to @c 0 or
983 * exceeds system limitations.
984 * - The specified path is invalid.
985 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
986 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
987 * @exception E_FILE_NOT_FOUND The specified @c filePath cannot be found.
988 * @exception E_STORAGE_FULL The disk space is full.
989 * @exception E_IO Either of the following conditions has occurred:
990 * - An unexpected device failure has occurred as the media ejected suddenly.
991 * - %File corruption is detected.
992 * - The number of opened files has exceeded the maximum limit.
994 static result ConvertToSecureFile(const Tizen::Base::String& plainFilePath, const Tizen::Base::String& secureFilePath, const Tizen::Base::ByteBuffer& key);
998 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1002 File(const File& rhs);
1005 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1009 File& operator =(const File& rhs);
1011 class _FileImpl* __pFileImpl;
1013 friend class _FileImpl;
1019 #endif // _FIO_FILE_H_