1 /*---------------------------------------------------------------------------* 2 3 Copyright 2010-2012 Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 // ----------------------------------------------------------------------------- 13 // demoFs.h 14 // 15 // ----------------------------------------------------------------------------- 16 17 #ifndef __DEMO_FS_H__ 18 #define __DEMO_FS_H__ 19 20 #include <cafe/demo.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /// @addtogroup demoFileSystem 27 /// @{ 28 29 typedef s32 DEMOFSFileInfo; 30 typedef s32 DEMOFSDir; 31 typedef s32 DEMOFSDirEntry; 32 33 // At the moment, only 3 of these result values are ever returned: 34 // (This may change in the future.) 35 36 typedef enum 37 { 38 DEMO_FS_RESULT_OK = 0, // YES! 39 DEMO_FS_RESULT_ACCESS = -1, // no 40 DEMO_FS_RESULT_PERMISSION = -2, // no 41 DEMO_FS_RESULT_CORRUPTION = -3, // no 42 DEMO_FS_RESULT_AREA_FULL = -4, // no 43 DEMO_FS_RESULT_MAX_HANDLES = -5, // no 44 DEMO_FS_RESULT_ALREADY_EXISTS = -6, // no 45 DEMO_FS_RESULT_NOT_FOUND = -7, // YES! 46 DEMO_FS_RESULT_NOT_EMPTY = -8, // no 47 DEMO_FS_RESULT_FILE_OPEN = -9, // no 48 DEMO_FS_RESULT_FATAL_ERROR = -128 // YES! 49 } DEMOFSResultCode; 50 51 52 /// \brief Open a file handle for reading. 53 /// 54 /// Opens a file for reading. 55 /// 56 /// If the pathname begins with '/', it is used as an absolute path name. 57 /// If it does not, then "/vol/content/" is pre-prended to the path name. 58 /// The demoFSOpenFile function returns one of error codes. 59 /// 60 /// \param path Pointer to file name to open 61 /// \param info Pointer to file information to use 62 /// 63 /// \retval DEMO_FS_RESULT_OK if it is ok. 64 /// \retval DEMO_FS_RESULT_PERMISSION if it is not permitted to open current file. 65 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 66 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 67 s32 DEMOFSOpenFile(const char* path, DEMOFSFileInfo* info); 68 69 /// \brief Open a file handle with a given mode. 70 /// 71 /// Opens a file for reading/writing/etc. 72 /// 73 /// If the pathname begins with '/', it is used as an absolute path name. 74 /// If it does not, then "/vol/content/" is pre-prended to the path name. 75 /// The DEMOFSOpenFileMode function returns one of error codes. 76 /// 77 /// \note If /vol/content has been remapped to use DVDFS, then you may not 78 /// open files there in "w" (write) mode. Use /vol/save instead. 79 /// 80 /// \param path Pointer to file name to open 81 /// \param info Pointer to file information to use 82 /// \param mode Pointer to file mode to use 83 /// 84 /// \retval DEMO_FS_RESULT_OK if it is ok. 85 /// \retval DEMO_FS_RESULT_PERMISSION if it is not permitted to open current file. 86 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 87 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 88 s32 DEMOFSOpenFileMode(const char* path, DEMOFSFileInfo* info, const char* mode); 89 90 /// \brief Gets the size of the opened file. 91 /// 92 /// Gets in advance the size of a file opened with the demoFSGetLength function. 93 /// 94 /// This function is actually a macro defined in dvd.h. 95 /// 96 /// \param fileInfo File information of the file 97 /// \param length The file size. As a return value, this size may not always be a multiple of 32. For this reason, when preparing buffers for reading files, this value must be rounded up to a multiple of 32 98 /// 99 /// \retval DEMO_FS_RESULT_OK if it is successed. 100 /// \retval DEMO_FS_RESULT_FATAL_ERROR if a fatal error occurs during a read, the function returns. 101 s32 DEMOFSGetLength(const DEMOFSFileInfo* fileInfo, u32* length); 102 103 /// \brief Synchronously reads from the opened file. 104 /// 105 /// Synchronously reads data from a file. First opens the file with the DEMOOpenFile function. 106 /// 107 /// \param fileInfo File information of the file. 108 /// \param addr Buffer address. Must be \c PPC_IO_BUFFER_ALIGN byte aligned. 109 /// \param length Number of bytes to read. Must be a multiple of 32. 110 /// \param offset File position to start reading from. Must be a multiple of 4. 111 /// 112 /// \retval DEMO_FS_RESULT_OK if it is ok. 113 /// \retval DEMO_FS_RESULT_ACCESS if it is no right to access file. 114 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 115 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 116 s32 DEMOFSRead(DEMOFSFileInfo* fileInfo, void* addr, s32 length, s32 offset); 117 118 /// \brief Writes data to a file. 119 /// 120 /// This function may put the current thread to sleep. 121 /// 122 /// \param fileInfo Pointer to a FSFileInfo structure. 123 /// \param addr Buffer address. Must be \c PPC_IO_BUFFER_ALIGN byte aligned. 124 /// \param length Number of bytes to write. 125 /// 126 /// \retval DEMO_FS_RESULT_OK if it is ok. 127 /// \retval DEMO_FS_RESULT_ACCESS if it is no right to access file. 128 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 129 /// \retval DEMO_FS_RESULT_AREA_FULL if all regions given by application are used up. no more empty space. 130 s32 DEMOFSWrite(DEMOFSFileInfo* fileInfo, const void* addr, s32 length); 131 132 /// \brief Closes the file. 133 /// 134 /// Closes the specified file. 135 /// if the FS library is not expecting a call (for example, during transfer) to the demoFSCloseFile function, the call to the function takes time. 136 /// Ensure that this situation doesn't occur. 137 /// (Namely, when calling demoFSCloseFile, make sure the transfer is complete.) 138 /// 139 /// \param fileInfo File information for the file to close. 140 /// 141 /// \retval DEMO_FS_RESULT_OK if it is ok. 142 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 143 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 144 s32 DEMOFSCloseFile(DEMOFSFileInfo* fileInfo); 145 146 /// \brief Reads a file into an automatically created and allocated buffer. 147 /// 148 /// This buffer is not aligned in any special way. 149 /// File is automatically closed after it's read from. 150 /// Call \ref DEMOFree() to free this buffer. 151 /// 152 /// \param filename File string name to read 153 /// \param len Length of file returned here 154 /// 155 void * DEMOFSSimpleRead(const char * filename, u32 * len); 156 157 /// \brief Reads a file into an automatically created and allocated buffer with alignment. 158 /// 159 /// This buffer is aligned with alignSize. 160 /// File is automatically closed after it's read from. 161 /// Call \ref DEMOFree() to free this buffer. 162 /// 163 /// \param filename File string name to read 164 /// \param len Length of file returned here 165 /// \param alignSize Alignment size for buffer 166 /// 167 void * DEMOFSSimpleReadAlign(const char * filename, u32 * len, u32 alignSize); 168 169 /// \brief Scans directory for all the files in it. 170 /// 171 /// This returns a list of the names of all the files in a directory. Subdirectories 172 /// are automatically excluded. Filenames, prefixed with pPrefixPath, 173 /// are returned, suitable for passing directly to DEMOFSOpenFile() or DEMOFSSimpleRead(). 174 /// If the directory pathname begins with '/', it is used as an absolute path name. 175 /// If it does not, then "/vol/content/" is pre-prended to the path name. 176 /// 177 /// \param pSearchPath Directory to search from 178 /// \param pPrefixPath Directory to prefix filenames with 179 /// \param pFileCount Number of files in the directory 180 /// \param MaxFiles Maximum number of file names to return from this function 181 /// \param ppFileNames Returned array of names of files. The base array must be specified 182 /// by the caller. (e.g char *ppFileNames[MaxFiles]; ) 183 /// Each non null string is allocated using DEMOAlloc() in this routine. 184 /// Call DEMOFree() in caller to free them. 185 /// \return DEMO_FS_RESULT_OK on success, or error value. 186 s32 DEMOFSScanDir(const char *pSearchPath, const char *pPrefixPath, u32 *pFileCount, u32 MaxFiles, char** ppFileNames ); 187 188 /// \brief Scans directory for all the files in it. 189 /// 190 /// This returns a list of the names of all the files in a directory. Subdirectories 191 /// are automatically excluded. Full pathnames, beginning with the given directory pathname, 192 /// are returned, suitable for passing directly to DEMOFSOpenFile() or DEMOFSSimpleRead(). 193 /// If the directory pathname begins with '/', it is used as an absolute path name. 194 /// If it does not, then "/vol/content/" is pre-prended to the path name. 195 /// 196 /// \param pPath Directory name 197 /// \param pFileCount Number of files in the directory 198 /// \param MaxFiles Maximum number of file names to return from this function 199 /// \param ppFileNames Returned array of names of files. The base array must be specified 200 /// by the caller. (e.g char *ppFileNames[MaxFiles]; ) 201 /// Each non null string is allocated using DEMOAlloc() in this routine. 202 /// Call DEMOFree() in caller to free them. 203 /// \return DEMO_FS_RESULT_OK on success, or error value. 204 s32 DEMOFSSimpleScanDir(const char *pPath, u32 *pFileCount, u32 MaxFiles, char** ppFileNames ); 205 206 /// \brief Rename a file or directory. 207 /// 208 /// For each pathname, if it begins with '/', it is used as an absolute path name. 209 /// If it does not, then "/vol/content/" is pre-prended to the path name. 210 /// 211 /// \note If /vol/content has been remapped to use DVDFS, then you may not 212 /// rename anything there. 213 /// 214 /// \param oldpath Pointer to existing name to change 215 /// \param newpath Pointer to new name to use 216 /// 217 /// \retval DEMO_FS_RESULT_OK if it is ok. 218 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during the operation. 219 s32 DEMOFSRename(const char* oldpath, const char *newpath); 220 221 /// \brief Remove a file or directory. 222 /// 223 /// For each pathname, if it begins with '/', it is used as an absolute path name. 224 /// If it does not, then "/vol/content/" is pre-prended to the path name. 225 /// 226 /// \note If /vol/content has been remapped to use DVDFS, then you may not 227 /// remove anything there. 228 /// 229 /// \param path Pointer to existing name to remove 230 /// \param ignoreError If TRUE, ignore errors from underlying FSA remove call. 231 /// 232 /// \retval DEMO_FS_RESULT_OK if it is ok. 233 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during the operation. 234 s32 DEMOFSRemove(const char* path, BOOL ignoreError); 235 236 /// @} 237 238 #ifdef __cplusplus 239 } 240 #endif 241 242 #endif /// __DEMO_FS_H__ 243