[binimg.h] Portable machine-independant binary format

contents

  Summary

  [binimg] offers a set of functions to read and write binary files in a portable
  machine-independant format. Within the STYX-system they are used to make data structures
  persistent.

  non-reentrant API:

  For each supported data type exist a read and write function with the following signature.

  |   void put<TYPE>(<CTYPE>  x);
  |   void get<TYPE>(<CTYPE> &x);

  Source and target are implicit in these operations. The functions 'getBgn' and 'getEnd'
  open and close a source. To open and close a target one has to use the functions 'putBgn'
  and 'putEnd'. So it is not possible to read or write more than one file at a time.

  reentrant API:

  For each supported data type exist a read and write function with the following signature.

  |   void fput<TYPE>(BinImg_T img, <CTYPE>  x);
  |   void fget<TYPE>(BinImg_T img, <CTYPE> &x);

  The functions 'fgetBgn' and 'fgetEnd' open and close a source. To open and close a target
  one has to use the functions 'fputBgn' and 'fputEnd'. So it is possible to read or write
  more than one file at a time.

  Each binary file within the STYX-system starts with a header block. Creation and reading
  e.g. checking is done by the functions 'putHeader' and 'getHeader' respectively
  'fputHeader' and 'fgetHeader'.

  The binary files are protected against unauthorized reading and writing by an integrated
  combined encryption and checking method. Further more they will be compressed.

  Files and EOF

  With the non-reentrant API it is not possible to read or write more than one file at a time.

  This module doesn't support an explicit EOF-predicate. It is the responsibility of the user
  to check for EOF. Reading behind EOF causes the program to abort with an error message.

BinImg_T BIN_getCurImage(void)

void BIN_setIncEvent(void (*evt)(float lvl))

void fBIN_setIncEvent(BinImg_T img,void (*evt)(float lvl))

Open & Close

void putBgn(c_string EnvVar, c_string FileName, c_string Ext)

BinImg_T fputBgn(c_string EnvVar, c_string FileName, c_string Ext)

BinImg_T TryfputBgn(c_string EnvVar, c_string FileName, c_string Ext)

void getBgn(c_string EnvVar, c_string FileName, c_string Ext)

BinImg_T fgetBgn(c_string EnvVar, c_string FileName, c_string Ext)

BinImg_T TryfgetBgn(c_string EnvVar, c_string FileName, c_string Ext)

void putEnd(void)

void fputEnd(BinImg_T img)

void getEnd(void)

void fgetEnd(BinImg_T img)

Header

  There are a lot of reasons to save some informations at the beginning of such a file.

  Beside a short text describing the content of the file, the user want to be sure that
  the file has the expected format. Following an old tradition this will be done by a
  'Magic'.

  To handle format changes of binary files we introduce a version. The version consists
  of two numbers ('Major', 'Minor'). Binary formats with different major-numbers are
  treated as incompatible. Binary formats with different minor-numbers are treated as
  upward compatible.

  Furthermore this module has an internal version number to track changes of the internal
  format.

  Contrary to the external representation the title will be be saved as null-terminated
  string.

  'getHeader' respectively 'fgetHeader' checks these informations and aborts the operation
  in the case of an error. During the read or write process the current minor-version is
  accessable via the function 'MinorVersion' respectively 'fMinorVersion'.

void putHeader(c_string Title, c_string Magic, c_byte Major, c_byte Minor)

void fputHeader
     (
       BinImg_T img, c_string Title, c_string Magic, c_byte Major, c_byte Minor
     )

void getHeaderInfo(c_string *Com, c_string *Mag, c_byte *Ma, c_byte *Mi, c_byte *Bv)

void fgetHeaderInfo
     (
       BinImg_T img, c_string *Com, c_string *Mag,
       c_byte *Ma, c_byte *Mi, c_byte *Bv
     )

void getHeader(c_string Magic, c_byte Major, c_byte Minor)

void fgetHeader(BinImg_T img, c_string Magic, c_byte Major, c_byte Minor)

void getHeaderTitle(c_string Magic, c_byte Major, c_byte Minor, c_string* Title)

void fgetHeaderTitle
     (
       BinImg_T img, c_string Magic, c_byte Major, c_byte Minor, c_string* Title
     )

short MinorVersion(void)

short fMinorVersion(BinImg_T img)

Data types

  Actually the following data types are supported.

  | TYPE      | CTYPE                  |
  +-----------+------------------------+----------------------------
  | Byte      | unsigned char          |
  | Word      | unsigned short int     |   Intrinsic C-data types
  | Long      | signed long int        |
  | ULong     | unsigned long int      |
  | Int64     | signed long long int   | if supported type
  | UInt64    | unsigned long long int | if supported type
  +-----------+------------------------+----------------------------
  | String    | (char *)               |   Strings
  | WC-String | (wchar_t *)            |   Unicode Strings
  | Binary    | c_bstring              |   binary Strings
  | Symbol    | symbol                 |   Symbols
  | Function  | (? (*)())              |   Functions
  | Abstract  | (?)                    |   "Objects"
  | StdCPtr   | (?*)                   |   References

Plain values

void putByte(c_byte v)

void fputByte(BinImg_T img, c_byte v)

void getByte(c_byte *v)

void fgetByte(BinImg_T img, c_byte *v)

int getByte_or_EOF(void)

int fgetByte_or_EOF(BinImg_T img)

void putWord(short v)

void fputWord(BinImg_T img, short v)

void getWord(short *v)

void fgetWord(BinImg_T img, short *v)

void putLong(long v)

void fputLong(BinImg_T img, long v)

void getLong(long *v)

void fgetLong(BinImg_T img, long *v)

void putULong(unsigned long v)

void fputULong(BinImg_T img, unsigned long v)

void getULong(unsigned long *v)

void fgetULong(BinImg_T img, unsigned long *v)

void putInt(int v)

void fputInt(BinImg_T img, int v)

void getInt(int* v)

void fgetInt(BinImg_T img, int* v)

#ifdef STYX_CONFIG_TINT64

void putInt64(c_int64 v)

void fputInt64(BinImg_T img, c_int64 v)

void getInt64(c_int64 *v)

void fgetInt64(BinImg_T img, c_int64 *v)

void putUInt64(c_uint64 v)

void fputUInt64(BinImg_T img, c_uint64 v)

void getUInt64(c_uint64 *v)

void fgetUInt64(BinImg_T img, c_uint64 *v)

#endif

void putString(c_string v)

void fputString(BinImg_T img, c_string v)

void getString(c_string *v)

void fgetString(BinImg_T img, c_string *v)

void putWCString(wc_string v)

void fputWCString(BinImg_T img, wc_string v)

void getWCString(wc_string *v)

void fgetWCString(BinImg_T img, wc_string *v)

void putBString(c_bstring v)

void fputBString(BinImg_T img, c_bstring v)

void getBString(c_bstring *v)

void fgetBString(BinImg_T img, c_bstring *v)

Huge binaries

void putHuge(HugeCPtr v, long len)

void fputHuge(BinImg_T img, HugeCPtr v, long len)

void getHuge(HugeCPtr *v, long *len)

void fgetHuge(BinImg_T img, HugeCPtr *v, long *len)

Symbols

void putSymbol(symbol v)

void fputSymbol(BinImg_T img, symbol v)

void getSymbol(symbol *v)

void fgetSymbol(BinImg_T img, symbol *v)

Functions

void putFunction(StdCPtr v)

void fputFunction(BinImg_T img, StdCPtr v)

void getFunction(StdCPtr *v)

void fgetFunction(BinImg_T img, StdCPtr *v)

Abstract types

   In the case of a generic data type ( e.g. 'List(Alpha)') a 'put'-function
   typically looks like:

   non-reentrant API:
   |  void putList(List(Alpha) v, void putAlpha(Alpha v))
   |  {
   |    putInt(List_length(v));
   |    for (; !List_null(v); v = List_rest(v))
   |      putAlpha(List_first(Alpha,v));
   |  }

   reentrant API:
   |  void putList(BinImg_T img, List(Alpha) v, void putAlpha(BinImg_T img,Alpha v))
   |  {
   |    fputInt(img,List_length(v));
   |    for (; !List_null(v); v = List_rest(v))
   |      putAlpha(img,List_first(Alpha,v));
   |  }

   In the case of a heterogen parameter type ("Object") the user has to save
   the corresponding 'get'-function together with the value.

void putAbstract(Abs_T v, void putData(Abs_T v), void getData(Abs_T *v))

void fputAbstract
     (
       BinImg_T img, Abs_T v,
       void putData(BinImg_T img,Abs_T v),
       void getData(BinImg_T img,Abs_T *v)
     )

void getAbstract(Abs_T *v)

void fgetAbstract(BinImg_T img, Abs_T *v)

Pointer

   References to multiple or cyclic referenced structures ( except symbols and functions )
   can't be simply expanded if the representation should be unique.
   For cases like this we support the following function.

   non-reentrant API:
   |  void putReference(Abs_T  v, void putData(Abs_T v));

   reentrant API:
   |  void fputReference(BinImg_T img, Abs_T  v, void putData(BinImg_T img,Abs_T v));

   This function outputs a reference number for this structure and only in the case of the
   first reference the structure values.

void putReference(Abs_T v, void putData(Abs_T v))

void fputReference
     (
       BinImg_T img, Abs_T v, void putData(BinImg_T img,Abs_T v)
     )

void getReference(Abs_T *v, void getData(Abs_T *v))

void fgetReference
     (
       BinImg_T img, Abs_T *v, void getData(BinImg_T img,Abs_T *v)
     )