[binimg.h] Portable machine-independant binary format


#include "standard.h"
#include "symbols.h"



  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 date structures
  persistent.

  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.

  Eaxh 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'.

  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

  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.

void BIN_setIncEvent(void (*evt)(float lvl))
set the get-inc event


Open & Close

void putBgn(c_string EnvVar, c_string FileName, c_string Ext)
open [$'EnvVar'/'FileName''Ext'] to put binary image
void getBgn(c_string EnvVar, c_string FileName, c_string Ext)
open [$'EnvVar'/'FileName''Ext'] to get binary image
void putEnd(void)
completes binary puting
void getEnd(void)
completes binary geting


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' 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'.

void putHeader(c_string Title, c_string Magic, c_byte Major, c_byte Minor)
put header
void getHeaderInfo(c_string *Com, c_string *Mag, c_byte *Ma, c_byte *Mi, c_byte *Bv)
get header information ( title,magic,major,minor,version )
void getHeader(c_string Magic, c_byte Major, c_byte Minor)
validates header
void getHeaderTitle(c_string Magic, c_byte Major, c_byte Minor, c_string* Title)
validates header, returns title
short MinorVersion(void)
'Minor' of the file


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
  | Binary    | c_bstring              |   binary Strings
  | Symbol    | symbol                 |   Symbols
  | Function  | (? (*)())              |   Functions
  | Abstract  | (?)                    |   "Objects"
  | StdCPtr   | (?*)                   |   References



Plain values

void putByte(c_byte v)
put 'v' to file
void getByte(c_byte *v)
get 'v' from file
int getByte_or_EOF(void)
get byte or EOF from file
void putWord(short v)
put 'v' to file; msb first
void getWord(short *v)
get 'v' from file; msb first
void putLong(long v)
put 'v' ( <= 32 Bit ) to file; msw first
void getLong(long *v)
get 'v' from file; msw first
void putULong(unsigned long v)
put 'v' ( <= 32 Bit ) to file; msw first
void getULong(unsigned long *v)
get 'v' from file; msw first
void putInt(int v)
put 'v' ( <= 16 Bit ) to file
void getInt(int* v)
get 'v' from file

#ifdef STYX_CONFIG_TINT64

void putInt64(c_int64 v)
put 'v' ( <= 64 Bit ) to file; msl first
void getInt64(c_int64 *v)
get 'v' from file; msl first
void putUInt64(c_uint64 v)
put 'v' ( <= 64 Bit ) to file; msl first
void getUInt64(c_uint64 *v)
get 'v' from file; msl first

#endif

void putString(c_string v)
put 'v' to file; length byte first
void getString(c_string *v)
get 'v' from file; length first; allocs memory
void putBString(c_bstring v)
put 'v' to file
void getBString(c_bstring *v)
get 'v' from file; allocs memory


Huge binaries


To save and load large binary data blocks the following functions can be used.
void putHuge(HugeCPtr v, long len)
put 'len' bytes to file
void getHuge(HugeCPtr *v, long *len)
get 'len' bytes from file


Symbols


Symbols are externally represented as ( binary ) strings.
The leading byte specifies the symbol type.
void putSymbol(symbol v)
put a symbol to file
void getSymbol(symbol *v)
get a symbol from file


Functions


For technical reasons the functions must be defined in a global table.
They are externally represented by a symbolic name representing the key to the function table entry. ( see also [glo_tab] )
void putFunction(StdCPtr v)
put a function to file
raises error if 'v' not 'Glo'bally defined

void getFunction(StdCPtr *v)
get a function from file
raises error if 's' not 'Glo'bally defined



Abstract types


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

   |  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));
   |  }

   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))
put abstract data to file
void getAbstract(Abs_T *v)
get abstract data from file


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.

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

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

void putReference(Abs_T v, void putData(Abs_T v))
put a pointer to file
void getReference(Abs_T *v, void getData(Abs_T *v))
get a pointer from file