Galaxy Communicator Documentation:

MITRE Utilities: Binary Data Tools

License / Documentation home / Help and feedback

The MIT binary data object can be used to transmit arbitrary structures from server to server, among other things. In this set of tools, we provide a facility for automatically encoding and decoding these structures. We provide an example of this facility in the context of the binary data example.

See the page on compiling and accessing these utilities.


Defining the data type

The MIT system supports a set of predefined datatypes which are used when determining the types of information transmitted over broker connections and stored in keys of frames. The tools here allow the user to "extend" this set of types.

typedef void *(*MGal_BinaryDataEncoder)(void *obj, int *size)
typedef void *(*MGal_BinaryDataDecoder)(void *data, int size)

void MGal_AddBinaryDataType(int data_type, MGal_BinaryDataEncoder encoder, MGal_BinaryDataDecoder decoder)
This function associates the encoder and decoder functions with the data_type. The encoder takes an arbitrary structure and returns something that will be treated as an array of bytes of length size.  The decoder takes an array of bytes of length size and returns an arbitrary structure. The programmer defines the encoder and decoder; typically, the types are declared in _GalSS_init_server:


Storing and accessing the data type

We provide facilities for storing and accessing this data. The functions here are intended to be parallel to functions like Gal_IntObject/Gal_GetInt, etc.

Gal_Object MGal_OpaqueObject(void *obj, int data_type)
Given an object whose encoder and decoder have been associated with data_type, return an object suitable for use as a value of a frame key. This function constructs a frame which contains the data_type and the binary encoding of the object:

{c __opaque__
   :type <datatype>
   :data <binary_encoding>}
void *MGal_GetOpaque(Gal_Frame fr, char *key, int *data_type)
Looks for a frame of the structure just described as the value of key in frame fr, decodes it according to its user-defined atatype, and sets the data_type. If the key does not exist, or the value is not a frame of the form described, or if there is no decoder for the datatype the frame contains, this function returns NULL and does not set data_type.

void *MGal_GetOpaqueWarn(Gal_Frame fr, char *key, int data_type)
Like MGal_GetOpaque, but in addition returns NULL if the element found is not of the required data_type.

In the example provided, the reinitialize dispatch function creates an object and dispatches it to the Hub, which returns it to othe receive_binary dispatch function, which prints out the structure based on its decoded type:


License / Documentation home / Help and feedback
Last updated September 20, 2001