# the Volume API

# Use cases

See Device API use cases.

# Data structures

    struct Volume{
        struct Device *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 Volume* adfMount(struct Device *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 Volume *vol)

## Description

Release a Volume. Free the bitmap structures.

adfCountFreeBlocks()

## Syntax

long adfCountFreeBlocks(struct Volume *vol)

## Description

Counts the free blocks of a Volume.

## Return values

The number of free blocks.

adfInstallBootBlock()

## Syntax

RETCODE adfInstallBootBlock(struct Volume* 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 Device* 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.