MaxIO is a powerful feature of BlitzMax that enables developers to work with archives (such as ZIP files) as if they were regular file systems. This is achieved through an underlying mechanism provided by PhysFS. The integration of PhysFS with BlitzMax allows the standard FileSystem functions to seamlessly work with mounted archives.
Writing Directory and Search Path
MaxIO uses a single writing directory and multiple reading directories called the "search path". The writing directory is the root of the writable filesystem, and the search path is a list of directories and archives that MaxIO can read from.
The writing directory is a secure location where your application can store files. By setting the writing directory, you prevent the application from accessing any directories above it, enhancing security. For example, if you were to set the writing directory to "C:\MyGame\MyWritingDirectory" (on Windows), then no MaxIO calls could touch anything above this directory, including the "C:\MyGame" and "C:" directories.
To give MaxIO full access to the system's real file system, you can set the writing directory to the root directory, but this is generally not recommended as it may expose your application to potential security risks.
The search path is a list of directories and archives that MaxIO can read from. When opening a file for reading, MaxIO goes through the search path, checking each location for the requested file. The search path creates a single, hierarchical directory structure that lends itself well to general abstraction with archives and provides better support for various operating systems.
Drive letters are hidden in MaxIO once you set up your initial paths. This means that you should not hardcode a drive letter when specifying file paths. Instead, use platform-independent notation, which ensures compatibility across different operating systems.
For example, if you want to write to "C:\MyGame\MyConfigFiles\game.cfg" (on Windows), you might set the writing directory to "C:\MyGame" and then open the file with the platform-independent notation "MyConfigFiles/game.cfg". This abstraction allows your application to work seamlessly across multiple platforms.
Platform-independent notation is a standardized way of specifying file paths that works across different operating systems. When using MaxIO, you should always specify file paths using platform-independent notation. This notation uses forward slashes ("/") as directory separators and omits drive letters.
Supported Archive Types
MaxIO supports the following archive types:
- .ZIP (pkZip/WinZip/Info-ZIP compatible)
- .7Z (7zip archives)
- .ISO (ISO9660 files, CD-ROM images)
- .GRP (Build Engine groupfile archives)
- .PAK (Quake I/II archive format)
- .HOG (Descent I/II HOG file archives)
- .MVL (Descent II movielib archives)
- .WAD (DOOM engine archives)
- .VDF (Gothic I/II engine archives)
- .SLB (Independence War archives)
Before you can use any MaxIO features, you need to initialise it.
Initialization sets up the necessary internal structures and prepares MaxIO for use.
To initialise MaxIO, call the
MaxIO.Init() function. This function returns an
Int value indicating the success or failure of the initialization process.
Here's an example of how to initialise MaxIO:
If MaxIO.Init() Then ' MaxIO is initialised and ready to use Else Print "Failed to initialise MaxIO" End End If
It's important to check the return value of
MaxIO.Init() to ensure that MaxIO has been
properly initialised. If the initialization fails, you should not attempt to use MaxIO
functions, as they will not behave correctly and may cause unexpected issues.
Once you've finished using the MaxIO module, you should deinitialise it to release any
resources it has acquired. To deinitialise MaxIO, call the
Keep in mind that deinitializing MaxIO while it's still in use can lead to unexpected behaviour. Always make sure that you have finished working with the module before deinitializing it.
Mounting Archives and Directories
Mounting archives and directories in MaxIO refers to the process of attaching an archive (such as a ZIP file) or a directory to the search path. This allows you to access the files and directories within the mounted archive or directory as if they were part of the native file system.
To mount an archive, use the
MaxIO.Mount() function. This function takes two parameters:
the path to the archive file and the mount point within the search path. The mount point
is a virtual directory where the archive will be attached in the search path.
Here's an example of how to mount a ZIP archive:
Local archivePath:String = "path/to/your/archive.zip" Local mountPoint:String = "myArchive" If MaxIO.Mount(archivePath, mountPoint) Then ' Archive is mounted and ready for use Else Print "Failed to mount the archive" End If
Once the archive is mounted, you can access its contents using platform-independent
notation and the standard BlitzMax file functions. For example, if the archive contains
a file named
data.txt, you can access it using the file path
Mounting directories is similar to mounting archives. You can use the
function to attach a directory to the search path, just like you would with an archive.
Here's an example of how to mount a directory:
Local dirPath:String = "path/to/your/directory" Local mountPoint:String = "myDir" If MaxIO.Mount(dirPath, mountPoint) Then ' Directory is mounted and ready for use Else Print "Failed to mount the directory" End If
Once the directory is mounted, you can access its contents using platform-independent notation and the standard BlitzMax file functions.
There are several optional parameters you can pass to the `MaxIO.Mount()`` function to control the behaviour of the mounted archive or directory:
append:Bool = True: By default, the mounted archive or directory is appended to the end of the search path. If you set append to False, the archive or directory will be inserted at the beginning of the search path instead.
createVirtualDir:Bool = False: If set to True, MaxIO will create a virtual directory for the mount point if it doesn't already exist.
Accessing Files Within Archives
After an archive is mounted, you can use the standard BlitzMax file functions to access files within the archive. MaxIO treats the mounted archive as if it were a regular file system, allowing you to read and write files with ease.
Here are some examples of how you can read and write files within a mounted archive using BlitzMax file functions:
Reading a File from an Archive
To read a file from a mounted archive, you can use the ReadFile function, just as you would when working with regular files:
Local file:TStream = ReadFile("path/to/file/in/archive.txt") If file Local content:String = ReadString(file) file.Close() Print "Content of the file: " + content Else Print "Failed to open the file in the archive" End If
Writing a File to an Archive
Writing to files within an archive is generally not supported. Instead, you should extract the file, modify it, and then add it back to the archive if necessary. However, if the archive is mounted to a writable directory, you can write a new file to the directory that will be accessible alongside the archive's contents:
Local file:TStream = WriteFile("path/to/writable/directory/newfile.txt") If file WriteString(file, "This is a new file.") CloseStream(file) Print "New file created successfully" Else Print "Failed to create a new file" End If
Remember that the writing directory should be set up to allow writing to the desired location in the virtual file system created by MaxIO.
Listing Files and Directories
You can use the standard BlitzMax directory listing functions to obtain a list of files and directories within the mounted archive. This allows you to navigate and explore the contents of an archive as if it were a regular directory on your file system.
Here's an example of how to list files and directories within a mounted archive:
Function ListDirContents(dirPath:String) Local dir:Byte Ptr = ReadDir(dirPath) If Not dir Print "Failed to open directory: " + dirPath Return End If Local entry:String = NextFile(dir) While entry Print "Entry: " + entry ' Check if the entry is a directory If FileType(dirPath + "/" + entry) = FILETYPE_DIR Then Print "This is a directory" ' Recursively list the contents of the subdirectory ListDirContents(dirPath + "/" + entry) End If entry = NextFile(dir) Wend CloseDir(dir) End Function ' Call the function with the path to the mounted archive or a directory within the archive ListDirContents("path/to/mounted/archive")
In this example, the
ListDirContents function takes a directory path as a parameter and
lists all files and directories within the specified directory. If it encounters a
subdirectory, it calls itself recursively to list the contents of the subdirectory as well.
Combining Multiple Archives
By mounting multiple archives to the same search path, you can treat them as a single, unified file system. This means that when you access files using MaxIO, the system will automatically search through all mounted archives in the search path to find the requested file. This can be particularly useful for managing game assets, mods, or updates, where you might want to overlay newer files on top of older ones without altering the original archive.
Here's an example of how to mount multiple archives to the same search path:
' Mount the base archive If Not MaxIO.Mount("base_archive.zip", "/") Then Print "Failed to mount base_archive.zip" End End If ' Mount the mod archive If Not MaxIO.Mount("mod_archive.zip", "/") Then Print "Failed to mount mod_archive.zip" End End If ' Mount the update archive If Not MaxIO.Mount("update_archive.zip", "/") Then Print "Failed to mount update_archive.zip" End End If
In this example, three archives (
are mounted to the root of the search path. When accessing files, MaxIO will search through
these archives, effectively combining their contents into a single file system.
If a file exists in more than one archive, the file from the most recently mounted archive will take precedence. This allows you to easily overlay new files on top of older ones, making it easy to manage updates or modifications to your application's assets.
MaxIO is mostly thread-safe, with errors returned by
unique to each thread. However, individual file accesses are not locked, so you cannot
safely read, write, seek, or close the same file from two threads simultaneously.
|MaxIO||IO abstraction implementation.|