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 /* 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 initialize 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 !