ChatRev protocol:
Pertains to version 1.2, including forum handling

About:
The ChatRev protocoll was done by Björnke von Gierke, based on experience with the IRC protocol. It also has grown and evolved a bit since the first usable version. This document has very detailed descriptions of every term, but after some definitions there's first a list of every term with a short description, ordered by sender.

A note on Styling and its meanings

Every message is delimited by returns. Every message is ended with return. In the examples I give, "return" is written as "cr". Note that no message can contain returns unless specific mentioned otherwise. Also in the examples is "comma" which means the comma character (,). The last mentioned delimiter is "tab" which means the tabulator.
Text you send is in quotes (eg: "login", variables you need to fill in are plain (eg: yourMessageHere). All communication is case independent, as usual in Rev. Example code is in Times new roman, example scripts from Rev is  Italic (also Times new Roman).

Client Messages
"register" & cr & nickname & comma & password & comma & "anything" & cr
Every chatter needs to register only once
"login" & cr & nickname & comma & password & cr
Initiates the login procedure
"version 1.2" & cr
Second part of the login procedures
"chat" & cr & htmltext & cr
Send a chat message to everyone
"message" & cr & htmltext & cr
Send a private message to a single person
"me" & cr & text & cr
Send a humorous emote message to everyone
"setabout" & cr & text & cr
Set your longer description, is only seen by other user on demand
"setMouse" & cr & text & cr
Short descriptive text, shown all the time in some clients, updates immediately
"setmail" & cr & text & cr
Specify a contact email
"getmail" & cr & Nickname & space & subject & cr
Querry the contact email of another person
"getAbout" & cr & Nickname & cr
Querry the longer description of a person
"pong" & cr
Answer to ping with this, only the server will notice
"disconnect" & cr
Quit the chat
"threads" & cr & forumName & cr
Get threads for the forum
"postReply" & cr & forumName & cr & threadID & cr & theCount & cr & theText
Make a Reply to a thread
"makeThread" & cr & theForum & cr & userLogin & theThread & cr & theCount & cr & theMessage
Create a thread, and make the first entry to it
"getThread" & cr & theForum & cr & threadID & cr
get all the entries in a thread.

Server Messages
"taken" & cr
this means that the nick is already registered
"empty nick" & cr
this means that item one (above: nickname) of your message was empty
"registered" & cr
Yay, new users!
"login wrong" & cr
either the user was not found, or the password was wrong
"logged in" & cr
This is a lie, you're not yet logged in, but on a good way towards that goal
"version OK" & cr
Your version string was approved
"please update to version 1.2, http://homepage.mac.com/bvg/chatrev1.2.rev" & cr
Your version was not approved
"chat" & cr & Nickname & cr & htmltext & cr
Someone send a chat message to everyone
"message" & cr & Nickname & cr & htmltext & cr
Someone send you a private message
"me" & cr & Nickname & cr & plaintext & cr
Someone has a feeling
"setmouse" & cr & Nickname & tab & label & cr
Someone has set his caption
"member" & cr & nickname & tab & label & cr
Someone joined the chat
"unmember" & cr & nickname & tab & label & cr
Someone left the chat
"threads" & cr & theCount & cr & theThreads
You demanded the threats of a forum, and now you got em
"thread" & cr & theCount & theMessage
You demanded to know a threads messages, and now you got them
"error" & cr & theErrorMessage & cr
Disconnect immediately (i'm not sure this is used anywhere)
"ping" & cr
Answer with pong immediately
"kick" & cr
Should force client to disconnect, but not yet implemented on server

Connecting to the chat:
You need to know the IP and the port of the chat server to connect to it. The IP of my Server is currently  81.221.127.96, the port is 8008. This stable server has no planned downtimes. As a client, you are generally expected ignore messages that are not in this document. As a server you are expected to disconnect clients who send non-approved messages.

registering:

Registering is not very complicated, with few steps needed. First you open the socket to the chatrev server:
open socket to field "ip" & ":8008" with message connected

Then you write your first message to the socket:
"register" & cr & nickname & comma & password & comma & cr
The nickname can contain any chars, besides "tab" or ","(comma).
the password can contain any chars, besides ",".
the last comma is due to a third parameter that got removed. One could add any string that does not contain a comma there.

The server responses with one of these messages:
"taken" & cr
this means that the nick is already registered.
"empty nick" & cr
this means that item one (above: nickname) of your message was empty.
"registered" & cr
your client has successfully registered the user nickname.

if you want to set the user modifiable data (mouseover, about, label), then you just send the appropriate messages now (they are described further below).

after registering you send a disconnect message:
"disconnect" & cr
the socket to the server should now be closed by using the "close socket" command.

login:

Login is a multi step affair. First you open the socket to the chatrev server.

Then you send your login information:
"login" & cr & nickname & comma & password & cr

The server responds with one of these messages:
"login wrong" & cr
either the user was not found, or the password was wrong.
"logged in" & cr
You can now proceed with logging in (you are not finished yet).

You now write your version information:
"version 1.2" & cr

The server should now send you one of these:
"version OK" & cr
if it is ANYTHING else, then you should disconnect, and show the received message to the user.
"please update to version 1.2, http://homepage.mac.com/bvg/chatrev1.2.rev" & cr
the current error message, when connecting with anything but 1.2

the server now proceeds to send your login information to everyone else that is connected. This contains: a "member" message and a "setmouse" message.
The server also sends the same to you about every other logged in client.
the other clients also get a "message" from the server, saying "Nickname: joined the chat at " and the server time. Whereas you get a "message" from the server saying "Nickname: you joined the chat at " and the server time. When you have received that, then you are properly connected.

Chat messages:

all these messages can be received at any time after you have send the version number.

the chat message indicates a message that is send to everyone. Excluded are messages from the server which might get send to everyone, but are always "messages". Chat goes like this:
"chat" & cr & Nickname & cr & htmltext & cr
you receive this to show the text. Version 1.1 and 1.0 have submitted clear text here, but htmltext allows for multiple lines and formatting.

the message message indicates a private message, only send to you (except server messages which are send to everyone). it goes like this:
"message" & cr & Nickname & cr & htmltext & cr
you receive this to show the text. Version 1.1 and 1.0 have submitted clear text here, but htmltext allows for multiple lines and formatting.

the me message indicates a humorous action. it is send to everyone, like the chat message.
"me" & cr & Nickname & cr & plaintext & cr
The me message allows no formatting or htmltext.

Status & special messages:

all these messages can be received at any time after you have send the version number.

the setmouse message sets the caption (previously called "MouseOver" or "Label") of a user to a certain value. It goes like this:
"setmouse" & cr & Nickname & tab & label & cr
This allows you to store the caption of a user. Note that this is necessary because messages about other chatters are always identified by both the nickname and the caption.

the member message indicates that a user has logged on. It goes like this:
"member" & cr & nickname & tab & label & cr
After this message you automatically get a private message by the server that the person has logged on. Note that you can't rely on the label for identifying users, just use the nickname to do that.

the unmember message indicates that a user has logged off It goes like this:
"unmember" & cr & Nickname & tab & label & cr
After this message you automatically get a message by the server that the person has logged off. Note that you can't rely on the label for identifying users, just use the nickname to do that.

The error message indicates that you have done something bad (not following the protocol) so you get this message:
"error" & cr & theErrorMessage & cr
you should disconnect after this message, socket communication can not be guaranteed anymore. I'm not sure if this message is even used anymore.

If you get a ping message, you should write a pong message to the server, or you will be disconnected.
"ping" & cr
"pong" & cr

the kick message is there to kick too talkative people.
"kick" & cr 
you should disconnect when receiving this message.

Messages you can write (non forum stuff):

"chat" & cr & htmltext & cr
send a message to everyone

"message" & cr & htmltext & cr
send a message to a single recipient

"me" & cr & text & cr
send a humorous emote message to everyone

"setabout" & cr & text & cr
set your about

"setMouse" & cr & text & cr
set your caption

"setmail" & cr & text & cr
this text may not contain spaces. and should be a mail address

"getmail" & cr & Nickname & space & subject & cr
When you send this message you automatically get a response from the server:
"mail" & cr & mailadress & space & subject & cr
where subject is the same as you have send before.

"getAbout" & cr & Nickname & cr
Again this gives you a autoreply, this time a private message which contains the about of the user Nickname.

Forum messages:

There is a build in forum in ChatRev, these messages are used to interface it. As this was added later on, and the forum does not allow styles, there will be some messages that allow returns in the data. For most messages, you need the name of an existing forum. Currently there's two valid forum names: "General discussion" and  "Support forum"

"threads" & cr & forumName & cr
You send this to get a list of threads in the specified forum. The server will respond with the following message:

"threads" & cr & theCount & cr & theThreads
You should read for theCount chars/bytes. theThreads will be a comma delimited list. Item 1 of each line is a unique identifying integer (an ID). Item 2 of each line is a time in seconds. This time is the last time someone has made a reply to that thread (usefull for sorting). Item 3 of each line is the plain text thread title.

"postReply" & cr & forumName & cr & threadID & cr & theCount & cr & theText
The threadID is a thread number you got by sending the "threads" message. TheCount is the number of chars respectively bytes in theText, which is your plain text message. theMessage starts with the nickname/login of the current user , followed by colon (:), and ends with the actual message.

"makeThread" & cr & theForum & cr & userLogin & theThread & cr & theCount & cr & theMessage
Similar to "postReply", but allows you to specify a new Thread.
theForum again is a valid forum name. theThread is a plain text line. theCount is the number of chars in (which is also the number of bytes of) theMessage. theMessage is plain text. It starts with the nickname/login of the current user , followed by colon (:), and ends with the actual message.

"getThread" & cr & theForum & cr & threadID & cr
Used to read the Threads. Note that there's no way to get a single message. Again, the threadID is the number you got from the "threads" message. You'll get this as an answer:

"thread" & cr & theCount & theMessage
You should read from socket for theCount chars/bytes to get the whole message.

Deprecated and unused messages

Generally you should never send or receive these messages, as they're mostly left overs from failed attempts. Maybe you'll get a response maybe not, maybe you'll be disconnected for sending a not approved message, or you might disconnect or disturb the remote user.

"fileRequest" & cr & nickName & cr & filePath & cr & fileDescription
"fileAccept" & cr & theRemoteUser & cr & myFilePath & cr & "Not implemented" & cr
"fileAccept" & cr & theRemoteUser & cr & myFilePath & cr & "Accept" & cr
Peer to Peer File sending was tested, but didn't work satisfactory. It blocked the chat from working properly, due to the big data sizes.

"subscribe" & cr & "rss" & cr
This was a trial to implement a RSS feed from the RunRev.com forums. Although it worked, it's currently disabled on the server, because it was a bit of a hack, and never really worked unobtrusively for the user, and wasn't updating often enough without taxing the runrev.com http server too much.