1 /*
2     This file is part of the KDE games library
3     SPDX-FileCopyrightText: 2001 Martin Heni <kde at heni-online.de>
4     SPDX-FileCopyrightText: 2001 Andreas Beckermann <b_mann@gmx.de>
5 
6     SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef __KGAMEMESSAGE_H_
10 #define __KGAMEMESSAGE_H_
11 
12 // own
13 #include "libkdegamesprivate_export.h"
14 // Qt
15 #include <QDataStream>
16 
17 /**
18  * \class KGameMessage kgamemessage.h <KGame/KGameMessage>
19  */
20 class KDEGAMESPRIVATE_EXPORT KGameMessage
21 {
22   public:
23     /**
24      * Creates a fully qualified player ID which contains the original
25      * player id in the lower bits and the game number in the higher bits.
26      * Do not rely on the exact bit positions as they are internal.
27      *
28      * See also @ref rawPlayerId and @ref rawGameId which are the inverse
29      * operations
30      *
31      * @param player The player id - can include a gameid (will get removed)
32      * @param game The game id (<64). 0 For broadcast.
33      * @return The new player id
34      */
35     static quint32 createPlayerId(int player, quint32 game);
36 
37     /**
38      * Returns the raw playerid, that is, a id which does not
39      * contain the game number encoded in it. See also @ref createPlayerId which
40      * is the inverse operation.
41      *
42      * @param playerid The player id
43      * @return The raw player id
44      **/
45     static int rawPlayerId(quint32 playerid);
46 
47     /**
48      * Returns the raw game id, that is, the game id the player
49      * belongs to. Se also @ref createPlayerId which is the inverse operation.
50      *
51      * @param playerid The player id
52      * @return The raw game id
53      **/
54     static quint32 rawGameId(quint32 playerid);
55 
56     /**
57      * Checks whether a message receiver/sender is a player
58      *
59      * @param id The ID of the sender/receiver
60      * @return true/false
61      */
62     static bool isPlayer(quint32 id);
63 
64     /**
65      * Checks whether the sender/receiver of a message is a game
66      *
67      * @param id The ID of the sender/receiver
68      * @return true/false
69      */
70     static bool isGame(quint32 id);
71 
72     /**
73      * Creates a message header given cookie,sender,receiver,...
74      *
75      * Also puts "hidden" header into the stream which are used by KGameClient
76      * (message length and magic cookie). If you don't need them remove them
77      * with dropExternalHeader
78      */
79     static void createHeader(QDataStream &msg, quint32 sender, quint32 receiver, int msgid);
80 
81     /**
82      * Retrieves the information like cookie,sender,receiver,... from a message header
83      *
84      * Note that it could be necessary to call dropExternalHeader first
85      */
86     static void extractHeader(QDataStream &msg,quint32 &sender, quint32 &receiver, int &msgid);
87 
88     /**
89      * Creates a property header  given the property id
90      */
91     static void createPropertyHeader(QDataStream &msg, int id);
92 
93     /**
94      * Retrieves the property id from a property message header
95      */
96     static void extractPropertyHeader(QDataStream &msg, int &id);
97 
98     /**
99      * Creates a property header given the property id
100      */
101     static void createPropertyCommand(QDataStream &msg, int cmdid, int pid, int cmd);
102 
103     /**
104      * Retrieves the property id from a property message header
105      */
106     static void extractPropertyCommand(QDataStream &msg, int &pid, int &cmd);
107 
108     /**
109      * @return Version of the network library
110      */
111     static int version();
112 
113     /**
114      * This function takes a @ref GameMessageIds as argument and returns a
115      * suitable string for it. This string can't be used to identify a message
116      * (as it is i18n'ed) but it can make debugging more easy.
117      * @return Either a i18n'ed string (the name of the id) or QString() if
118      * the msgid is unknown
119      **/
120     static QString messageId2Text(int msgid);
121 
122 
123   /**
124    * Message Ids used inside @ref KGame.
125    *
126    * You can use your own custom message Id by adding @p IdUser to it.
127    **/
128 // please document every new id with a short comment
129   enum GameMessageIds {
130 // game init, game load, disconnect, ...
131     IdSetupGame=1,         // sent to a newly connected player
132     IdSetupGameContinue=2, // continue the setup
133     IdGameLoad=3,          // load/save the game to the client
134     IdGameConnected=4,     // Client successfully connected to master
135     IdSyncRandom=5,        // new random seed set - sync games
136     IdDisconnect=6,        // KGame object disconnects from game
137     IdGameSetupDone=7,     // New game client is now operational
138 
139 // properties
140     IdPlayerProperty=20,   // a player property changed
141     IdGameProperty=21,     // a game property changed
142 
143 // player management
144     IdAddPlayer=30,         // add a player
145     IdRemovePlayer=31,      // the player will be removed
146     IdActivatePlayer=32,    // Activate a player
147     IdInactivatePlayer=33,  // Inactivate a player
148     IdTurn=34,              // Turn to be prepared
149 
150 // to-be-categorized
151     IdError=100,            // an error occurred
152     IdPlayerInput=101,      // a player input occurred
153     IdIOAdded=102,          // KGameIO got added to a player...init this IO
154 
155 // special ids for computer player
156     IdProcessQuery=220,     // Process queries data (process only)
157     IdPlayerId=221,         // PlayerId got changed (process only)
158 
159     IdUser=256          // a user specified message
160   };
161 };
162 
163 #endif
164