A special library has been prepared for the management of MFS disks. The library makes it easier to write code for disk control in your programs, helping you realize more efficient and understandable disk management.
The MFS manages files using files and directories in the same way as UNIX and DOS. You can name the files and directories, and manage them using names and numbers.
The MFS library locically treats the ROM area and the RAM area on the disk as different drives. The drive allocation for the ROM area and RAM area is shown below:
ROM area A drive
File names and directories can be specified with their full path, which means the drive name, path name, file name and extension. The drive name and path name are separated by a colon (" :" ), while the directory names are demarcated by a forward slash (" / ") and the file name and its extension are separated by a period (". ")
Example: A:/dir1/picture/mario1.rgb
Most of the time you will be accessing files that are all stored under the same directory, and it would be inconvenient to have to specify the drive name and path name every time. That is why the MFS library allows you to set the current drive and the current directory. When a drive name and path name are not specified, the current drive and current directory are assumed. Relative path names are supported, but you cannot trace backwards using two periods (" .. ").
The first thing you need to do is initialize the whole library. There are two initialization functions: mfsHInitDiskBoot to boot from the disk and mfsHInitCasBoot to boot from the Game Pak.
| Function name: | mfsHInitDiskBoot | |
| Syntax: | s32 mfsHInitDiskBoot(MfsFile handle,u8 handleNum, u8 *company,u8* game,u8 dest) |
|
| Arguments: | handle | Pointer for the file handle structure array |
| handleNum | The number of file handle structures | |
| company | Company code | |
| game | Game code | |
| dest | Game code | |
| Return Value: | Error | |
| Function name: | mfsHInitCasBoot | |
| Syntax: | s32 mfsHInitCasBoot(MfsFile handle,u8 handleNum, u8 *company,u8* game,u8 dest) |
|
| Arguments: | handle | Pointer for the file handle structure array |
| handleNum | The number of file handle structures | |
| company | Company code | |
| game | Game code | |
| dest | Destination code | |
| Return value: | Error | |
The handle argument specifies the pointer to the file handle buffer where the application will prepare the MfsFileHandle structure array when handling files. The MfsFileHandle structure pointer is declared as type MfsFile. The handleNum argument specifies the size of the array. The number of files that the application can open at the same time is determined by the number of file handles specified here. The company and game arguments specify the company code and game code (initial code) issued by Nintendo. The dest argument is the destination code, which is used as disk information when the RAM area is formatted. The following values can be specified for the argument:
| MFS_DESTINATION_JAPAN | 0 | Japan | |
| MFS_DESITNATION_US | 1 | America |
Both of these functions initialize the low-level Leo library first. If the Leo library processes terminate normally, MFS_ERR_NO is returned. If a MFS_ERR_DEVICE error is returned, jump to the appropriate error handling sequence by referencing the global variable mfsError, where the value returned by the Leo*CreateLeoManager function is stored.
2.4.3 Opening Files
To access a file, first you need to open the file and get its file handle with the mfsHFopen function.
| Function name: | mfsHFopen | |
| Syntax: | s32 mfsHFopen(MfsFile* handle, u8* path, u16 mode) | |
| Arguments: | handle | Pointer storing the file handle pointer |
| path | File path name | |
| mode | Open mode | |
| Return value: | Error | |
The file handle is the pointer to the structure that contains the information needed for file read/writes. The file specified by "path" is opened and the file handle is set in "handle". The mode argument specifies the method of file access. Specify either or bitwise OR them to specify both:
| MFS_OPEN_READ | 0x0001 | Open for reading | |
| MFS_OPEN_WRITE | 0x0002 | Open for writing |
For MFS_OPEN_WRITE you can specify any of the following flags. To specify more than one flag, bitwise OR them into the mode argument.
| MFS_OPEN_UPDATE | 0x0000 | Open in overwrite mode | |
| MFS_OPEN_APPEND | 0x0010 | Open in append mode | |
| MFS_OPEN_CREATE | 0x0020 | Create a file if there is no file |
2.4.4 File Read/Writes
Once a file is opened, you can use the obtained file handle to read/write that file. You read from the file using the mfsHFread function, and you write to the file using the mfsHFwrite function.
| Function name: | mfsHFread | |
| Syntax: | s32 mfsHFread(MfsFile handle, void* buf, s32 len) | |
| Arguments: | handle | File handle |
| buf | Pointer to buffer where data is stored | |
| len | Size to read | |
| Return value: | The read size (Error if it is a negative value) | |
| Function name: | mfsHFwrite | |
| Syntax: | s32 mfsHFwrite(MfsFile handle, void* buf, s32 len) | |
| Arguments: | handle | File handle |
| buf | Pointer to buffer where the data to be written is stored | |
| len | Size to write | |
| Return value: | The written size (Error if it is a negative value) | |
2.4.5 Closing Files
After access to the file is finished and there is no need for the file handle anymore, you use the mfsHFclose function to release the file handle.
| Function name: | mfsHFclose | |
| Syntax: | s32 mfsHFclose(MfsFile handle) | |
| Argument: | handle | File handle |
| Return value: | Error | |
The MFS library also has functions for such things as browsing and finding files, deleting files and changing file names. All of the functions explained above are high-level library functions (mfsH*), but with MFS you can also perform lower-level operations, and a group of MFS functions that are not part of the high-level library have been prepared for that purpose.
2.4.6 Errors
A negative number returned as the return value by an MFS library function always indicates an error. Therefore, whenever a negative value is returned from an MFS function, please check the type of error and perform the appropriate error processing.