Liren Large Software Subsidy 7/07.iso/c/c085/2.ddi/BCFILE.DOC

Text File | 1991-04-25 | 15.6 KB | 469 lines

Win++ Version 2.00                                                  BCFILE.DOC


                         BCFile Class Documentation

                                Version 2.00
                               April 25, 1991


                           POSITION IN HIERARCHY

BCObject
  BCDataObject
  BCDevice
  BCDispObject
  BCFile           <--
  BCGraphicObject
  BCList

                                  SUMMARY

BCFile is an alternative to C++ streams and I/O streams.  Its member functions
provide file input and output services for a variety of fundamental data types
in a type-safe manner.


                                DECLARATION

BCFile is declared in the FILE.H header file.

   class BCFile : public BCObject
   {
       FILE *spFile;
       CHAR caFileName[120];
       WORD wMode;
       BCModule *opModule;
   public:
       BCFile(CHAR     *cpFileName,
              WORD      wOpenMode = 0,
              BCModule *opMod     = (BCModule *)BCGetApp());
       BCFile(CHAR     *cpFileName,
              CHAR     *cpFileExt,
              BOOL      blFrcExt  = FALSE,
              WORD      wOpenMode = 0,
              BCModule *opMod     = (BCModule *)BCGetApp());
       BCFile(FILE     *spFilePtr,
              CHAR     *cpFileName = NULL,
              WORD      wOpenMode  = 0,
              BCModule *opMod      = (BCModule *)BCGetApp());
      ~BCFile(VOID);
       BOOL      Open(WORD wOpenMode);
       BOOL      Close(VOID);
       WORD      Read(VOID *pBuf,WORD wCnt);
       WORD      Write(VOID *pBuf,WORD wCnt);
       LONG      GetPos(VOID);
       LONG      SetPos(LONG lPos,WORD wMode);
       LONG      GetLen(VOID);
       BOOL      Flush(VOID);
       BOOL      Delete(VOID);
       INT       GetChr(VOID);
       BOOL      GetBlk(VOID *pBlk,WORD wLen);
       BOOL      GetStr(CHAR *cpBuf,WORD wMaxLen);
       BOOL      PutBlk(VOID *pBlk,WORD wLen);
       BOOL      PutChrs(INT iChr,WORD wCnt);
       BOOL      PutChr(INT iChr);
       BOOL      PutStr(CHAR *cpStr);
       BOOL      FrmtPutStr(CHAR *cpFrmt,...);
       BOOL      LoadByte(BYTE  bByte);
       BOOL      LoadBool(BOOL  blBool);
       BOOL      LoadInt(INT  iInt);
       BOOL      LoadWord(WORD  wWord);
       BOOL      LoadCoord(COORD  coCoord);
       BOOL      LoadLong(LONG  lLong);
       BOOL      LoadDblWord(DWORD  dwDblWord);
       BOOL      LoadFloat(FLOAT  fFloat);
       BOOL      LoadDouble(DOUBLE  dDouble);
       BOOL      LoadPtr(VOID * pPtr);
       BOOL      LoadString(CHAR *cpString);
       BOOL      LoadStringPtr(CHAR * cpString);
       LONG      LoadLength(VOID);
       BOOL      LoadFarBlk(VOID HUGE *lpBlk,LONG lSize);
       BOOL      SaveByte(BYTE bByte);
       BOOL      SaveBool(BOOL blBool);
       BOOL      SaveInt(INT iInt);
       BOOL      SaveWord(WORD wWord);
       BOOL      SaveCoord(COORD coCoord);
       BOOL      SaveLong(LONG lLong);
       BOOL      SaveDblWord(DWORD dwDblWord);
       BOOL      SaveFloat(FLOAT fFloat);
       BOOL      SaveDouble(DOUBLE dDouble);
       BOOL      SavePtr(VOID *pPtr);
       BOOL      SaveString(CHAR *cpString);
       BOOL      SaveStringPtr(CHAR *cpString);
       BOOL      SaveLength(DWORD dwLen);
       BOOL      SaveFarBlk(VOID HUGE *lpBlk,LONG lSize);
       FILE     *GetPtr(VOID);
       CHAR     *GetName(VOID);
       CHAR     *GetErrLocStr(LONG lOfs);
       CHAR     *GetErrLocStr(VOID);
       BOOL      IsOpen(VOID);
       BCModule *GetModule(VOID) { return(opModule); }
       VOID      SetModule(BCModule *opMod) { opModule = opMod; }
   };



                                 CONSTANTS

        /* file open modes (from cdecls.h) */

#define BC_READ_OPEN       0x0001  /* open file for reading */
#define BC_WRITE_OPEN      0x0002  /* open file for writing */
#define BC_APPEND_FILE     0x0004  /* append file attribute */
#define BC_TRUNC_FILE      0x0008  /* truncate file attribute */
#define BC_BINARY_FILE     0x0010  /* binary file attribute */


        /* SetPos mode codes (from cdecls.h) */

#define BC_REL_BOF    0       /* relative to beginning of file */
#define BC_REL_CRNT   1       /* relative to current position */
#define BC_REL_EOF    2       /* relative to end of file */



                                CONSTRUCTORS

BCFile(CHAR     *cpFileName,
       WORD      wOpenMode = 0,
       BCModule *opMod     = (BCModule *)BCGetApp());

   This constructor accepts a complete filename and  optionally  accepts  open
   mode flags.  These flags are defined in CDECLS.H.  If wOpenMode is nonzero,
   then the file is opened by the constructor.

BCFile(CHAR     *cpFileName,
       CHAR     *cpFileExt,
       BOOL      blFrcExt  = FALSE,
       WORD      wOpenMode = 0,
       BCModule *opMod     = (BCModule *)BCGetApp());

   This  constructor  accepts  a  default  filename extension.  If blFrcExt is
   FALSE and if the given filename  does  not  have  an  extension,  then  the
   cpFileExt extension is appended to the name.  If blFrcExt is TRUE, then the
   cpFileExt   extension   replaces  any  existing  filename  extension.   The
   wOpenMode flags are defined in CDECLS.H.  If wOpenMode is nonzero, then the
   file is opened by the constructor.

BCFile(FILE     *spFilePtr,
       CHAR     *cpFileName = NULL,
       WORD      wOpenMode  = 0,
       BCModule *opMod      = (BCModule *)BCGetApp());

   This constructor creates a BCFile object from a pointer to an existing FILE
   structure, which must pertain to an existing, open file.


                                 DESTRUCTOR

~BCFile(VOID);

This is the destructor.  It closes the file if it is open.


                              MEMBER FUNCTIONS

BOOL Close(VOID);

   "Close" closes the file, which (of course) must already have  been  opened.
   It returns TRUE if successful.

BOOL Delete(VOID);

   "Delete"  deletes  the  file, which should not be open.  It returns TRUE if
   successful.

BOOL Flush(VOID);

   "Flush" flushes the file buffers.  It returns TRUE if successful.

BOOL FrmtPutStr(CHAR *cpFrmt,...);

   "FrmtPutStr" uses vfprintf() to format and write a string to the file.   It
   returns TRUE if successful.

BOOL GetBlk(VOID *pBlk,WORD wLen);

   "GetBlk"  reads  a  block  of bytes from the file.  It returns TRUE if wLen
   bytes were successfully read.

INT GetChr(VOID);

   "GetChr" reads and return the next character from the file.  It returns  -1
   if EOF or an error is encountered.

CHAR *GetErrLocStr(LONG lOfs);

   "GetErrLocStr"  (this  version)  returns  a  pointer to a string "at offset
   (ofs) in file (name)" using lOfs and the current filename.

CHAR *GetErrLocStr(VOID);

   "GetErrLocStr" (this version) returns a pointer  to  a  string  "at  offset
   (ofs)  in  file  (name)"  using  the  current file position and the current
   filename.

LONG GetLen(VOID);

   "GetLen" returns the length of the file, or -1L if error.

BCModule *GetModule(VOID);

   "GetModule" returns the BCModule object indicating the module that owns the
   file.

CHAR *GetName(VOID);

   "GetName" returns a pointer to the filename.

LONG GetPos(VOID);

   "GetPos" returns a number representing the current position  in  the  file.
   It returns -1L upon error.

FILE *GetPtr(VOID);

   "GetPtr"  returns  the  FILE  pointer for the file.  It returns NULL if the
   file is not open.

BOOL GetStr(CHAR *cpBuf,WORD wMaxLen);

   "GetStr" reads characters from the file up to and including the  next  line
   separator.

BOOL IsOpen(VOID);

   "IsOpen" returns TRUE if the file is open.

BOOL Load(BCFile *opFile);

   "Load"  loads  this  BCFile object's data member values from a file that is
   specified by another BCFile object.  The file specified via opFile must  be
   open  for  reading  in  binary  mode, and its file position must point to a
   location  previously  stored  with  BCFile::Save.   It  returns   TRUE   if
   successful.

BOOL LoadBool(BOOL  blBool);

   "LoadBool"  reads  a BOOL from the file and assigns the value to the blBool
   reference.  It returns TRUE if successful.

BOOL LoadByte(BYTE  bByte);

   "LoadByte" reads a byte from the file and assigns the  byte  value  to  the
   bByte reference.  It returns TRUE if successful.

BOOL LoadCoord(COORD  coCoord);

   "LoadCoord"  reads  a  COORD  from  the  file  and assigns the value to the
   coCOORD reference.  It returns TRUE if successful.

BOOL LoadDblWord(DWORD  dwDblWord);

   "LoadDblWord" reads a double word (4 bytes) from the file and assigns it to
   the dwDblWord reference.  It returns TRUE if successful.

BOOL LoadDouble(DOUBLE  dDouble);

   "LoadDouble" reads a DOUBLE from the file and assigns  it  to  the  dDouble
   reference.  It returns TRUE if successful.

BOOL LoadFarBlk(VOID HUGE *lpBlk,LONG lSize);

   "LoadFarBlk" reads data from a file into a far or huge block of memory.  It
   returns TRUE if lSize bytes were successfully read into lpBlk.

BOOL LoadFloat(FLOAT  fFloat);

   "LoadFloat"  reads  a  FLOAT  from  a  file  and  assigns  it to the fFloat
   reference.  It returns TRUE if successful.

BOOL LoadInt(INT  iInt);

   "LoadInt" reads an INT from a file and assigns it to  the  iInt  reference.
   It returns TRUE if successful.

LONG LoadLength(VOID);

   "LoadLength"  reads  a  variable-length length field previously stored with
   SaveLength.  See SaveLength below for the format.  It  returns  the  length
   value or -1L if an error occurred.

BOOL LoadLong(LONG  lLong);

   "LoadLong"  reads a LONG from a file and assigns it to the lLong reference.
   It returns TRUE if successful.

BOOL LoadPtr(VOID * pPtr);

   "LoadPtr" reads a VOID pointer from a file  and  assigns  it  to  the  pPtr
   reference.   The  pointer  must  have  been  saved  from a program having a
   corresponding memory model.  The actual value of the pointer is useless  in
   any  program  instance  other  than  the  instance  that saved the pointer,
   although it may be useful to  know  whether  the  pointer  is  0.   LoadPtr
   returns TRUE if successful.

BOOL LoadString(CHAR *cpString);

   "LoadString"  reads  a  string  from  the  file, copying it into the buffer
   pointed to by cpString.  The string is stored in the  file  as  a  variable
   length  length field (see SaveLength) followed by the string bytes (without
   the null terminator).  The cpString argument must be big enough to hold the
   string.  Otherwise, use Loadlength to check the length first, and then  use
   GetBlk,   Read,   or   SetPos  accordingly.   LoadString  returns  TRUE  if
   successful.

BOOL LoadStringPtr(CHAR * cpString);

   "LoadStringPtr" allocates memory for and reads a string from  the  file  in
   the  same  manner as LoadString.  LoadStringPtr sets the cpString reference
   to point to the allocated memory.  It returns TRUE if successful, or  FALSE
   if an error occurs while allocating the memory or reading the file.

BOOL LoadWord(WORD  wWord);

   "LoadWord" reads a word (2 bytes) from the file and assigns it to the wWord
   reference.  It returns TRUE if successful.

BOOL Open(WORD wOpenMode);

   "Open"  opens  the  file  with  the  given mode flags, which are defined in
   CDECLS.H.  The file must not already be open in this object.  Open  returns
   TRUE if the file was successfully opened.

BOOL PutBlk(VOID *pBlk,WORD wLen);

   "PutBlk"  writes  a  block  of  bytes to the file.  It returns TRUE if wLen
   bytes were successfully written.

BOOL PutChr(INT iChr);

   "PutChr" writes the  byte  in  iChr  to  the  file.   It  returns  TRUE  if
   successful.

BOOL PutChrs(INT iChr,WORD wCnt);

   "PutChrs"  writes  wCnt copies of the byte in iChr to the file.  It returns
   TRUE if wCnt bytes were written.

BOOL PutStr(CHAR *cpStr);

   "PutStr" writes the given string to the file (without the NUL  terminator).
   It returns TRUE if successful.

WORD Read(VOID *pBuf,WORD wCnt);

   "Read" reads from the file.  It returns the number of bytes read.

BOOL Save(BCFile *opFile);

   "Save" writes this object to the file represented by another BCFile object,
   which  must  be  open  for  writing  in  binary  mode.   It returns TRUE if
   successful.

BOOL SaveBool(BOOL blBool);

   "SaveBool" writes a BOOL to the file.  It returns TRUE if successful.

BOOL SaveByte(BYTE bByte);

   "SaveByte" writes a byte to the file.  It returns TRUE if successful.

BOOL SaveCoord(COORD coCoord);

   "SaveCoord" writes  a  COORD  value  to  the  file.   It  returns  TRUE  if
   successful.

BOOL SaveDblWord(DWORD dwDblWord);

   "SaveDblWord" writes a double word (4 bytes) to a file.  It returns TRUE if
   successful.

BOOL SaveDouble(DOUBLE dDouble);

   "SaveDouble" writes a DOUBLE to the file.  It returns TRUE if successful.

BOOL SaveFarBlk(VOID HUGE *lpBlk,LONG lSize);

   "SaveFarBlk"  writes  a  far or huge block of data to the file.  It returns
   TRUE if successful.

BOOL SaveFloat(FLOAT fFloat);

   "SaveFloat" writes  a  FLOAT  value  to  the  file.   It  returns  TRUE  if
   successful.

BOOL SaveInt(INT iInt);

   "SaveInt" writes an INT value to the file.  It returns TRUE if successful.

BOOL SaveLong(LONG lLong);

   "SaveLong" writes a LONG value to the file.  It returns TRUE if successful.

BOOL SaveLength(DWORD dwLen);

   "SaveLength"  writes  a  variable-length  length  field  to  the file.  Its
   objective is to use the fewest bytes possible to hold the length value.  It
   breaks up the length value into up to five bytes, each with 7 bits  of  the
   length  value  and a bit flag.  If the flag bit is set, it means that there
   is at least one more byte following the byte.  These length fragment  bytes
   are  stored with the bytes holding the most significant parts of the length
   first.  Therefore, with this scheme, if the length is less than 128 it  can
   be  stored  with  one  byte;  if less than 16384, two bytes; etc., up to 32
   bits.  SaveLength returns TRUE if successful.

BOOL SavePtr(VOID *pPtr);

   "SavePtr" writes pointer value to the file.  The number  of  bytes  written
   depends on the program's memory model.  SavePtr returns TRUE if successful.

BOOL SaveString(CHAR *cpString);

   "SaveString"  writes  a  string to the file.  It stores first the length of
   the string using SaveLength, followed by the string bytes (write  the  null
   terminator).  The cpString argument must point to a null-terminated string.
   SaveString returns TRUE if successful.

BOOL SaveStringPtr(CHAR *cpString);

   "SaveStringPtr" writes a string to the file.  It is the same as SaveString.

BOOL SaveWord(WORD wWord);

   "SaveWord"  writes  a  word  (2  bytes)  to  the  file.  It returns TRUE if
   successful.

VOID SetModule(BCModule *opMod);

   "SetModule" specifies the BCModule object that owns the file.

LONG SetPos(LONG lPos,WORD wMode);

   "SetPos" moves the current  position  in  the  file.   The  wMode  argument
   specifies  whether  lPos  is  relative  to  the  beginning, end, or current
   position of the file.  (Use the constant  values  listed  after  the  class
   declaration above.)  It returns -1L upon error.

WORD Write(VOID *pBuf,WORD wCnt);

   "Write" writes to the file.  It returns the number of bytes written.


                                  EXAMPLE

BCFile oFile("MyName");

if (oFile.Open(BC_WRITE_OPEN))
{
    if (!oFile.PutStr("Hello, file.\n"))
        DispMsg("Error writing file.");

    oFile.Close();
}
else
    DispMsg("Unable to open file.");

                         === End of BCFILE.DOC ===