mirror of
https://github.com/gryf/ADFlib.git
synced 2026-02-07 08:45:55 +01:00
271 lines
7.1 KiB
Plaintext
271 lines
7.1 KiB
Plaintext
The ADFlib API quick overview
|
|
*****************************
|
|
|
|
outdated ! But may be useful anyway...
|
|
|
|
|
|
Always read ADFlib structures, never change a value directly, the
|
|
behaviour of the library could then become unforeseeable.
|
|
|
|
|
|
|
|
Minimal C program with ADFlib
|
|
-----------------------------
|
|
|
|
#include<stdio.h> /* for puts() */
|
|
|
|
#include"adflib.h"
|
|
|
|
ENV_DECLARATION;
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
adfEnvInitDefault();
|
|
|
|
puts("hello world");
|
|
|
|
adfEnvCleanUp();
|
|
}
|
|
|
|
|
|
|
|
|
|
Device
|
|
------
|
|
|
|
struct Device {
|
|
int devType; /* see adf_str.h */
|
|
BOOL readOnly;
|
|
long size; /* in bytes */
|
|
|
|
int nVol; /* partitions */
|
|
struct Volume** volList;
|
|
|
|
long cylinders; /* geometry */
|
|
long heads;
|
|
long sectors;
|
|
|
|
BOOL isNativeDev;
|
|
void *nativeDev;
|
|
};
|
|
|
|
struct Device* adfMountDev(char* name)
|
|
mounts and allocates a device (real or dump)
|
|
|
|
void adfDeviceInfo(struct Device* dev)
|
|
prints device info to stdout : must be rewritten for another GUI
|
|
|
|
void adfUnMountDev(struct Device* dev)
|
|
|
|
void adfCreateHd(struct Device* dev, int nbPartitions, struct Partition** part)
|
|
create a filesystem for harddisk with one or several partition
|
|
(see hd_test2.c)
|
|
|
|
void adfCreateFlop(struct Device* dev, char* name, int flags)
|
|
flags are for ffs, dircache or international (see fl_test.c)
|
|
|
|
|
|
Volume
|
|
------
|
|
|
|
struct Volume {
|
|
struct Device* dev;
|
|
|
|
SECTNUM firstBlock; /* first block of data area (from beginning of device) */
|
|
SECTNUM lastBlock; /* last block of data area (from beginning of device) */
|
|
SECTNUM rootBlock; /* root block (from firstBlock) */
|
|
|
|
char dosType; /* FFS/OFS, DIRCACHE, INTERNATIONAL */
|
|
BOOL bootCode;
|
|
int datablockSize; /* 488 or 512 */
|
|
|
|
char *volName;
|
|
|
|
long bitmapSize; /* in blocks */
|
|
SECTNUM *bitmapBlocks; /* bitmap blocks pointers */
|
|
struct bBitmapBlock **bitmapTable;
|
|
BOOL *bitmapBlocksChg;
|
|
|
|
SECTNUM curDirPtr;
|
|
};
|
|
|
|
|
|
struct Volume* adfMount(struct Device* dev, int partition, BOOL readOnly)
|
|
The first partition is #0
|
|
To be called after adfCreateFlop(), adfCreateHd() or adfMountDev().
|
|
|
|
void adfVolumeInfo(vol)
|
|
Display volume info to stdout, must be rewritten for another GUI
|
|
|
|
void adfUnMount(struct Volume *vol)
|
|
|
|
|
|
Dump device (.ADF)
|
|
------------------
|
|
|
|
struct adfCreateDumpDevice(char*, int cyl, int heads, int sectors)
|
|
To be used in place of adfMountDev(). Create a filename of the right size,
|
|
nothing else
|
|
|
|
|
|
File
|
|
----
|
|
|
|
struct File* adfOpenFile(struct Volume *volume, char* filename, char* mode)
|
|
mode = "r" or "w"
|
|
|
|
void adfCloseFile(struct File* file)
|
|
|
|
long adfReadFile(struct File* file, long length, unsigned char* buffer)
|
|
returns the number of bytes read
|
|
|
|
long adfWriteFile(struct File* file, long length, unsigned char* buffer)
|
|
returns the number of bytes written
|
|
|
|
BOOL adfEndOfFile(struct File* file)
|
|
|
|
|
|
Directory
|
|
---------
|
|
|
|
struct List* adfGetDirEnt(struct Volume* vol, SECTNUM nSect)
|
|
Returns a linked list with the directory entries. Each cell content of the list
|
|
must be freed with adfFreeEntry()
|
|
|
|
void adfFreeEntry(struct Entry *entry)
|
|
|
|
SECTNUM adfChangeDir(struct Volume* vol, char* dirname)
|
|
change current directory
|
|
|
|
void adfParentDir(struct Volume* vol)
|
|
change current directory
|
|
|
|
void printEntry(struct Entry* entry)
|
|
print the cell content to stdout
|
|
|
|
void CreateDir(struct Volume* vol, SECTNUM parentSect, char* name)
|
|
|
|
|
|
|
|
Callbacks mechanism
|
|
-------------------
|
|
|
|
* The library environment : 'struct Env adfEnv'
|
|
|
|
This variable is the only global variable of the library. It contains
|
|
callbacks for error and notification messages, and global variables.
|
|
By default, adfEnvInitDefault() initialize adfEnv functions that display
|
|
messages to stderr. You must use adfSetEnv() to use your own defined
|
|
functions.
|
|
The environment must be clean up with adfEnvCleanUp().
|
|
|
|
Four functions are available :
|
|
- (*adfEnv.eFct)(char*), called by ADFlib for a fatal error. It STOPS
|
|
the library : you must redefine yourself a more friendly to handle
|
|
this kind of error.
|
|
- (adfEnv.wFct)(char*), called for warnings. It is called when something wrong
|
|
happens, but processing can continue.
|
|
- (adfEnv.vFct)(char*), called to display verbose messages.
|
|
- (*adfEnv.notifyEnv)(SECTNUM p, int t), called to tell that
|
|
the volume structure has changed. The value p give where the change appeared,
|
|
t the type of the value (ST_DIR,ST_FILE,...).
|
|
|
|
The environment also contains access to nativeFunctions.
|
|
|
|
|
|
* Native device and functions
|
|
|
|
By default, the library is compiled to manage .ADF files (dump files) and
|
|
real devices like harddisk and removable disks (called native devives)
|
|
on ONE defined plateform (WinNT/Intel or Linux/68k...)
|
|
|
|
To add a new plateform to be supported by ADFlib, you must write your
|
|
own files adf_nativ.h and adf_nativ.c.
|
|
|
|
. data types
|
|
|
|
adf_nativ.h defines two structures :
|
|
- 'struct nativeDev'. It contains all the variable necessary for
|
|
the native device management. You can add here whatever you what to
|
|
be able to manage your real device on your plateform !
|
|
- 'struct nativeFunctions'. It defines the minimal API between ADFlib and
|
|
the specific native part. The functions names and prototypes must not be
|
|
changed, since they are called by the library. It is possible to add
|
|
other functions.
|
|
|
|
The type device 'struct Device' contains one variable 'void* nativeDev'.
|
|
It is allocated within adf_nativ.c by adfInitDevice().
|
|
Another variable 'BOOL isNativeDev' tells if the ADFlib is working with
|
|
a dump file (.ADF) or a real device.
|
|
|
|
'adfEnv' contains one variable 'void *nativeFct'. adfEnvInitDefault()
|
|
allocates it by calling the function adfInitNativeFct().
|
|
|
|
|
|
. callback functions :
|
|
|
|
The structure 'struct nativeFunctions' must have at least :
|
|
BOOL (*adfInitDevice)(struct Device*, char*)
|
|
BOOL (*adfNativeReadSector)(struct Device*, long, int, unsigned char*)
|
|
BOOL (*adfNativeWriteSector)(struct Device*, long, int, unsigned char*)
|
|
BOOL (*adfIsDevNative)(char*)
|
|
void (*adfReleaseDevice)()
|
|
|
|
|
|
For example, adfMountDev() calls adfInitDevice() this way :
|
|
struct nativeFunctions *nFct;
|
|
|
|
... /* struct Device* dev allocation */
|
|
|
|
nFct = adfEnv.nativeFct; /* was of type void* */
|
|
|
|
/* only once ! */
|
|
dev->isNativeDev = (*nFct->adfIsDevNative)(filename);
|
|
|
|
/* choose between dump or a real device */
|
|
if (dev->isNativeDev)
|
|
(*nFct->adfInitDevice)(dev, filename);
|
|
else
|
|
adfInitDumpDevice(dev, filename);
|
|
|
|
|
|
You must define one function to initialize a device, for example :
|
|
|
|
BOOL myInitDevice(struct Device *dev, char* name)
|
|
{
|
|
/* allocate and initailize dev->nativeDev */
|
|
|
|
/* return TRUE if everything happens right */
|
|
}
|
|
|
|
or
|
|
|
|
BOOL myIsDevNative(char* name)
|
|
{
|
|
/* for a Unix like platform */
|
|
return( strncmp("/dev/",name,5)==0 );
|
|
}
|
|
|
|
|
|
|
|
And so on to read, write a 512 bytes block, and release the native device.
|
|
|
|
|
|
The function 'adfInitNativeFct()', also defined in adf_nativ.c (and .h),
|
|
makes the names and the ADFlib native API :
|
|
|
|
void adfInitNativeFct()
|
|
{
|
|
struct nativeFunctions *nFct;
|
|
|
|
nFct = (struct nativeFunctions*)adfEnv.nativeFct;
|
|
|
|
nFct->adfInitDevice = myInitDevice ;
|
|
nFct->adfNativeReadSector = myReadSector ;
|
|
...
|
|
}
|
|
|
|
But the prototypes must stay the same !
|
|
|
|
|