asciireflector

Network-reflector for ASCII data - very useful tool to distribute data between different networked programs.

DOWNLOAD

[ asciireflector-1.2.tar.gz (10k) ]

README

Author: A. Schiffler, aschiffler [at] ferzkopp.net to contact the author.
Licenced under the GPL; see the file COPYING for details.

[ asciireflector Ver. 1.2 ]

(c) under the GPL, A. Schiffler.

Please see file LICENSE for GPL notes.


[ version history ]

Ver 1.2 - Fri Sep 17 15:36:33 CEST 1999
- Fixed connection count
- Added a few messages
- Fixed PUSH behaviour
Ver 1.1 - Sun Aug 29 12:24:30 CEST 1999
- Put timeouts in read routine to fix "hang" after clients terminated
Ver 1.0 - Thu Aug 19 14:56:04 CEST 1999
- Initial release


[ introduction ]

The asciireflector is a simple, unix based reflector program that allows
sharing of data between clients through a TCP stream-socket connection. The
reflector reads ASCII lines from each connected client, buffers them in a
shared pool (ringbuffer) and sends all lines back to each client.


[ usage and protocol ]

Client reception is initiated by sending a textline to the reflector. This
will usually be the data that is to be shared between clients. This line 
gets stored in the reflectors buffer unless it is the text "POLL". All lines
send to the reflector have to end with a newline character. If the line is
preceded by the keyword "PUSH", the line gets distributed by the reflector
with the PUSH removed, but no lines get send back to the client. Otherwise
immediately after the reception from the client, all textlines that have 
been received since the last sending of text will be written back to the 
client. This sequence is finished when the text "OVER" is send from the
reflector. This means no new textlines are in the ringbuffer. To close the
socket connection with the reflector, send the word "LOGOUT". 

Note that the reflector sends the last textline that was received from 
the client back to the client during the next iteration. This can be 
used to test if the speed of the network connection is sufficient 
to maintain complete reception of the ringbuffer. If the first line 
received is not equal to the last line send, the ringbuffer has been 
overwritten by another client in the mean time, indicating that 
reception is too slow. Reflector use should be stopped in such a case.

Thus the client should run the following sequence repeatedly:

1. Connect to reflector
2.)   Send data

2.1.) Send data as "textline", store as "last_textline"

OR

2.2) Send "POLL"

OR

2.3) Send "PUSH__and__some_text" to send text without having to receive
anything (i.e. proceed to 4.)

3.)  Read data
3.1.) Read "textline" unless PUSH was send
3.1.2) If first "textline" is not "last_textline" abort with an error
3.2.) Repeat from 3.1 until "textline" is the "OVER"
4.) ... do other stuff ...
5.) Goto 2. or send "LOGOUT"

The use of ASCII and stream-sockets was used for its easy of use and
transparency - its not very efficient though for realtime applications that
have to transport a lot of data.


[ compilation and test ]

To compile the source type
	make

Then run
	asciireflector

To test, connect to the reflector in (a few) different terminal(s) with
	telnet localhost 1522
and type a few lines.

The program was developed on a RedHat Linux system but should work with
any unix system that provides a pthread implementation.


[ limits and settings ]

The current (compiled-in defaults) are:

Port number		1522
Connections		20
Line Length		128 chars (including newline)
Size of Ringbuffer	1024 lines

Change the defines in the .h files to adjust to your application.