EpochMessage - EPOCH V3 Network Message

The EpochMessage class implements EPOCH V3 messages. An EPOCH message consists of a 12-byte header and an optional message body. The header contains 4 fields:

ID - is a client-supplied message ID.

Response ID - is used to return the client's ID in a response message.

Number - is the message type; e.g., MSG_ACK, MSG_NAK, MSG_CONNECT, etc.

Length - is the length in bytes of the message body.

Typically, when a client sends a command to a server, the server returns the command message ID in the response ID field of the acknowledgement message. [The V3 communications library has a complicated scheme for managing message IDs; furthermore, the IDs are not even visible to the application. Since these IDs are not particularly useful, the ERA library doesn't bother with them; the EpochMessage::ID() methods are available for servers that need to respond to strictly conforming V3 messages.]

The optional message body can be an arbitrary sequence of bytes, stored and retrieved with the Body() methods. More commonly, however, the message body is a collection of EPOCH V3 name-value pairs (named variables) stored and retrieved in XDR format using the Encode() and Decode() methods, respectively.

The following code fragment constructs and sends a connect message to an EPOCH V3 device handler:

    #include  "EpochMessage.h"			// Epoch message class.
    #include  "EpochStream.h"			// Epoch stream class.
    ...
    EpochStream  handler ;			// Connection to device handler.
    ...
    NVarSet  *set = new NVarSet ;
    set->Add (new NVar (3, "HANDLEUNIT")) ;	// Device unit #3.
    EpochMessage  message (MSG_CONNECT) ;
    message.Encode (set) ;			// Encode parameters in body.
    handler.Write (-1.0, message) ;		// Send connect message.

To read the connect message and return an acknowledgement, the device handler might do as follows:

    #include  "EpochMessage.h"			// Epoch message class.
    #include  "EpochStream.h"			// Epoch stream class.
    ...
    EpochStream  *client ;			// Connection to device client.
    ...
    EpochMessage  *message ;
    client->Read (-1.0, message) ;
    if (message->Type () == MSG_CONNECT) {	// Decode parameters from body.
        NVarSet  *parameters = message->Decode () ;
        ... process parameters ...
        delete parameters ;
        EpochMessage  response (MSG_ACK) ;	// Construct response message.
        response.ID (message->ID ()) ;		// Put client ID in response field.
        client->Write (-1.0, response) ;	// Send acknowledgement message.
    }
    delete message ;

Public Methods

EpochMessage() - creates an EPOCH message.

EpochMessage() - copy constructor.

~EpochMessage() - destroys an EPOCH message.

=() - assignment operator.

Header() - gets the message header.

Type() - gets the message type.

Type() - sets the message type.

Length() - gets the length of the message body.

Body() - gets the message body.

Body() - sets the message body.

Decode() - decodes the message body into a set of named variables.

Encode() - encodes a set of named variables into the message body.

Erase() - erases the contents of a message.

Public Class Methods

Name() - converts a message number to a message name.

Number() - converts a message name to a message number.

Private Methods

Copy() - copies the contents of one message to another.

Source Files

EpochMessage.cpp

EpochMessage.h