Copyright (c) 2012-2016 Hyperion Entertainment and contributors.
Disk I/O Library is a higher level API for disk/partition I/O that automatically takes care of most technical details. Details like:
- getting the correct device name, unit and flags to call OpenDevice()
- checking that it's of the correct type and what commands to use
- calculating the disk/partition dimensions based on the DosEnvec structure and TD_GETGEOMETRY (if de_LowCyl is zero).
As an additional safety measures it also checks that all read and write accesses are within partition bounds and immediately fails them if they are not.
Disk I/O Library has functions that allow reading and writing data that is not block aligned or a multiple of the block size and it has a built-in block cache.
The functions themselves should be simple use and are described in the autodoc.
The Setup() function is called to get the disk i/o handle. This takes a device/volume name, which is used to find the device node and from there all the other necessary data, and an optional taglist specifying additional parameters.
After Setup(), Query() should be used to get information on the disk/partition and whether there is a storage medium available at all.
Reading and writing is done through ReadBytes/ReadBlocks(). WriteBytes/WriteBlocks() and the write cache is flushed to disk by using FlushIOCache() (this also calls CMD_UPDATE to flush the device driver's write cache if there is one).
When all is done Cleanup() is called to get rid of the disk I/O handle (this also automatically flushes the write cache if any).
AddDiskChangeHandler()/RemDiskChangeHandler() make it simple to add a disk change handler. As with Setup() all that is needed is a device/volume name and all the low level details are hidden.
Update() is used to make diskio.library start accessing a new storage medium. It's called implicitly the first time during Setup() and among other things takes care of things like getting rid of the old block cache if any and setting up a new one. The currently available file systems do not use this function because they create a new disk I/O handle every time a new disk/medium is inserted.
Example code is available in the NTFS-3G (libntfs-3g/amiga_io.c) and ExFAT (libexfat/amiga_io.c) ports.