MGE General C Library - API Documentation v1.8.0
Library of general C functions.
Message Buffers and Messages

Overview

These library functions address the need to exchange meassages, maybe between processes on the same machine, or, maybe between machines using UDP or TCP streams. The only fixed aspect of a message is that it contains 1 or more fields separated by a 'separator' charcter and terminated by a 'terminator' character. These 2 characters are defined in the mgemessage struct.

The data source for this system is a flat buffer which may contain part of a message, a complete message or mutiple messages.

This flat buffer is first loaded into a mgebuffer struct which maintains a buffer and indexes to the next byte to be processed and the next free byte.

This mgebuffer struct is then processed, extracting data into a mgemessage struct until it contains a complete message. When it contains a complete message it is parsed into individual arguments held in the struct.

Buffers

The buffers area consists of 2 functions; concat_buf() and trim_buf().

concat_buf()

concat_buf() takes the supplied flat buffer and appends it to the buffer in the supplied mgebuffer struct updating the relevant pointers.

trim_buf()

The trim_buf() function removes processed data from the mgebuffer struct buffer. It is typically called after some or all of the data in the mgebuffer struct has been processed.

Messages

The message area API consists of 2 functions; pull_msg() and clear_msg().

The following diagram shows a typical message workflow.

Functions

pull_msg()

The pull_msg() function extracts data from the mgebuffer struct buffer and loads it into a mgemessage struct. The processed part of the mgebuffer struct buffer is then removed by invoking trim_buf(). If the mgemessage struct buffer then holds a complete message it fully populates the mgemessage struct.

clear_msg()

The clear_msg() function frees the message buffer and argument storage and resets the other fileds to initial values.