diff --git a/doc/protocol.txt b/doc/protocol.txt new file mode 100644 index 0000000..bcc0f5a --- /dev/null +++ b/doc/protocol.txt @@ -0,0 +1,59 @@ +Terms +===== + +Parts between < and > are mandatory. They will never contain white space and +thus can be mentioned as words. + +Parts between [ and ] are optional. It can be one word, several words, or even +missing. + +White space can be a space or Tab character. New line and carriage return are +not considered as white space. + + is a message ID. It can contain alphanumeric characters (must match the +regular expression [a-zA-Z0-9]+), except for server messages which are not +generated in response to a client request, which begins with a dot (.). + + is similar to HTTP Status codes. The first digit depends on +the generator module. 0 is for the messages generated by RPGServ core; 1 is +for messages generated by RPG System modules. Other numbers are currently +reserved for future use. The second digit is the message level: 0 are +informational, or success messages; 1 are warnings, which are recoverable, +while 2 is for errors. 3 indicates server-side system failure, and is always +followed by a disconnect. 8-9 are two-level debug messages. 4-7 are currently +reserved for future use. + +Client side +=========== + + [ARGUMENTS] + +MESSAGE SIZE contains the length of the whole message. Although white space +characters are ignored during message parsing, MESSAGE SIZE must include the +length of these characters, either. + +COMMAND is the command itself. + +ARGUMENTS are the (optional) command arguments. Arguments are case sensitive. +Each word in ARGUMENTS is a separate argument, white space and newline is +ignored between them, except the argument is wrapped between two " or ' +characters. These two have identical meaning, but can not be swapped. To put a +plain wrapper character in a wrapped text, prefix it with a backslash. + +Server side +=========== + + + +PIECE-NR is the packet number for the given message. Every message is divided +into packets based on the server side settings. Messages that fit in one +packet are sent with this field set to 0. Longer messages, or messages that +are generated over time and pieces can be sent meanwhile are numbered from 1. +The last piece of message for a given MID is always marked as LAST in the +PIECE-NR field. + +PIECE-SIZE is the size of the current piece in bytes. + +MESSAGE-CHUNK contains the message itself, or the chunk transmitted in this +packet. The message or message chunk doesn't have a trailing character, like a +newline.