Commit 2fb6c1c5 authored by Christian Fibich's avatar Christian Fibich
Browse files

Add readme.md

parent d68cdb23
# ZMQ Chat System #
## Getting Started ##
Install ZeroMQ as follows:
* Under Debian/Ubuntu, install the packages `libzmq3` and `libzmq3-dev`
* Under Fedora, install the packages `zeromq` and `zeromq-devel`
To get started with ZeroMQ, refer to http://zeromq.org/intro:read-the-manual
After installing the ZeroMQ development packages, man pages should
be available for all ZeroMQ library functions.
These can also be viewed online at http://api.zeromq.org/
The archive mentioned above contains code and a makefile. You can test
if you installed ZeroMQ correctly by unpacking the archive, and
executing `make` from the directory containing the archive content.
## Functionality ##
The server program contained in this repo mentioned above may be
executed in the following way:
```
./zmq_chat_server -r <REPLY_PORT> -p <PUBLISHER_PORT>
```
_Poster_ clients may send requests to the `REPLY_PORT` via `ZMQ_REQUEST`
sockets, while _Printer_ clients may connect to the `PUBLISHER_PORT`
using `ZMQ_SUBSCRIBER` sockets.
## To Do ##
* Implement the _poster_ program
* Implement the _printer_ program
### _Poster_ ###
The _Poster_ program shall send requests to the server application and
process its replies.
This request consists of a multi-part message sent to the `REPLY_PORT` of the server application.
NOTE: A multi-part message may contain multiple ZeroMQ messages as _parts_.
It is delivered _atomically_, which means that either *all* parts are
delivered to the receiver or the message is *not delivered at all*.
This message must contain the following parts in this order:
1. A *non-terminated* string containing a _Channel_ name
2. A *non-terminated* string containing a _Nick_ name
3. A *non-terminated* string containing the message
The server replies to each request with a multi-part message consisting
of the following parts in this order:
1. An integer describing the completion status (0 = OK, 1 = Not OK)
2. A message providing further details on the completion status in
a *non-terminated* string
[NOTE]
============
*non-terminated* means that the trailing `\0` byte is not transmitted
via ZeroMQ.
You may use the functions in `common/zmq_strings.c` to send/receive
conventional C strings via ZeroMQ
============
[TIP]
============
Multi-part messages can be *sent* by supplying the `ZMQ_SNDMORE` to
the link:http://api.zeromq.org/4-0:zmq-send[`zmq_send(3)`] and link:http://api.zeromq.org/4-0:zmq-msg-send[`zmq_msg_send(3)`] functions in all but the last
message parts.
Multi-part messages can be *received* using link:http://api.zeromq.org/4-0:zmq-recv[`zmq_recv(3)`] and link:http://api.zeromq.org/4-0:zmq-msg-recv[`zmq_msg_recv(3)`].
just like single-part messages. After receiving the current part of the
message, use
* link:http://api.zeromq.org/4-0:zmq-msg-more[`zmq_msg_more(3)`] on the message object if using link:http://api.zeromq.org/4-0:zmq-msg-recv[`zmq_msg_recv(3)`] or
* or link:http://api.zeromq.org/4-0:zmq-getsockopt[`zmq_getsockopt(3)`] on the socket with the `ZMQ_RCVMORE` option name if using link:http://api.zeromq.org/4-0:zmq-recv[`zmq_recv(3)`].
============
[NOTE]
============
You can read/write to a ZeroMQ socket directly from a buffer (e.g., an array) via
link:http://api.zeromq.org/4-0:zmq-recv[`zmq_recv(3)`]/link:http://api.zeromq.org/4-0:zmq-send[`zmq_send(3)`] or via ZeroMQ message objects using link:http://api.zeromq.org/4-0:zmq-msg-recv[`zmq_msg_recv(3)`]/link:http://api.zeromq.org/4-0:zmq-msg-send[`zmq_msg_send(3)`].
ZeroMQ messages provide an advantage for the receiver side: ZeroMQ allocates
as much memory as is needed to store the message dynamically.
A ZeroMQ message is just a variable of type `zmq_msg_t`. When messages are
no longer needed, they have to be freed using link:http://api.zeromq.org/4-0:zmq-msg-close[`zmq_msg_close(3)`].
============
The _Poster_ client shall provide the following command-line interface:
```
$ ./zmq_chat_poster -s <SERVER NAME/IP> -p <REPLY_PORT> -c <CHANNEL> -n <NICKNAME> <MESSAGE>
```
### _Printer_ ###
The _Printer_ program shall connect a `ZMQ_SUBSCRIBER` socket to the
server.
It may subscribe to one or more channels, which shall be passed as
command-line arguments.
[TIP]
============
Subscribing to a particular prefix is done by calling link:http://api.zeromq.org/4-0:zmq-setsockopt[`zmq_setsockopt(3)`]
on the socket with `ZMQ_SUBSCRIBE` as _option name_ and the prefix data
(in this case, the channel name) as _option value_.
============
[NOTE]
============
To prevent that a subscriber subscribed to channel _cat_ also
receives messages from channel _catastrophes_ (due to the common prefix _cat_),
append the separator character `SEP` from `common/messages.h` to the channel
name before calling `zmq_setsockopt(...,ZMQ_SUBSCRIBE,...)`.
============
Once connected and subscribed, the _Printer_ client may start to receive
messages from the server.
These messages have the following format:
```
<Channel>#<Timestamp>#<Nickname>#message
```
where `#` can be any separator character defined in `common/messages.h`.
This information shall be decoded and pretty-printed to the terminal by
the _Printer_ client.
The _Printer_ client shall provide the following command-line interface:
```
$ ./zmq_chat_printer -s <SERVER NAME/IP> -p <PUBLISHER_PORT> <CHANNEL1> [<further CHANNELS>]
```
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment