216 lines
6.6 KiB
Plaintext
216 lines
6.6 KiB
Plaintext
/***************************************************************************
|
|
|
|
API doc for low level file management. See chunk.txt for chunky file
|
|
management.
|
|
|
|
***************************************************************************/
|
|
|
|
|
|
/****************************************
|
|
Classes and types
|
|
****************************************/
|
|
|
|
|
|
class FIL;
|
|
typedef class FIL *PFIL;
|
|
Low level file class.
|
|
|
|
class FLO;
|
|
File location class. Has fields for a pfil, fp and cb.
|
|
Legal as auto.
|
|
|
|
typedef long FP;
|
|
A file position (index into a file).
|
|
|
|
|
|
/****************************************
|
|
Other hungarian
|
|
****************************************/
|
|
|
|
short bo;
|
|
Indicates byte order.
|
|
|
|
short osk;
|
|
Indicates an operating system. Typically used to determine
|
|
how to translate strings (from one character set to another).
|
|
See TranslateStz and its cousins in utilstr. These have the
|
|
same value in either byte order. Ie, their high and low bytes
|
|
are the same.
|
|
|
|
short el;
|
|
Error level. These, in order of severity, include elNil, kelWrite,
|
|
kelRead, kelSeek, kelCritical.
|
|
|
|
ushort grffil;
|
|
A group of flags indicating file options.
|
|
|
|
|
|
/****************************************
|
|
Constants
|
|
****************************************/
|
|
|
|
short kboCur; // byte order same as current machine
|
|
short kboOther; // byte order opposite from current machine
|
|
|
|
short koskCur; // current machine
|
|
short koskMac; // Mac OS
|
|
short koskWin; // Win OS
|
|
|
|
ushort ffilNil; // default options
|
|
ushort ffilWriteEnable; // open with write permissions
|
|
ushort ffilTemp; // make it a temp file
|
|
ushort ffilMark; // mark the file (see below)
|
|
|
|
|
|
/****************************************
|
|
Concepts
|
|
****************************************/
|
|
|
|
Files have both a mark flag and an open count. If you open a file that
|
|
is already open, the open count of the file is incremented. Calling
|
|
pfil->Close() decrements the open count. A pfil is only freed when
|
|
both the open count is zero and the mark flag is clear. To set the
|
|
mark flag, specify ffilMark when opening or creating the file, or call
|
|
pfil->Mark().
|
|
|
|
To use Quill-style Mark-and-Free, open the file with ffilMark specified
|
|
and call pfil->Close(). At cleanup time, client code should call
|
|
FIL::ClearMarks() to clear all the mark flags, then enumerate files
|
|
still needed and call Mark() on them, then call FIL::CloseUnmarked().
|
|
Files that were marked or have non-zero open count will not be closed
|
|
by FIL::CloseUnmarked().
|
|
|
|
For a file used locally, open the file normally. When you are done with
|
|
it, call close. There is no need to monkey with the marking stuff if
|
|
you just need to do a quick file access.
|
|
|
|
|
|
Files have a delayed error handling mechanism. If you have several
|
|
file accesses to make, you can generally do them all without checking
|
|
for errors. If an error occurs, future file accesses will short circuit.
|
|
At the end of a section of several accesses, you should call ElError() to
|
|
check for an error.
|
|
|
|
|
|
/****************************************
|
|
FIL static methods
|
|
****************************************/
|
|
|
|
PFIL FIL::PfilFirst(void);
|
|
The first pfil (they form a linked list).
|
|
|
|
PFIL FIL::PfilFromFni(FNI *pfni);
|
|
If the file indicated by *pfni is open, this returns a pointer
|
|
to the FIL. Otherwise it returns pNil.
|
|
|
|
PFIL FIL::PfilOpen(FNI *pfni, ushort grffil);
|
|
Opens the indicated file with the indicated options. Read-only is
|
|
the default. To allow writing to a file, use ffilWriteEnable.
|
|
If the file is already open, this ensures that the read/write
|
|
permissions are high enough and increments the open count. This
|
|
call should be balanced with a call to pfil->Close(). Specifying
|
|
ffilMark causes the file to be marked. ffilTemp is illegal.
|
|
|
|
PFIL FIL::PfilCreate(FNI *pfni, ushort grffil);
|
|
Creates and opens the indicated file (asserts that it isn't
|
|
already open) and sets the open count to 1. Assumes
|
|
ffilWriteEnable. ffilMark is legal. Use ffilTemp to create a temp
|
|
file, which will be automatically deleted when it is closed.
|
|
|
|
void FIL::ClearMarks(void);
|
|
Clears the mark flag on all files. See discussion under concepts.
|
|
|
|
void FIL::CloseUnmarked(void);
|
|
Closes all files that are not marked and have zero open count.
|
|
See discussion under concepts.
|
|
|
|
|
|
/****************************************
|
|
FIL methods
|
|
****************************************/
|
|
|
|
PFIL FIL::Next(void);
|
|
Returns the next file (in the linked list).
|
|
|
|
void FIL::Open(void);
|
|
Increment the open count, nothing more.
|
|
|
|
void FIL::Close(void);
|
|
Decrements the open count. If the file is not marked and the
|
|
open count becomes zero, the file is closed.
|
|
|
|
void FIL::Mark(void);
|
|
Sets the mark flag.
|
|
|
|
short FIL::ElError(void);
|
|
Returns the error level of the file. elNil means no error.
|
|
|
|
void FIL::SetTemp(bool f);
|
|
Set or clear the temp flag. Temp files are automatically deleted
|
|
when closed.
|
|
|
|
bool FIL::FTemp(void);
|
|
Returns the temp flag.
|
|
|
|
void FIL::GetFni(FNI *pfni);
|
|
Gets the file name.
|
|
|
|
void FIL::SetFpPos(FP fp);
|
|
Sets the file position.
|
|
|
|
FP FIL::FpPos(void);
|
|
Returns the current file position. If there has been a seek error
|
|
(or higher level error), returns 0.
|
|
|
|
bool FIL::FSetFpMac(FP fp);
|
|
Sets the end of file. Files can not be shrunk using this. This
|
|
asserts that the passed fp is greater than the current end of file.
|
|
|
|
FP FIL::FpMac(void);
|
|
Returns the length of the file. If there has been a seek error
|
|
(or higher level error), returns 0.
|
|
|
|
bool FIL::FReadRgb(void *pv, long cb);
|
|
Reads cb bytes from the current file position. Advances the file
|
|
position. Asserts if you read past the end of file.
|
|
|
|
bool FIL::FWriteRgb(void *pv, long cb);
|
|
Writes cb bytes to the current file position. Advances the file
|
|
position (and eof if its reached).
|
|
|
|
bool FIL::FSwapNames(PFIL pfil);
|
|
Renames the files to swap names. Typically used during a safe save.
|
|
The files should live in the same directory.
|
|
|
|
bool FIL::FRename(FNI *pfni);
|
|
Renames the file. The fni should be in the same directory as the
|
|
file.
|
|
|
|
|
|
/****************************************
|
|
FLO methods
|
|
****************************************/
|
|
|
|
FLO is an auto class: new is illegal; auto, member and global declarations
|
|
are legal.
|
|
|
|
bool FLO::FRead(void *pv);
|
|
Read data from the flo into pv.
|
|
|
|
bool FLO::FWrite(void *pv);
|
|
Write data from pv to the file.
|
|
|
|
bool FLO::FReadRgb(void *pv, long cb, FP dfp);
|
|
Read cb bytes of data from dfp into the flo into pv. Asserts the
|
|
range is totally contained within the flo.
|
|
|
|
bool FLO::FWriteRgb(void *pv, long cb, FP dfp);
|
|
Write cb bytes of data from pv to dfp into the flo. Asserts the
|
|
range is totally contained within the flo.
|
|
|
|
bool FLO::FCopy(FLO *pfloDest);
|
|
Copy data from one flo to the other. Asserts the cb's are
|
|
equal.
|
|
|
|
|