Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegames@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 93 insertions, 0 deletions

diff --git a/libkdegames/kgame/messages.txt b/libkdegames/kgame/messages.txt
new file mode 100644
index 00000000..151196d5
--- /dev/null
+++ b/libkdegames/kgame/messages.txt
@@ -0,0 +1,93 @@
+Message formats of libkdegames:
+-------------------------------
+
+There are two different communication layers, using their own protocols:
+
+ - the message layer (KMessageIO, KMessageServer, KMessageClient)
+
+     This is used to send messages from one client (i.e. KGame object)
+     to an other one, to a group of other clients, or to all the clients
+     connected to the KMessageServer. The messages are arbitrary blocks
+     of data, of an arbitrary length.
+     This layer is an underlying protocol that isn't game specific at all.
+     You shouldn't need to know the message format of the packets. If you
+     want to extend the protocol, have a look into KMessageServer API
+     reference for a complete list of message types.
+
+ - the game layer (KGame, KGameIO, KPlayer)
+
+     This layer uses the message layer to send its specific message packets
+     between the objects of the game.
+     This layer contains the game specific messages (e.g. addPlayer, setupGame).
+     The rest of this file describes this layer.
+
+
+Game Layer Messages:
+--------------------
+
+     Application Cookie   16 Bit
+     Version               8 Bit
+     MsgId                16 Bit
+     SenderId             16 Bit
+     ReceiverId           16 Bit
+     Userdata
+
+The format of the messages is used internally and there is usually no reason why
+you have to know what it is used for. But as usually != always here are some
+comments on the format. Note that KGame is under development and the content of
+this file could be obsolete. Please result the sourcecode for up-to-date
+information.
+Application Cookie is used to identify the application. This prevents a
+chess game from talking to a poker game.
+Version is the version of KNetworkGame, sender and receiver must be of the same
+version.
+  library note: this could be a limitation, as KGame should be backward
+  compatible. Maybe change to version must be >= KNETWORKGAME or something less
+  restrictive
+MsgId specifies the kind of the message data (see below).
+SenderId is the id of the KGame/KPlayer object which sent the message, it is
+coded like this: the lower 10 bits specify a player and the upper bit
+represent the game id shifted by 10 bits. So we get
+Id=playerId | (gameId<<10);
+ReceiverId is the id of the receiver of the message. It can be either
+a player, a game or a broadcast. For a broadcast the Id is set to 0
+in the other cases the coding is as with the senderId
+Userdata is the data of the user (wow ;-))
+
+
+MsgId           UserData
+---------------------------------------------------------
+IdMessage        user defined
+
+IdSetupGame      Q_INT32  isServer
+                 Q_INT32  maxPlayers
+                 Q_INT32  newid (id for the new game)
+                 Q_INT32  cntR (virtual player nunmber)
+                 Q_INT32  cntT (tagged player number)
+                 TODO: Changed
+
+IdContinueSetup: TODO
+
+IdSendPlayer     Q_INT32  omit how many tagged players for replacement
+                 TODO: Changed
+
+IdGameSave       Save(msg)->Load(msg)
+
+IdAddPlayer      rtti
+                 gameid() of the owner
+		 player->Save(msg) -> player->Load(msg)
+
+IdRemovePlayer   Q_INT16  playerid
+
+IdError          Q_INT32  errorcode
+                 QString  errortext
+
+IdGameStatus     Q_INT32  status
+
+IdPlayerProperty Q_INT16  propertyId
+                 user defined -> the property
+
+IdGameProperty   Q_INT16  propertyId
+                 user defined -> the property
+
+IdPlayerInput    user defined