# the File API

# Data structures

Warning ! None of the fields of the structure below must be modified directly. In this case, i can not tell how will behave the library. Unless specified, read access is of course allowed.

The dynamic memory allocation/releasing is done by the library (i hope :).

    struct File {
        struct Volume *volume;            // pointer to the volume

        struct bFileHeaderBlock* fileHdr; // the header block
        void *currentData;                // current data block
        struct bFileExtBlock* currentExt; // current data extension block

        long nDataBlock;                  // number of current data blocks
        SECTNUM curDataPtr;               // pointer to the current data block
        unsigned long pos;                // file pos

        int posInDataBlk;                 // index in a datablock
        int posInExtBlk;                  // index in a file header or file extension block
        BOOL eof;                         // TRUE is the last byte has been read, use adfendOfFile()
        BOOL writeMode;                   // if the adfOpenFile() mode is "w"
        };

adfOpenFile()

## Syntax

struct File* adfOpenFile(struct Volume* vol, char* name, char* mode);

## Description

Opens the file with the name name which is located in the current working directory of the vol volume.
The allowed mode are "r" and "w". If the mode is "w", the file mustn't already exists, otherwise an error occurs.

Some basic access permissions are just checked for now.

## Return values

The File structure, ready to be read or wrote.
NULL if an error occurs : file not found with "r", or file already exists with "w".

## Internals

adfFlushFile()

## Syntax

void adfFlushFile(struct File* file);

## Description

Flushes the datablocks on disk.

adfCloseFile()

## Syntax

void adfCloseFile(struct File* file)

## Description

Calls adfFlushFile() and frees the file structure.

adfFileRealSize()

## Syntax

long adfFileRealSize(unsigned long size, int blockSize, long* dataN, long* extN);

## Description

Returns the real size in blocks of a file which the given size. It does not taking into account the new dircache that -may- be allocated.

The blockSize must be 488 or 512. This information is located in the datablockSize of the Volume structure.

If the pointers dataN and extN aren't NULL, the number of data blocks and file extension blocks are returned.

adfReadFile()

## Syntax

long adfReadFile(struct File* file, long n, unsigned char* buffer)

## Description

Read n bytes from the given file into the buffer buffer.

Use adfEndOfFile() to check if the end of the file is reached or not.

## Example

    #include"adflib.h"

    struct File* file;
    FILE* out;
    long n;
    unsigned char buf[600];

    /* a device and a volume 'vol' has been successfully mounted */

    /* opens the Amiga file */
    file = adfOpenFile(vol, "mod.and.distantcall","r");
    if (!file) { /* frees resources and exits */  };

    /* opens the output classic file */
    out = fopen("mod.distant","wb");
    if (!out) { adfCloseFile(file); /* ... */ };

    /* copy the Amiga file into the standard file, 600 bytes per 600 bytes */
    len = 600;
    n = adfReadFile(file, len, buf);
    while(!adfEndOfFile(file)) {
        fwrite(buf, sizeof(unsigned char), n, out);
        n = adfReadFile(file, len, buf);
    }
    /* even if the EOF is reached, some bytes may need to be written */
    if (n>0)
        fwrite(buf, sizeof(unsigned char), n, out);

    /* closes the standard file */
    fclose(out);

    /* closes the Amiga file */
    adfCloseFile(file);

## Returned values

The number of bytes really read.

adfEndOfFile()

## Syntax

BOOL adfEndOfFile(struct File* file)

## Description

TRUE if the end of the file file is reached.

adfWriteFile()

## Syntax

long adfWriteFile(struct File* file, long n, unsigned char* buffer)

## Description

Writes n bytes from the given buffer into the file file.

## Example

    #include"adflib.h"

    struct File* file;
    FILE* in;

    /* a device and a volume 'vol' has been successfully mounted */

    file = adfOpenFile(vol, "moon_gif", "w");
    if (!file) { /* error handling */ };

    in = fopen( argv[2],"rb");
    if (!out) { adfCloseFile(file); /* error handling */ };

    len = 600;
    n = fread(buf,sizeof(unsigned char),len,out);
    while(!feof(out)) {
        adfWriteFile(file, n, buf);
        n = fread(buf,sizeof(unsigned char),len,out);
    }
    if (n>0)
        adfWriteFile(file, n, buf);

    fclose(out);

    adfCloseFile(file);

## Returned values

The number of bytes really wrote.