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, 173 insertions, 0 deletions

diff --git a/libkdegames/kgame/kgamemessage.h b/libkdegames/kgame/kgamemessage.h
new file mode 100644
index 00000000..4394b4fa
--- /dev/null
+++ b/libkdegames/kgame/kgamemessage.h
@@ -0,0 +1,173 @@
+/*
+    This file is part of the KDE games library
+    Copyright (C) 2001 Martin Heni ([email protected])
+    Copyright (C) 2001 Andreas Beckermann ([email protected])
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License version 2 as published by the Free Software Foundation.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+*/
+/*
+    $Id$
+*/
+#ifndef __KGAMEMSG_H_
+#define __KGAMEMSG_H_
+
+#include <qdatastream.h>
+#include <kdemacros.h>
+
+class KDE_EXPORT KGameMessage
+{
+  public:
+    /**
+     * Creates a fully qualified player ID which contains the original
+     * player id in the lower bits and the game number in the higher bits.
+     * Do not rely on the exact bit positions as they are internal.
+     *
+     * See also @ref rawPlayerId and @ref rawGameId which are the inverse
+     * operations
+     *
+     * @param playerid the player id - can include a gameid (will get removed)
+     * @param gameid The game id (<64). 0 For broadcast.
+     * @return the new player id
+     */
+    static Q_UINT32 createPlayerId(int player, Q_UINT32 game);
+
+    /**
+     * Returns the raw playerid, that is, a id which does not
+     * contain the game number encoded in it. See also @ref createPlayerId which
+     * is the inverse operation.
+     *
+     * @param the player id
+     * @return the raw player id
+     **/
+    static int rawPlayerId(Q_UINT32 playerid);
+
+    /**
+     * Returns the raw game id, that is, the game id the player
+     * belongs to. Se also @ref createPlayerId which is the inverse operation.
+     *
+     * @param the player id
+     * @return the raw game id
+     **/
+    static Q_UINT32 rawGameId(Q_UINT32 playerid);
+
+    /**
+     * Checks whether a message receiver/sender is a player
+     *
+     * @param id The ID of the sender/receiver
+     * @return true/false
+     */
+    static bool isPlayer(Q_UINT32 id);
+
+    /**
+     * Checks whether the sender/receiver of a message is a game
+     *
+     * @param id The ID of the sender/receiver
+     * @return true/false
+     */
+    static bool isGame(Q_UINT32 id);
+
+    /**
+     * Creates a message header given cookie,sender,receiver,...
+     *
+     * Also puts "hidden" header into the stream which are used by KGameClient
+     * (message length and magic cookie). If you don't need them remove them
+     * with @ref dropExternalHeader
+     */
+    static void createHeader(QDataStream &msg, Q_UINT32 sender, Q_UINT32 receiver, int msgid);
+
+    /**
+     * Retrieves the information like cookie,sender,receiver,... from a message header 
+     *
+     * Note that it could be necessary to call @ref dropExternalHeader first
+     */
+    static void extractHeader(QDataStream &msg,Q_UINT32 &sender, Q_UINT32 &receiver, int &msgid);
+
+    /**
+     * Creates a property header  given the property id
+     */
+    static void createPropertyHeader(QDataStream &msg, int id);
+
+    /**
+     * Retrieves the property id from a property message header
+     */
+    static void extractPropertyHeader(QDataStream &msg, int &id);
+
+    /**
+     * Creates a property header given the property id
+     */
+    static void createPropertyCommand(QDataStream &msg, int cmdid, int pid, int cmd);
+
+    /**
+     * Retrieves the property id from a property message header
+     */
+    static void extractPropertyCommand(QDataStream &msg, int &pid, int &cmd);
+
+    /**
+     * @return Version of the network library
+     */
+    static int version();
+
+    /**
+     * This function takes a @ref GameMessageIds as argument and returns a
+     * suitable string for it. This string can't be used to identify a message
+     * (as it is i18n'ed) but it can make debugging more easy. See also @ref
+     * KGameDebugDialog.
+     * @return Either a i18n'ed string (the name of the id) or QString::null if
+     * the msgid is unknown
+     **/
+    static QString messageId2Text(int msgid);
+
+
+  /**
+   * Message Ids used inside @ref KGame.
+   *
+   * You can use your own custom message Id by adding @p IdUser to it.
+   **/
+// please document every new id with a short comment
+  enum GameMessageIds {
+// game init, game load, disconnect, ...
+    IdSetupGame=1,         // sent to a newly connected player
+    IdSetupGameContinue=2, // continue the setup
+    IdGameLoad=3,          // load/save the game to the client
+    IdGameConnected=4,     // Client successfully connected to master
+    IdSyncRandom=5,        // new random seed set - sync games
+    IdDisconnect=6,        // KGame object disconnects from game
+    IdGameSetupDone=7,     // New game client is now operational
+
+// properties
+    IdPlayerProperty=20,   // a player property changed
+    IdGameProperty=21,     // a game property changed
+
+// player management
+    IdAddPlayer=30,         // add a player
+    IdRemovePlayer=31,      // the player will be removed
+    IdActivatePlayer=32,    // Activate a player
+    IdInactivatePlayer=33,  // Inactivate a player
+    IdTurn=34,              // Turn to be prepared
+
+// to-be-categorized
+    IdError=100,            // an error occurred
+    IdPlayerInput=101,      // a player input occurred
+    IdIOAdded=102,          // KGameIO got added to a player...init this IO
+
+// special ids for computer player
+    IdProcessQuery=220,     // Process queries data (process only)
+    IdPlayerId=221,         // PlayerId got changed (process only)
+
+    IdUser=256          // a user specified message
+  };
+};
+
+#endif