epc_util - EPOCH Communications Utilities

The EPC utilities are used to send and receive EPOCH 3.0-compatible messages over TCP/IP network connections. An EPOCH message consists of a 12-byte header followed by zero or more, XDR-encoded named variables. The contents of the header specify a message ID and the total message length, among other things.

The following program implements a simple EPOCH server that receives commands from its client and returns status messages to the client:

    #include  <stdio.h>				-- Standard I/O definitions.
    #include  "tcp_util.h"			-- TCP/IP networking utilities.
    #include  "epc_util.h"			-- EPOCH network streams.

    int  main (int argc, char *argv[])
    {
        EpochStream  stream ;
        EpochHeader  header ;
        NVarSet  command, status ;
        TcpEndpoint  client, server ;

        tcpListen (argv[1], 99, &server) ;	-- Create listening endpoint.

        for ( ; ; ) {				-- Answer next client.
            tcpAnswer (server, -1.0, &client) ;
            epcCreate (client, &stream) ;
            for ( ; ; ) {			-- Service connected client.
                if (epcReadSet (stream, -1.0, &header, &command))  break ;
                ... process command ...
                ... construct status message ...
                header.responseID = header.ID ;
                epcWriteSet (stream, -1.0, &header, status) ;
            }
            epcDestroy (stream) ;		-- Lost client.
        }

    }

The server's name is specified as the first argument on the command line (i.e., argv[1]). If a client connection is broken, the server loops back to wait for another client.

The client program below sends commands to the EPOCH server and reads the status messages that are returned:

    #include  <stdio.h>				-- Standard I/O definitions.
    #include  "tcp_util.h"			-- TCP/IP networking utilities.
    #include  "epc_util.h"			-- EPOCH network streams.

    int  main (int argc, char *argv[])
    {
        EpochStream  stream ;
        EpochHeader  header ;
        NVarSet  command, status ;
        TcpEndpoint  connection ;

        tcpCall (argv[1], 0, &connection) ;	-- Call server.
        epcCreate (connection, &stream) ;
        for ( ; ; ) {				-- Communicate with server.
            ... construct command message ...
            epcWriteSet (stream, -1.0, &header, command) ;
            if (epcReadSet (stream, -1.0, &header, &status))  break ;
            ... process status message ...
        }
        epcDestroy (stream) ;			-- Lost server.

    }

Both epcReadSet() and epcWriteSet() take a timeout argument that allows the application to limit the amount of time these routines wait to perform their respective functions.

In event-driven applications (e.g., those based on the X Toolkit or the IOX dispatcher), the socket connection underlying the EPOCH stream, returned by epcFd(), can be monitored for input by your event dispatcher. Because input is buffered, the input callback must repeatedly call epcRead() or epcReadSet() while epcIsReadable() is true.

Public Procedures

epcCreate() - creates an EPOCH network stream.

epcDestroy() - deletes an EPOCH network stream.

epcFd() - returns an EPOCH stream's socket number.

epcIsReadable() - checks if input is waiting to be read from a stream.

epcIsUp() - checks if an EPOCH stream is up.

epcIsWriteable() - checks if data can be written to a stream.

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

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

epcName() - returns the name of an EPOCH stream.

epcRead() - reads the next message from an EPOCH stream.

epcReadSet() - reads an NVarSet message from an EPOCH stream.

epcWrite() - writes a message to an EPOCH stream.

epcWriteSet() - writes an NVarSet message to an EPOCH stream.

Source Files

epc_util.c

epc_util.h