Binary compatibility information. void * opaque
Instance data for this struct. PHYSFS_sint64(* read )(struct PHYSFS_Io *io, void *buf, PHYSFS_uint64 len)
Read more data. PHYSFS_sint64(* write )(struct PHYSFS_Io *io, const void *buffer, PHYSFS_uint64 len)
Write more data. int(* seek )(struct PHYSFS_Io *io, PHYSFS_uint64 offset)
Move i/o position to a given byte offset from start. PHYSFS_sint64(* tell )(struct PHYSFS_Io *io)
Report current i/o position. PHYSFS_sint64(* length )(struct PHYSFS_Io *io)
Determine size of the i/o instance's dataset. struct PHYSFS_Io *(* duplicate )(struct PHYSFS_Io *io)
Duplicate this i/o instance. int(* flush )(struct PHYSFS_Io *io)
Flush resources to media, or wherever. void(* destroy )(struct PHYSFS_Io *io)
Cleanup and deallocate i/o instance.
Historically, PhysicsFS provided access to the physical filesystem and archives within that filesystem. However, sometimes you need more power than this. Perhaps you need to provide an archive that is entirely contained in RAM, or you need to bridge some other file i/o API to PhysicsFS, or you need to translate the bits (perhaps you have a a standard .zip file that's encrypted, and you need to decrypt on the fly for the unsuspecting zip archiver).
A PHYSFS_Io is the interface that Archivers use to get archive data. Historically, this has mapped to file i/o to the physical filesystem, but as of PhysicsFS 2.1, applications can provide their own i/o implementations at runtime.
This interface isn't necessarily a good universal fit for i/o. There are a few requirements of note:
- They only do blocking i/o (at least, for now).
- They need to be able to duplicate. If you have a file handle from fopen(), you need to be able to create a unique clone of it (so we have two handles to the same file that can both seek/read/etc without stepping on each other).
- They need to know the size of their entire data set.
- They need to be able to seek and rewind on demand.
...in short, you're probably not going to write an HTTP implementation.
Thread safety: PHYSFS_Io implementations are not guaranteed to be thread safe in themselves. Under the hood where PhysicsFS uses them, the library provides its own locks. If you plan to use them directly from separate threads, you should either use mutexes to protect them, or don't use the same PHYSFS_Io from two threads at the same time.
This function must always succeed: as such, it returns void. The system may call your flush() method before this. You may report failure there if necessary. This method may still be called if flush() fails, in which case you'll have to abandon unflushed data and other failing conditions and clean up.
Once this method is called for a given instance, the system will assume it is unsafe to touch that instance again and will discard any references to it.
If you can't duplicate a handle, it's legal to return NULL, but you almost certainly need this functionality if you want to use this to PHYSFS_Io to back an archive.
This function may be called before destroy(), as it can report failure and destroy() can not. It may be called at other times, too.
You don't have to implement this; set it to NULL if not implemented. This will only be used if the file is opened for reading. If set to NULL, a default implementation that immediately reports failure will be used.
buf The buffer to store data into. It must be at least (len) bytes long and can't be NULL.
len The number of bytes to read from the interface.
offset The new byte offset for the i/o position.
You don't have to implement this; set it to NULL if not implemented. This will only be used if the file is opened for writing. If set to NULL, a default implementation that immediately reports failure will be used.
You are allowed to buffer; a write can succeed here and then later fail when flushing. Note that PHYSFS_setBuffer() may be operating a level above your i/o, so you should usually not implement your own buffering routines.
buffer The buffer to read data from. It must be at least (len) bytes long and can't be NULL.
len The number of bytes to read from (buffer).
|Fri May 22 2020||Version 3.0.2|