1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 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 prepended to the path name. 58 /// 59 /// \param path Pointer to file name to open 60 /// \param info Pointer to file information to use 61 /// 62 /// \retval DEMO_FS_RESULT_OK if it is ok. 63 /// \retval DEMO_FS_RESULT_PERMISSION if it is not permitted to open current file. 64 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 65 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 66 s32 DEMOFSOpenFile(const char* path, DEMOFSFileInfo* info); 67 68 /// \brief Open a file handle with a given mode. 69 /// 70 /// Opens a file for reading/writing/etc. 71 /// 72 /// If the pathname begins with '/', it is used as an absolute path name. 73 /// If it does not, then "/vol/content/" is prepended to the path name. 74 /// 75 /// \note If /vol/content has been remapped to use DVDFS, then you may not 76 /// open files there in "w" (write) mode. Use /vol/save instead. 77 /// 78 /// \param path Pointer to file name to open 79 /// \param info Pointer to file information to use 80 /// \param mode Pointer to file mode to use 81 /// 82 /// \retval DEMO_FS_RESULT_OK if it is ok. 83 /// \retval DEMO_FS_RESULT_PERMISSION if it is not permitted to open current file. 84 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 85 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 86 s32 DEMOFSOpenFileMode(const char* path, DEMOFSFileInfo* info, const char* mode); 87 88 /// \brief Gets the size of the opened file. 89 /// 90 /// Gets the size of a file opened with \ref DEMOFSOpenFile. 91 /// 92 /// This function is actually a macro defined in dvd.h. 93 /// 94 /// \param fileInfo File information of the file 95 /// \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 96 /// 97 /// \retval DEMO_FS_RESULT_OK if it is ok. 98 /// \retval DEMO_FS_RESULT_FATAL_ERROR if a fatal error occurs during a read, the function returns. 99 s32 DEMOFSGetLength(const DEMOFSFileInfo* fileInfo, u32* length); 100 101 /// \brief Synchronously reads from the opened file. 102 /// 103 /// Synchronously reads data from a file opened with \ref DEMOFSOpenFile. 104 /// 105 /// \param fileInfo File information of the file. 106 /// \param addr Buffer address. Must be \c PPC_IO_BUFFER_ALIGN byte aligned. 107 /// \param length Number of bytes to read. Must be a multiple of 32. 108 /// \param offset File position to start reading from. Must be a multiple of 4. 109 /// 110 /// \retval DEMO_FS_RESULT_OK if it is ok. 111 /// \retval DEMO_FS_RESULT_ACCESS if it is no right to access file. 112 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 113 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 114 s32 DEMOFSRead(DEMOFSFileInfo* fileInfo, void* addr, s32 length, s32 offset); 115 116 /// \brief Writes data to a file. 117 /// 118 /// Note: This function may put the current thread to sleep. 119 /// 120 /// \param fileInfo Pointer to a FSFileInfo structure. 121 /// \param addr Buffer address. Must be \c PPC_IO_BUFFER_ALIGN byte aligned. 122 /// \param length Number of bytes to write. 123 /// 124 /// \retval DEMO_FS_RESULT_OK if it is ok. 125 /// \retval DEMO_FS_RESULT_ACCESS if it is no right to access file. 126 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 127 /// \retval DEMO_FS_RESULT_AREA_FULL if all regions given by application are used up. no more empty space. 128 s32 DEMOFSWrite(DEMOFSFileInfo* fileInfo, const void* addr, s32 length); 129 130 /// \brief Closes the file. 131 /// 132 /// Closes the specified file. 133 /// if the FS library is not expecting a call (for example, during transfer) to the DEMOFSCloseFile function, the call to the function takes time. 134 /// Ensure that this situation doesn't occur. 135 /// (Namely, when calling DEMOFSCloseFile, make sure the transfer is complete.) 136 /// 137 /// \param fileInfo File information for the file to close. 138 /// 139 /// \retval DEMO_FS_RESULT_OK if it is ok. 140 /// \retval DEMO_FS_RESULT_CORRUPTION if a file is corrupted. 141 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during a read, the function returns. 142 s32 DEMOFSCloseFile(DEMOFSFileInfo* fileInfo); 143 144 /// \brief Reads a file into an automatically created and allocated buffer. 145 /// 146 /// This buffer is not aligned in any special way. 147 /// File is automatically closed after it's read from. 148 /// Call \ref DEMOFree to free this buffer. 149 /// 150 /// \param filename File string name to read 151 /// \param len Length of file returned here 152 /// 153 void * DEMOFSSimpleRead(const char * filename, u32 * len); 154 155 /// \brief Reads a file into an automatically created and allocated buffer with alignment. 156 /// 157 /// This buffer is aligned with alignSize. 158 /// File is automatically closed after it's read from. 159 /// Call \ref DEMOFree to free this buffer. 160 /// 161 /// \param filename File string name to read 162 /// \param len Length of file returned here 163 /// \param alignSize Alignment size for buffer 164 /// 165 void * DEMOFSSimpleReadAlign(const char * filename, u32 * len, u32 alignSize); 166 167 /// \brief Scans directory for all the files in it. 168 /// 169 /// This returns a list of the names of all the files in a directory. Subdirectories 170 /// are automatically excluded. Filenames, prefixed with pPrefixPath, 171 /// are returned, suitable for passing directly to \ref DEMOFSOpenFile or \ref DEMOFSSimpleRead. 172 /// If the directory pathname begins with '/', it is used as an absolute path name. 173 /// If it does not, then "/vol/content/" is prepended to the path name. 174 /// 175 /// \param pSearchPath Directory to search from 176 /// \param pPrefixPath Directory to prefix filenames with 177 /// \param pFileCount Number of files in the directory 178 /// \param MaxFiles Maximum number of file names to return from this function 179 /// \param ppFileNames Returned array of names of files. The base array must be specified 180 /// by the caller. (e.g char *ppFileNames[MaxFiles]; ) 181 /// Each non null string is allocated using DEMOAlloc() in this routine. 182 /// Call DEMOFree() in caller to free them. 183 /// \return DEMO_FS_RESULT_OK on success, or error value. 184 s32 DEMOFSScanDir(const char *pSearchPath, const char *pPrefixPath, u32 *pFileCount, u32 MaxFiles, char** ppFileNames ); 185 186 /// \brief Scans directory for all the files in it. 187 /// 188 /// This returns a list of the names of all the files in a directory. Subdirectories 189 /// are automatically excluded. Full pathnames, beginning with the given directory pathname, 190 /// are returned, suitable for passing directly to \ref DEMOFSOpenFile or \ref DEMOFSSimpleRead. 191 /// If the directory pathname begins with '/', it is used as an absolute path name. 192 /// If it does not, then "/vol/content/" is prepended to the path name. 193 /// 194 /// \param pPath Directory name 195 /// \param pFileCount Number of files in the directory 196 /// \param MaxFiles Maximum number of file names to return from this function 197 /// \param ppFileNames Returned array of names of files. The base array must be specified 198 /// by the caller. (e.g char *ppFileNames[MaxFiles]; ) 199 /// Each non null string is allocated using DEMOAlloc() in this routine. 200 /// Call DEMOFree() in caller to free them. 201 /// \return DEMO_FS_RESULT_OK on success, or error value. 202 s32 DEMOFSSimpleScanDir(const char *pPath, u32 *pFileCount, u32 MaxFiles, char** ppFileNames ); 203 204 /// \brief Rename a file or directory. 205 /// 206 /// For each pathname, if it begins with '/', it is used as an absolute path name. 207 /// If it does not, then "/vol/content/" is prepended to the path name. 208 /// 209 /// \note If /vol/content has been remapped to use DVDFS, then you may not 210 /// rename anything there. 211 /// 212 /// \param oldpath Pointer to existing name to change 213 /// \param newpath Pointer to new name to use 214 /// 215 /// \retval DEMO_FS_RESULT_OK if it is ok. 216 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during the operation. 217 s32 DEMOFSRename(const char* oldpath, const char *newpath); 218 219 /// \brief Remove a file or directory. 220 /// 221 /// For each pathname, if it begins with '/', it is used as an absolute path name. 222 /// If it does not, then "/vol/content/" is prepended to the path name. 223 /// 224 /// \note If /vol/content has been remapped to use DVDFS, then you may not 225 /// remove anything there. 226 /// 227 /// \param path Pointer to existing name to remove 228 /// \param ignoreError If TRUE, ignore errors from underlying FSA remove call. 229 /// 230 /// \retval DEMO_FS_RESULT_OK if it is ok. 231 /// \retval DEMO_FS_FATAL_ERROR if a fatal error occurs during the operation. 232 s32 DEMOFSRemove(const char* path, BOOL ignoreError); 233 234 /// \brief Determines whether a file exists 235 /// 236 /// This function can be used prior to \ref DEMOFSSimpleRead to error out without 237 /// asserting if the file does not exist. 238 /// 239 /// \param path Pointer to the name of the file 240 /// 241 /// \retval TRUE if the file exists. 242 /// \retval FALSE if the file does not exist. 243 BOOL DEMOFSFileExists(const char* path); 244 245 /// @} 246 247 #ifdef __cplusplus 248 } 249 #endif 250 251 #endif /// __DEMO_FS_H__ 252