[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
|