Galaxy Communicator Documentation:

Binary Data

License / Documentation home / Help and feedback

In addition to brokering, MIT provides a way of moving binary data among servers, using the binary frame object. We can use this object either to send around audio data, or to encode arbitrary structures which remain opaque to the Communicator Hub. (Be aware that unlike brokering connections, big_endian/little_endian issues are not addressed in the binary data tools, since only 8 bit binary data can be encoded.)

We provide an example of using binary objects for audio to compare with our example of using brokering for audio. In this section, we show how one might use binary objects to encode arbitrary structures.

Passing arbitrary data

The key aspect of using binary objects to encode arbitrary data is to write encoding and decoding functions for the data. In the example we provide, we encode and decode a simple structure, whose slots are initialized in the reinitialize() message:

typedef struct __MTestStruct {

int first;

int last;

char *msg;

} MTestStruct;

static void *encode_test_struct(MTestStruct *s, int *len)
{
char *encode_buf;

encode_buf = (char *) malloc(sizeof(char) * (strlen(s->msg) + 64));
sprintf(encode_buf, "%d %d %s", s->first, s->last, s->msg);
*len = strlen(encode_buf);
return (void *) encode_buf;
}

static MTestStruct *decode_test_struct(void *data, int len)
{
MTestStruct *s = (MTestStruct *) malloc(sizeof(MTestStruct));
int where;

sscanf(data, "%d %d %n", &(s->first), &(s->last), &where);
s->msg = (char *) malloc(sizeof(char) * (1 + (len - where)));
strncpy(s->msg, data + where, len - where);
return s;
}

The important step here is for the server or servers which need access to this arbitrary data to agree on a binary (or string) encoding of the data. The data will be passed untouched. In our example, the reinitialize() message creates a structure, encodes it, and passes it to the Hub, and the receive_binary() message decodes the data, recreates the structure, and prints out the contents of the structure:

Gal_Frame receive_binary(Gal_Frame f, void *server_data)

{

int size = 0;

void *buf = Gal_GetBinary(f, ":binary_data", &size);

MTestStruct *s = decode_test_struct(buf, size);

sls_pinfo1("Decoded buf is `%s'\n", buf);
sls_pinfo1("First is %d, last is %d, msg is `%s'\n",
s->first, s->last, s->msg);
return (Gal_Frame) NULL;
}

Gal_Frame reinitialize(Gal_Frame f, void *server_data)
{
Gal_Frame fr;
int len;
void *data;
MTestStruct *s = (MTestStruct *) malloc(sizeof(MTestStruct));

s->first = Gal_GetInt(f, ":test_first");
s->last = Gal_GetInt(f, ":test_last");
s->msg = Gal_GetString(f, ":test_msg");

/* Create a new message. */
fr = Gal_MakeFrame("main", GAL_CLAUSE);
data = encode_test_struct(s, &len);
Gal_SetProp(fr, ":binary_data", Gal_BinaryObject(data, len));
GalSS_EnvWriteFrame((GalSS_Environment *) server_data, fr, 0);
Gal_FreeFrame(fr);
return (Gal_Frame) NULL;
}

Note how the data and size established by the encoder are used to create a binary object, and then how the data and size in the binary object are passed to the decoder to recreate the structure. In this way, data structures which the Hub knows nothing about can be passed between servers without needing to recursively duplicate the structure of the data in frames.

License / Documentation home / Help and feedback

Last updated October 10, 1999

Galaxy Communicator Documentation: Binary Data

Passing arbitrary data

Galaxy Communicator Documentation:

Binary Data