[mw-devel] MW3 r1392 - trunk/src/server

[arthur at sucs.org]

Author: arthur
Date: 2015-09-24 10:28:17 +0100 (Thu, 24 Sep 2015)
New Revision: 1392

Added:
   trunk/src/server/PROTOCOL
Log:
Attempt to document the client-server protocol


Added: trunk/src/server/PROTOCOL
===================================================================
--- trunk/src/server/PROTOCOL	                        (rev 0)
+++ trunk/src/server/PROTOCOL	2015-09-24 09:28:17 UTC (rev 1392)
@@ -0,0 +1,89 @@
+Milliways client-to-server protocol definition
+==============================================
+
+Every message sent has the following header :
+
+/* from socket.h */
+struct {
+        uint32_t src;           // sending userid
+        uint32_t dst;           // destination user/room
+        uint32_t type;          // message type, ipc.h
+        uint32_t len;           // bytes of body
+        uint64_t serial;        // sequence number
+         int64_t when;          // unixtime of sending
+} ipc_msghead_t;
+
+Followed by a body depending on type.
+
+IPC_* numbered items are old format, raw text or instructions.
+IPC_* codes using FCC are json formatted messages.
+
+IPC_HELLO - Login to the server, start a session
+	Body: (binary)
+		userid - 4 bytes - offset in users db 
+		nonce - to end - unique version string for server
+	Response:
+		none
+IPC_UPTIME - Enquire how long the server has been up
+	Body: 
+		none
+	Response: (json)
+		uptime - time in seconds
+		version - server version string
+		
+IPC_SAYTOROOM - user said something to the room
+	Header:
+		dest is room to send to
+	Body: (json)
+		exclude - username to not send to
+		type - sub-type of message
+			say - normal talking
+			raw - use of .raw command
+			emote - use of .emote command
+			notsayto - .notsayto command
+			says - .say command
+			whispers - .whi command
+		plural - sub-type of emote
+			1 - emote's
+			2 - emote'
+			3 - emote'd
+			4 - emote'll
+		text - what was actually said
+	Response:
+		none
+
+IPC_SAYTOUSER - send text to one specific person
+	Header:
+		dest is ignored
+	Body: (json)
+		target - username of person it is for
+		same as IPC_SAYTOROOM 
+	Response:
+		error if target is not logged in
+
+IPC_SAYTOALL - send text to every user 
+	Header:
+		dest is ignored
+
+IPC_TALKERROR - an error response (usually from server)
+	Header:
+		dest - PID / session id of offender
+	Body: (json)
+		type - type of original message that caused error
+		text - error message
+	Response:
+		this is the response
+
+IPC_REPLAY - request retransmission of past messages
+	Header:
+		dest ignored
+	Body: (json)
+		In order of preference:-
+		serial - show all AFTER this sequence number
+		since - unixtime to show since	
+		count - now the last $n messages	
+	Response:
+		you will get all of the relevant messages sent again
+
+all other codes are old unformatted messages and are to be phased out,
+most commonly used is IPC_TEXT which is raw text to be displayed