1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - FS - include
3   File:     file.h
4 
5   Copyright 2007-2008 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-12-05#$
14   $Rev: 9524 $
15   $Author: yosizaki $
16 
17  *---------------------------------------------------------------------------*/
18 
19 
20 #if	!defined(NITRO_FS_FILE_H_)
21 #define NITRO_FS_FILE_H_
22 
23 
24 #include <nitro/fs/archive.h>
25 
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 
32 /*---------------------------------------------------------------------------*/
33 /* Declarations */
34 
35 // File structure
36 typedef struct FSFile
37 {
38 // private:
39     struct FSFile              *next;
40     void                       *userdata;
41     struct FSArchive           *arc;
42     u32                         stat;
43     void                       *argument;
44     FSResult                    error;
45     OSThreadQueue               queue[1];
46 
47     union
48     {
49         u8                      reserved1[16];
50         FSROMFATProperty        prop;
51     };
52     union
53     {
54         u8                      reserved2[24];
55         FSROMFATCommandInfo     arg;
56     };
57 }
58 FSFile;
59 
60 
61 SDK_COMPILER_ASSERT(sizeof(FSFile) == 72);
62 
63 
64 /*---------------------------------------------------------------------------*/
65 /* Functions */
66 
67 /*---------------------------------------------------------------------------*
68   Name:         FS_InitFile
69 
70   Description:  Initializes an FSFile structure.
71 
72   Arguments:    file: An FSFile structure
73 
74   Returns:      None.
75  *---------------------------------------------------------------------------*/
76 void    FS_InitFile(FSFile *file);
77 
78 /*---------------------------------------------------------------------------*
79   Name:         FS_GetAttachedArchive
80 
81   Description:  Gets the archive associated with a file or directory.
82 
83   Arguments:    file: A file or directory handle
84 
85   Returns:      The archive for the handle if it is being held, and NULL otherwise.
86  *---------------------------------------------------------------------------*/
FS_GetAttachedArchive(const FSFile * file)87 SDK_INLINE FSArchive *FS_GetAttachedArchive(const FSFile *file)
88 {
89     return file->arc;
90 }
91 /*---------------------------------------------------------------------------*
92   Name:         FS_IsBusy
93 
94   Description:  Determines if a file is processing a command.
95 
96   Arguments:    file: The FSFile structure that issued the command.
97 
98   Returns:      TRUE if the command is being processed.
99  *---------------------------------------------------------------------------*/
FS_IsBusy(volatile const FSFile * file)100 SDK_INLINE BOOL FS_IsBusy(volatile const FSFile *file)
101 {
102     return ((file->stat & FS_FILE_STATUS_BUSY) != 0);
103 }
104 
105 /*---------------------------------------------------------------------------*
106   Name:         FS_IsCanceling
107 
108   Description:  Determines if a file is cancelling a command.
109 
110   Arguments:    file: The FSFile structure that issued the command.
111 
112   Returns:      TRUE if the command is being cancelled.
113  *---------------------------------------------------------------------------*/
FS_IsCanceling(volatile const FSFile * file)114 SDK_INLINE BOOL FS_IsCanceling(volatile const FSFile *file)
115 {
116     return ((file->stat & FS_FILE_STATUS_CANCEL) != 0);
117 }
118 
119 /*---------------------------------------------------------------------------*
120   Name:         FS_IsSucceeded
121 
122   Description:  Determines if the most recent command completed successfully.
123 
124   Arguments:    file: The FSFile structure that issued the command.
125 
126   Returns:      TRUE if the command completed successfully.
127  *---------------------------------------------------------------------------*/
FS_IsSucceeded(volatile const FSFile * file)128 SDK_INLINE BOOL FS_IsSucceeded(volatile const FSFile *file)
129 {
130     return (file->error == FS_RESULT_SUCCESS);
131 }
132 
133 /*---------------------------------------------------------------------------*
134   Name:         FS_IsFile
135 
136   Description:  Determines if a handle represents an open file.
137 
138   Arguments:    file: An FSFile structure
139 
140   Returns:      TRUE if the file handle is being held.
141  *---------------------------------------------------------------------------*/
FS_IsFile(volatile const FSFile * file)142 SDK_INLINE BOOL FS_IsFile(volatile const FSFile *file)
143 {
144     return ((file->stat & FS_FILE_STATUS_IS_FILE) != 0);
145 }
146 
147 /*---------------------------------------------------------------------------*
148   Name:         FS_IsDir
149 
150   Description:  Determines if a handle represents an open directory.
151 
152   Arguments:    file: An FSFile structure
153 
154   Returns:      TRUE if the directory handle is being held.
155  *---------------------------------------------------------------------------*/
FS_IsDir(volatile const FSFile * file)156 SDK_INLINE BOOL FS_IsDir(volatile const FSFile *file)
157 {
158     return ((file->stat & FS_FILE_STATUS_IS_DIR) != 0);
159 }
160 
161 /*---------------------------------------------------------------------------*
162   Name:         FS_GetResultCode
163 
164   Description:  Gets the value of the most recent command result.
165 
166   Arguments:    file: An FSFile structure
167 
168   Returns:      The value of the most recent command result.
169  *---------------------------------------------------------------------------*/
FS_GetResultCode(volatile const FSFile * file)170 SDK_INLINE FSResult FS_GetResultCode(volatile const FSFile *file)
171 {
172     return file->error;
173 }
174 
175 /*---------------------------------------------------------------------------*
176   Name:         FS_WaitAsync
177 
178   Description:  Blocks until asynchronous commands have completed.
179 
180   Arguments:    file: File handle
181 
182   Returns:      TRUE if the command is successful.
183  *---------------------------------------------------------------------------*/
184 BOOL    FS_WaitAsync(FSFile *file);
185 
186 /*---------------------------------------------------------------------------*
187   Name:         FS_CancelFile
188 
189   Description:  Requests that asynchronous commands be cancelled.
190 
191   Arguments:    file: File handle
192 
193   Returns:      None.
194  *---------------------------------------------------------------------------*/
195 void    FS_CancelFile(FSFile *file);
196 
197 /*---------------------------------------------------------------------------*
198   Name:         FS_SetFileHandle
199 
200   Description:  Initializes a file structure as a file handle.
201                 This function is called from the archive implementation to support the OpenFile command.
202 
203 
204   Arguments:    file: An FSFile structure
205                 arc: The archive with which to associate
206                 userdata: Arbitrary archive-defined data to maintain file handle information
207 
208 
209   Returns:      None.
210  *---------------------------------------------------------------------------*/
FS_SetFileHandle(FSFile * file,FSArchive * arc,void * userdata)211 SDK_INLINE void FS_SetFileHandle(FSFile *file, FSArchive *arc, void *userdata)
212 {
213     file->stat |= FS_FILE_STATUS_IS_FILE;
214     file->stat &= ~FS_FILE_STATUS_IS_DIR;
215     file->arc = arc;
216     file->userdata = userdata;
217 }
218 
219 /*---------------------------------------------------------------------------*
220   Name:         FS_SetDirectoryHandle
221 
222   Description:  Initializes a file structure as a directory handle.
223                 This function is called from the archive implementation to support the OpenDirectory command.
224 
225 
226   Arguments:    file: An FSFile structure
227                 arc: The archive with which to associate
228                 userdata: Arbitrary archive-defined data to maintain directory handle information
229 
230 
231   Returns:      None.
232  *---------------------------------------------------------------------------*/
FS_SetDirectoryHandle(FSFile * file,FSArchive * arc,void * userdata)233 SDK_INLINE void FS_SetDirectoryHandle(FSFile *file, FSArchive *arc, void *userdata)
234 {
235     file->stat |= FS_FILE_STATUS_IS_DIR;
236     file->stat &= ~FS_FILE_STATUS_IS_FILE;
237     file->arc = arc;
238     file->userdata = userdata;
239 }
240 
241 /*---------------------------------------------------------------------------*
242   Name:         FS_DetachHandle
243 
244   Description:  Initializes a file structure as an invalid handle.
245                 This function is called from the archive implementation to support the CloseFile and CloseDirectory commands.
246 
247 
248   Arguments:    file: An FSFile structure
249 
250   Returns:      None.
251  *---------------------------------------------------------------------------*/
FS_DetachHandle(FSFile * file)252 SDK_INLINE void FS_DetachHandle(FSFile *file)
253 {
254     file->userdata = NULL;
255     file->stat &= ~(FS_FILE_STATUS_IS_FILE | FS_FILE_STATUS_IS_DIR);
256 }
257 
258 /*---------------------------------------------------------------------------*
259   Name:         FS_GetFileUserData
260 
261   Description:  Gets archive-defined data associated with a file structure.
262                 This is called from the archive implementation.
263 
264   Arguments:    file: An FSFile structure
265 
266   Returns:      Archive-defined data associated with a file structure.
267  *---------------------------------------------------------------------------*/
FS_GetFileUserData(const FSFile * file)268 SDK_INLINE void* FS_GetFileUserData(const FSFile *file)
269 {
270     return file->userdata;
271 }
272 
273 /*---------------------------------------------------------------------------*
274   Name:         FS_GetPathName
275 
276   Description:  Gets the full path name to the specified file or directory.
277 
278   Arguments:    file: A file or directory handle
279                 buffer: Location to store the path name
280                 length: The buffer size
281 
282   Returns:      TRUE if it could be obtained properly, including the terminating '\0'.
283  *---------------------------------------------------------------------------*/
284 BOOL    FS_GetPathName(FSFile *file, char *buffer, u32 length);
285 
286 /*---------------------------------------------------------------------------*
287   Name:         FS_GetPathLength
288 
289   Description:  Gets the length of the full path name to the specified file or directory.
290 
291   Arguments:    file: A file or directory handle
292 
293   Returns:      The length of the path name, including the terminating '\0', on success and -1 on failure.
294  *---------------------------------------------------------------------------*/
295 s32     FS_GetPathLength(FSFile *file);
296 
297 /*---------------------------------------------------------------------------*
298   Name:         FS_CreateFile
299 
300   Description:  Creates a file.
301 
302   Arguments:    path: Path name
303                 mode: Access mode
304 
305   Returns:      TRUE if the file was created normally.
306  *---------------------------------------------------------------------------*/
307 BOOL    FS_CreateFile(const char *path, u32 permit);
308 
309 /*---------------------------------------------------------------------------*
310   Name:         FS_DeleteFile
311 
312   Description:  Deletes a file.
313 
314   Arguments:    path: Path name
315 
316   Returns:      TRUE if the file was deleted normally.
317  *---------------------------------------------------------------------------*/
318 BOOL    FS_DeleteFile(const char *path);
319 
320 /*---------------------------------------------------------------------------*
321   Name:         FS_RenameFile
322 
323   Description:  Renames a file.
324 
325   Arguments:    src: The original filename to change.
326                 dst: The new filename to change to.
327 
328   Returns:      TRUE if the file was renamed normally.
329  *---------------------------------------------------------------------------*/
330 BOOL    FS_RenameFile(const char *src, const char *dst);
331 
332 /*---------------------------------------------------------------------------*
333   Name:         FS_GetPathInfo
334 
335   Description:  Gets information for a file or directory.
336 
337   Arguments:    path: Path name
338                 info: Location to store the information
339 
340   Returns:      Processing result
341  *---------------------------------------------------------------------------*/
342 BOOL    FS_GetPathInfo(const char *path, FSPathInfo *info);
343 
344 /*---------------------------------------------------------------------------*
345   Name:         FS_SetPathInfo
346 
347   Description:  Sets information for a file or directory.
348 
349   Arguments:    path: Path name
350                 info: Location to store the information
351 
352   Returns:      Processing result
353  *---------------------------------------------------------------------------*/
354 BOOL    FS_SetPathInfo(const char *path, const FSPathInfo *info);
355 
356 /*---------------------------------------------------------------------------*
357   Name:         FS_CreateDirectory
358 
359   Description:  Creates a directory.
360 
361   Arguments:    path: Path name
362                 mode: Access mode
363 
364   Returns:      TRUE if the directory was created normally.
365  *---------------------------------------------------------------------------*/
366 BOOL    FS_CreateDirectory(const char *path, u32 permit);
367 
368 /*---------------------------------------------------------------------------*
369   Name:         FS_DeleteDirectory
370 
371   Description:  Deletes a directory.
372 
373   Arguments:    path: Path name
374 
375   Returns:      TRUE if the directory was deleted normally.
376  *---------------------------------------------------------------------------*/
377 BOOL    FS_DeleteDirectory(const char *path);
378 
379 /*---------------------------------------------------------------------------*
380   Name:         FS_RenameDirectory
381 
382   Description:  Renames a directory.
383 
384   Arguments:    src: The original directory name to change.
385                 dst: The new directory name to change to.
386 
387   Returns:      TRUE if the directory was renamed normally.
388  *---------------------------------------------------------------------------*/
389 BOOL    FS_RenameDirectory(const char *src, const char *dst);
390 
391 /*---------------------------------------------------------------------------*
392   Name:         FS_CreateFileAuto
393 
394   Description:  Creates a file along with required intermediate directories.
395 
396   Arguments:    path: Path name
397                 permit: Access mode
398 
399   Returns:      TRUE if the file was created normally.
400  *---------------------------------------------------------------------------*/
401 BOOL FS_CreateFileAuto(const char *path, u32 permit);
402 
403 /*---------------------------------------------------------------------------*
404   Name:         FS_DeleteFileAuto
405 
406   Description:  Deletes a file along with required intermediate directories.
407 
408   Arguments:    path: Path name
409 
410   Returns:      TRUE if the file was deleted normally.
411  *---------------------------------------------------------------------------*/
412 BOOL FS_DeleteFileAuto(const char *path);
413 
414 /*---------------------------------------------------------------------------*
415   Name:         FS_RenameFileAuto
416 
417   Description:  Changes a filename along with required intermediate directories.
418 
419   Arguments:    src: The original filename to change.
420                 dst: The new filename to change to.
421 
422   Returns:      TRUE if the file was renamed normally.
423  *---------------------------------------------------------------------------*/
424 BOOL FS_RenameFileAuto(const char *src, const char *dst);
425 
426 /*---------------------------------------------------------------------------*
427   Name:         FS_CreateDirectoryAuto
428 
429   Description:  Creates a directory along with required intermediate directories.
430 
431   Arguments:    path: The directory name to create
432                 permit: Access mode
433 
434   Returns:      TRUE if the directory was created normally.
435  *---------------------------------------------------------------------------*/
436 BOOL FS_CreateDirectoryAuto(const char *path, u32 permit);
437 
438 /*---------------------------------------------------------------------------*
439   Name:         FS_DeleteDirectoryAuto
440 
441   Description:  Recursively deletes a directory.
442 
443   Arguments:    path: Path name
444 
445   Returns:      TRUE if the directory was deleted normally.
446  *---------------------------------------------------------------------------*/
447 BOOL FS_DeleteDirectoryAuto(const char *path);
448 
449 /*---------------------------------------------------------------------------*
450   Name:         FS_RenameDirectoryAuto
451 
452   Description:  Renames a directory, automatically creating any required intermediate directories.
453 
454   Arguments:    src: The original directory name to change.
455                 dst: The new directory name to change to.
456 
457   Returns:      TRUE if the directory was renamed normally.
458  *---------------------------------------------------------------------------*/
459 BOOL FS_RenameDirectoryAuto(const char *src, const char *dst);
460 
461 /*---------------------------------------------------------------------------*
462   Name:         FS_GetArchiveResource
463 
464   Description:  Gets resource information for the specified archive.
465 
466   Arguments:    path: Path name that can specify an archive
467                 resource: Location to store the obtained resource information
468 
469   Returns:      TRUE if the resource information was obtained normally.
470  *---------------------------------------------------------------------------*/
471 BOOL    FS_GetArchiveResource(const char *path, FSArchiveResource *resource);
472 
473 /*---------------------------------------------------------------------------*
474   Name:         FSi_GetSpaceToCreateDirectoryEntries
475 
476   Description:  Estimates the space required to store the directory entries that will be created at the same time as a file.
477                 (This assumes directories that already exist in the path will need to be re-created)
478 
479   Arguments:    path: The path name for the file to create.
480                 bytesPerCluster: Number of bytes for each cluster in the file system.
481 
482   Returns:      Space required to store the directory entries.
483  *---------------------------------------------------------------------------*/
484 u32  FSi_GetSpaceToCreateDirectoryEntries(const char *path, const u32 bytesPerCluster);
485 
486 /*---------------------------------------------------------------------------*
487   Name:         FS_HasEnoughSpaceToCreateFile
488 
489   Description:  Determines if it is currently possible to create a file with the specified path name and size.
490 
491   Arguments:    resource: Archive information obtained in advance with the FS_GetArchiveResource function.
492                             When the function succeeds, each of the sizes will be decreased only by the amount that the file consumes.
493                 path: The path name for the file to create.
494                 size: The size of the file to create.
495 
496   Returns:      TRUE if a file can be created with the specified path name and size.
497  *---------------------------------------------------------------------------*/
498 BOOL FS_HasEnoughSpaceToCreateFile(FSArchiveResource *resource, const char *path, u32 size);
499 
500 /*---------------------------------------------------------------------------*
501   Name:         FS_IsArchiveReady
502 
503   Description:  Determines if the specified archive is currently usable.
504 
505   Arguments:    path: An absolute path that starts with "archive_name:"
506 
507   Returns:      TRUE if the specified archive is currently usable.
508                 FALSE for an archive on an SD Card that has not been inserted in the slot, or a save data archive that has not been imported.
509 
510  *---------------------------------------------------------------------------*/
511 BOOL FS_IsArchiveReady(const char *path);
512 
513 /*---------------------------------------------------------------------------*
514   Name:         FS_OpenFileEx
515 
516   Description:  Specifies a path name and opens a file.
517 
518   Arguments:    file: An FSFile structure
519                 path: Path name
520                 mode: Access mode
521 
522   Returns:      TRUE on success.
523  *---------------------------------------------------------------------------*/
524 BOOL FS_OpenFileEx(FSFile *file, const char *path, u32 mode);
525 
526 /*---------------------------------------------------------------------------*
527   Name:         FS_ConvertPathToFileID
528 
529   Description:  Gets the file ID from a path name.
530 
531   Arguments:    p_fileid: Location to store the FSFileID
532                 path: Path name
533 
534   Returns:      TRUE on success.
535  *---------------------------------------------------------------------------*/
536 BOOL    FS_ConvertPathToFileID(FSFileID *p_fileid, const char *path);
537 
538 /*---------------------------------------------------------------------------*
539   Name:         FS_OpenFileFast
540 
541   Description:  Specifies a file ID and opens a file.
542 
543   Arguments:    file: An FSFile structure
544                 fileid: File ID obtained by a function such as FS_ReadDir
545 
546   Returns:      TRUE on success.
547  *---------------------------------------------------------------------------*/
548 BOOL    FS_OpenFileFast(FSFile *file, FSFileID fileid);
549 
550 /*---------------------------------------------------------------------------*
551   Name:         FS_OpenFileDirect
552 
553   Description:  Directly maps an offset into an archive and opens a file.
554 
555   Arguments:    file: An FSFile structure
556                 arc: Archive to map the file
557                 top: Offset to the start of the file image
558                 bottom: Offset to the end of the file image
559                 fileid: Arbitrary file ID to assign
560 
561   Returns:      TRUE on success.
562  *---------------------------------------------------------------------------*/
563 BOOL    FS_OpenFileDirect(FSFile *file, FSArchive *arc,
564                           u32 top, u32 bottom, u32 fileid);
565 
566 /*---------------------------------------------------------------------------*
567   Name:         FS_CloseFile
568 
569   Description:  Closes a file handle.
570 
571   Arguments:    file: An FSFile structure
572 
573   Returns:      TRUE on success.
574  *---------------------------------------------------------------------------*/
575 BOOL    FS_CloseFile(FSFile *file);
576 
577 /*---------------------------------------------------------------------------*
578   Name:         FS_GetFileLength
579 
580   Description:  Gets the file size.
581 
582   Arguments:    file: File handle
583 
584   Returns:      File size
585  *---------------------------------------------------------------------------*/
586 u32     FS_GetFileLength(FSFile *file);
587 
588 /*---------------------------------------------------------------------------*
589   Name:         FS_SetFileLength
590 
591   Description:  Changes the file size.
592 
593   Arguments:    file: File handle
594                 length: The changed size
595 
596   Returns:      Processing result
597  *---------------------------------------------------------------------------*/
598 FSResult FS_SetFileLength(FSFile *file, u32 length);
599 
600 /*---------------------------------------------------------------------------*
601   Name:         FS_GetFilePosition
602 
603   Description:  Gets the current position of a file pointer.
604 
605   Arguments:    file: File handle
606 
607   Returns:      The current position of the file pointer.
608  *---------------------------------------------------------------------------*/
609 u32     FS_GetFilePosition(FSFile *file);
610 
611 /*---------------------------------------------------------------------------*
612   Name:         FS_GetSeekCacheSize
613 
614   Description:  Finds the buffer size required by a full cache for a fast reverse seek.
615 
616   Arguments:    path
617 
618   Returns:      The size on success and 0 on failure.
619  *---------------------------------------------------------------------------*/
620 u32 FS_GetSeekCacheSize( const char *path);
621 
622 /*---------------------------------------------------------------------------*
623   Name:         FS_SetSeekCache
624 
625   Description:  Assigns the cache buffer for a fast reverse seek.
626 
627   Arguments:    file: File handle
628                 buf: Cache buffer
629                 buf_size: Cache buffer size
630 
631   Returns:      TRUE on success.
632  *---------------------------------------------------------------------------*/
633 BOOL FS_SetSeekCache(FSFile *file, void* buf, u32 buf_size);
634 
635 /*---------------------------------------------------------------------------*
636   Name:         FS_SeekFile
637 
638   Description:  Moves a file pointer.
639 
640   Arguments:    file: File handle
641                 offset: The offset to move
642                 origin: The origin to move from
643 
644   Returns:      TRUE on success.
645  *---------------------------------------------------------------------------*/
646 BOOL    FS_SeekFile(FSFile *file, s32 offset, FSSeekFileMode origin);
647 
648 /*---------------------------------------------------------------------------*
649   Name:         FS_SeekFileToBegin
650 
651   Description:  Moves a file pointer to the beginning of the file.
652 
653   Arguments:    file: File handle
654 
655   Returns:      TRUE on success.
656  *---------------------------------------------------------------------------*/
FS_SeekFileToBegin(FSFile * file)657 SDK_INLINE BOOL FS_SeekFileToBegin(FSFile *file)
658 {
659     return FS_SeekFile(file, 0, FS_SEEK_SET);
660 }
661 
662 /*---------------------------------------------------------------------------*
663   Name:         FS_SeekFileToEnd
664 
665   Description:  Moves a file pointer to the end of the file.
666 
667   Arguments:    file: File handle
668 
669   Returns:      TRUE on success.
670  *---------------------------------------------------------------------------*/
FS_SeekFileToEnd(FSFile * file)671 SDK_INLINE BOOL FS_SeekFileToEnd(FSFile *file)
672 {
673     return FS_SeekFile(file, 0, FS_SEEK_END);
674 }
675 
676 /*---------------------------------------------------------------------------*
677   Name:         FS_ReadFile
678 
679   Description:  Reads data from a file.
680 
681   Arguments:    file: File handle
682                 buffer: Buffer to transfer to
683                 Length: Read size
684 
685   Returns:      The size that was actually read on success and -1 on failure.
686  *---------------------------------------------------------------------------*/
687 s32     FS_ReadFile(FSFile *file, void *buffer, s32 length);
688 
689 /*---------------------------------------------------------------------------*
690   Name:         FS_ReadFileAsync
691 
692   Description:  Asynchronously reads data from a file.
693 
694   Arguments:    file: File handle
695                 buffer: Buffer to transfer to
696                 Length: Read size
697 
698   Returns:      The same value as length on success and -1 on failure.
699  *---------------------------------------------------------------------------*/
700 s32     FS_ReadFileAsync(FSFile *file, void *buffer, s32 length);
701 
702 /*---------------------------------------------------------------------------*
703   Name:         FS_WriteFile
704 
705   Description:  Writes data to a file.
706 
707   Arguments:    file: File handle
708                 buffer: Buffer to transfer from
709                 length: Write size
710 
711   Returns:      The size that was actually written on success and -1 on failure.
712  *---------------------------------------------------------------------------*/
713 s32     FS_WriteFile(FSFile *file, const void *buffer, s32 length);
714 
715 /*---------------------------------------------------------------------------*
716   Name:         FS_WriteFileAsync
717 
718   Description:  Asynchronously writes data to a file.
719 
720   Arguments:    file: File handle
721                 buffer: Buffer to transfer from
722                 length: Write size
723 
724   Returns:      The same value as length on success and -1 on failure.
725  *---------------------------------------------------------------------------*/
726 s32     FS_WriteFileAsync(FSFile *file, const void *buffer, s32 length);
727 
728 /*---------------------------------------------------------------------------*
729   Name:         FS_FlushFile
730 
731   Description:  Applies file changes to the device.
732 
733   Arguments:    file: File handle
734 
735   Returns:      Processing result
736  *---------------------------------------------------------------------------*/
737 FSResult FS_FlushFile(FSFile *file);
738 
739 /*---------------------------------------------------------------------------*
740   Name:         FS_OpenDirectory
741 
742   Description:  Opens a directory handle.
743 
744   Arguments:    file: An FSFile structure
745                 path: Path name
746                 mode: Access mode
747 
748   Returns:      TRUE on success.
749  *---------------------------------------------------------------------------*/
750 BOOL    FS_OpenDirectory(FSFile *file, const char *path, u32 mode);
751 
752 /*---------------------------------------------------------------------------*
753   Name:         FS_CloseDirectory
754 
755   Description:  Closes a directory handle.
756 
757   Arguments:    file: An FSFile structure
758 
759   Returns:      TRUE on success.
760  *---------------------------------------------------------------------------*/
761 BOOL    FS_CloseDirectory(FSFile *file);
762 
763 /*---------------------------------------------------------------------------*
764   Name:         FS_ReadDirectory
765 
766   Description:  Reads through only one directory entry.
767 
768   Arguments:    file: An FSFile structure
769                 info: FSDirectoryEntryInfo structure
770 
771   Returns:      TRUE on success.
772  *---------------------------------------------------------------------------*/
773 BOOL    FS_ReadDirectory(FSFile *file, FSDirectoryEntryInfo *info);
774 
775 /*---------------------------------------------------------------------------*
776   Name:         FS_TellDir
777 
778   Description:  Gets the current directory position from a directory handle.
779 
780   Arguments:    dir: Directory handle
781                 pos: Location to store the directory position
782 
783   Returns:      TRUE on success.
784  *---------------------------------------------------------------------------*/
785 BOOL    FS_TellDir(const FSFile *dir, FSDirPos *pos);
786 
787 /*---------------------------------------------------------------------------*
788   Name:         FS_SeekDir
789 
790   Description:  Opens a directory handle with the directory position specified.
791 
792   Arguments:    dir: Directory handle
793                 pos: Directory position
794 
795   Returns:      TRUE on success.
796  *---------------------------------------------------------------------------*/
797 BOOL    FS_SeekDir(FSFile *p_dir, const FSDirPos *p_pos);
798 
799 /*---------------------------------------------------------------------------*
800   Name:         FS_RewindDir
801 
802   Description:  Moves the list position for a directory handle back to the beginning.
803 
804   Arguments:    dir: Directory handle
805 
806   Returns:      TRUE on success.
807  *---------------------------------------------------------------------------*/
808 BOOL    FS_RewindDir(FSFile *dir);
809 
810 
811 /*---------------------------------------------------------------------------*
812  * Unicode Support
813  *---------------------------------------------------------------------------*/
814 
815 /*---------------------------------------------------------------------------*
816   Name:         FS_OpenFileExW
817 
818   Description:  Specifies a path name and opens a file.
819 
820   Arguments:    file: An FSFile structure
821                 path: Path name
822 
823   Returns:      TRUE on success.
824  *---------------------------------------------------------------------------*/
825 BOOL FS_OpenFileExW(FSFile *file, const u16 *path, u32 mode);
826 
827 /*---------------------------------------------------------------------------*
828   Name:         FS_OpenDirectoryW
829 
830   Description:  Opens a directory handle.
831 
832   Arguments:    file: An FSFile structure
833                 path: Path name
834                 mode: Access mode
835 
836   Returns:      TRUE on success.
837  *---------------------------------------------------------------------------*/
838 BOOL FS_OpenDirectoryW(FSFile *file, const u16 *path, u32 mode);
839 
840 /*---------------------------------------------------------------------------*
841   Name:         FS_ReadDirectoryW
842 
843   Description:  Reads through only one directory entry.
844 
845   Arguments:    file: An FSFile structure
846                 info: FSDirectoryEntryInfo structure
847 
848   Returns:      TRUE on success.
849  *---------------------------------------------------------------------------*/
850 BOOL FS_ReadDirectoryW(FSFile *file, FSDirectoryEntryInfoW *info);
851 
852 
853 /*---------------------------------------------------------------------------*
854  * Deprecated Functions
855  *---------------------------------------------------------------------------*/
856 
857 /*---------------------------------------------------------------------------*
858   Name:         FS_OpenFile
859 
860   Description:  Specifies a path name and opens a file.
861 
862   Arguments:    file: An FSFile structure
863                 path: Path name
864 
865   Returns:      TRUE on success.
866  *---------------------------------------------------------------------------*/
867 BOOL    FS_OpenFile(FSFile *file, const char *path);
868 
869 /*---------------------------------------------------------------------------*
870   Name:         FS_GetLength
871 
872   Description:  Gets the file size.
873 
874   Arguments:    file: File handle
875 
876   Returns:      File size
877  *---------------------------------------------------------------------------*/
878 u32     FS_GetLength(FSFile *file);
879 
880 /*---------------------------------------------------------------------------*
881   Name:         FS_GetPosition
882 
883   Description:  Gets the current position of a file pointer.
884 
885   Arguments:    file: File handle
886 
887   Returns:      The current position of the file pointer.
888  *---------------------------------------------------------------------------*/
889 u32     FS_GetPosition(FSFile *file);
890 
891 /*---------------------------------------------------------------------------*
892   Name:         FS_FindDir
893 
894   Description:  Opens a directory handle.
895 
896   Arguments:    dir: FSFile structure
897                 path: Path name
898 
899   Returns:      TRUE on success.
900  *---------------------------------------------------------------------------*/
901 BOOL    FS_FindDir(FSFile *dir, const char *path);
902 
903 /*---------------------------------------------------------------------------*
904   Name:         FS_ReadDir
905 
906   Description:  Reads through only a single instance of directory handle entry information.
907 
908   Arguments:    dir: Directory handle
909                 entry: Location to store the entry information
910 
911   Returns:      TRUE on success.
912  *---------------------------------------------------------------------------*/
913 BOOL    FS_ReadDir(FSFile *dir, FSDirEntry *entry);
914 
915 /*---------------------------------------------------------------------------*
916   Name:         FS_GetFileInfo
917 
918   Description:  Gets information for a file or directory.
919 
920   Arguments:    path: Path name
921                 info: Location to store the information
922 
923   Returns:      Processing result
924  *---------------------------------------------------------------------------*/
925 typedef FSPathInfo  FSFileInfo;
926 FSResult FS_GetFileInfo(const char *path, FSFileInfo *info);
927 
928 
929 #ifdef __cplusplus
930 } /* extern "C" */
931 #endif
932 
933 
934 #endif /* NITRO_FS_FILE_H_ */
935