# the Volume API

# Use cases

See Device API use cases.

# Data structures

    struct AdfVolume{
        struct AdfDevice *     dev;              /* the pointer of the Device structure of which the volume belongs to */

        /* physical sector numbers */
        SECTNUM                firstBlock;       /* first block of the data area (from the beginning of the media) */
        SECTNUM                lastBlock;        /* last usable block (from the beginning of the media) */

        /* logical sector number */
        SECTNUM                rootBlock;        /* root block (from firstBlock) */

        char                   dosType;          /* FFS/OFS, DIRCACHE, INTERNATIONAL */
        BOOL                   bootCode;         /* TRUE if a floppy is bootable */
        int                    dataBlockSize;    /* 488 or 512 */

        char *                 volName;

        /* bitmap */
        long                   bitmapSize;       /* number of blocks used to store the bitmap
                                                    (excluding the bitmapExtension blocks)         */
        SECTNUM *              bitmapBlocks;     /* bitmap blocks pointers (excluding bitmap extensions blocks) */
        struct bBitmapBlock ** bitmapTable;      /* stores the bitmap blocks */
        BOOL *                 bitmapBlocksChg;  /* bitmapBlocksChg[i] is TRUE if bitmapTable[i} has changed,
                                                    and need to be written at bitmapBlocks[i]                  */

        SECTNUM curDirPtr;                       /* number of the current working directory */
    }

If vol is one Volume structure returned by adfMount() :

- The devType is vol->dev->devType.
- The dosType is OFS or FFS (exclusive), and may have the DIRCACHE and INTERNATIONAL modes enabled. Uses isFFS(vol->dosType), isOFS(), isINTL() and isDIRCACHE() to determine it.
  Warning ! Even if isINTL() returns FALSE, if isDIRCACHE() is TRUE, the Volume is considered (like with AmigaDOS) as having the international mode enabled !

adfMount()

## Syntax

struct AdfVolume* adfMount(struct AdfDevice *dev, int nPart, BOOL readOnly)

## Description

Mounts a designed volume (nPart) of the Device (dev), eventually with read only access (readOnly). The first partition is #0.

The current working directory is the root block.

## Return values

The Volume, NULL in case of error.

## Internals

1. Read the bootblock to determine vol->dosType and vol->datablockSize.
2. Read the rootblock, fills vol->curDirPtr
3. Read and allocate the bitmap : vol->bitmapBlocks[], vol->bitmapTable[], vol->bitmapSize, vol->bitmapBlocksChg[].

adfUnMount()

## Syntax

void adfUnMount(struct AdfVolume *vol)

## Description

Release a Volume. Free the bitmap structures.

adfCountFreeBlocks()

## Syntax

long adfCountFreeBlocks(struct AdfVolume *vol)

## Description

Counts the free blocks of a Volume.

## Return values

The number of free blocks.

adfInstallBootBlock()

## Syntax

RETCODE adfInstallBootBlock(struct AdfVolume* vol, unsigned char* code)

## Description

Install a bootblock on a floppy disk. Won't work on any other device.

You must provide the 1024 bytes large bootblock.
Doesn't modify the initial 'DOS' header and dosType. Recalculates the checksum.

## Return values

RC_OK, something different in case of error.

adfCreateHdFile()

## Syntax

RETCODE adfCreateHdFile(struct AdfDevice* dev, char* volName, int volType)

## Description

Create an hardfile on a dump file. The size of this file must be larger than 1802240 bytes, the size of an high density floppy dump.

Use adfCreateDumpDevice() the create the device passed to adfCreateHdFile().

## Return values

RC_OK, something different in case of error.

## Internals

The device is created with one volume, and dev->devType if filled with DEVTYPE_HARDFILE.