d4297b04d3a49f106c60eb4215e6feb6d7dc36e1
[platform/framework/native/appfw.git] / 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