This file is indexed.

/usr/include/libkdegamesprivate/kgame/kmessageclient.h is in libkdegames-dev 4:4.13.0-0ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
/*
    This file is part of the KDE games library
    Copyright (C) 2001 Burkhard Lehner (Burkhard.Lehner@gmx.de)

    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.
*/

#ifndef __KMESSAGECLIENT_H__
#define __KMESSAGECLIENT_H__

#include <QtCore/QObject>
#include <QtCore/QString>

#include "../libkdegamesprivate_export.h"
class KMessageIO;
class KMessageServer;
class KMessageClientPrivate;

/**
  \class KMessageClient kmessageclient.h <KGame/KMessageClient>
  
  @short A client to connect to a KMessageServer

  This class implements a client that can connect to a KMessageServer object.
  It can be used to exchange messages between clients.

  Usually you will connect the signals broadcastReceived and forwardReceived to
  some specific slots. In these slot methods you can analyze the messages that are
  sent to you from other clients.

  To send messages to other clients, use the methods sendBroadcast() (to send to all
  clients) or sendForward() (to send to a list of selected clients).

  If you want to communicate with the KMessageServer object directly (on a more low
  level base), use the method sendServerMessage to send a command to the server and
  connect to the signal serverMessageReceived to see all the incoming messages.
  In that case the messages must be of the format specified in KMessageServer.
  @author Burkhard Lehner <Burkhard.Lehner@gmx.de>
*/
class KDEGAMESPRIVATE_EXPORT KMessageClient : public QObject
{
  Q_OBJECT

public:

  /**
    Constructor.
    Creates an unconnected KMessageClient object. Use setServer() later to connect to a
    KMessageServer object.
  */
  KMessageClient (QObject *parent = 0);

  /**
    Destructor.
    Disconnects from the server, if any connection was established.
  */
  ~KMessageClient ();

  /**
    @return The client ID of this client. Every client that is connected to a KMessageServer
    has a unique ID number.

    NOTE: As long as the object is not yet connected to the server, and as long as the server
    hasn't sent the client ID, this method returns 0.
  */
  quint32 id () const;

  /**
    @return Whether or not this client is the server admin.
    One of the clients connected to the server is the admin and can administrate the server
    (set maximum number of clients, remove clients, ...).

    If you use admin commands without being the admin, these commands are simply ignored by
    the server.

    NOTE: As long as you are not connected to a server, this method returns false.
  */
  bool isAdmin () const;

  /**
    @return The ID of the admin client on the message server.
  */
  quint32 adminId() const;

  /**
    @return The list of the IDs of all the message clients connected to the message server.
  */
  QList <quint32> clientList() const;

  /**
    Connects the client to (another) server.

    Tries to connect via a TCP/IP socket to a KMessageServer object
    on the given host, listening on the specified port.

    If we were already connected, the old connection is closed.
    @param host The name of the host to connect to. Must be either a hostname which can 
    be resolved to an IP or just an IP
    @param port The port to connect to
  */
  void setServer (const QString &host, quint16 port);

  /**
    Connects the client to (another) server.

    Connects to the given server, using KMessageDirect.
    (The server object has to be in the same process.)

    If we were already connected, the old connection is closed.
    @param server The KMessageServer to connect to
  */
  void setServer (KMessageServer *server);

  /**
   * Corresponds to setServer(0); but also emits the connectionBroken signal
   **/
  void disconnect();

  /**
    Connects the client to (another) server.

    To use this method, you have to create a KMessageIO object with new (indeed you must
    create an instance of a subclass of KMessageIO, e.g. KMessageSocket or KMessageDirect).
    This object must already be connected to the new server.

    Calling this method disconnects any earlier connection, and uses the new KMessageIO
    object instead. This object gets owned by the KMessageClient object, so don't delete
    or manipulate it afterwards.

    With this method it is possible to change the server on the fly. But be careful that
    there are no important messages from the old server not yet delivered.

    NOTE: It is very likely that we will have another client ID on the new server. The
    value returned by clientID may be a little outdated until the new server tells us
    our new ID.

    NOTE: The two other setServer methods are for convenience. If you use them, you don't
    have to create a KMessageIO object yourself.
  */
  virtual void setServer (KMessageIO *connection);

  /**
    @return True, if a connection to a KMessageServer has been started, and if the
    connection is ready for transferring data. (It will return false e.g. as long as
    a socket connection hasn't been established, and it will also return false after
    a socket connection is broken.)
  */
  bool isConnected () const;

  /**
    @return TRUE if isConnected() is true AND this is not a local (like
    KMessageDirect) connection.
  */
  bool isNetwork () const;

  /**
    @return 0 if isConnected() is FALSE, otherwise the port number this client is
    connected to. See also KMessageIO::peerPort and QSocket::peerPort.
  */
  quint16 peerPort () const;

  /**
    @return "localhost" if isConnected() is FALSE, otherwise the hostname this client is
    connected to. See also KMessageIO::peerName() and QSocket::peerName().
  */
  QString peerName() const;

  /**
    Sends a message to the KMessageServer. If we are not yet connected to one, nothing
    happens.

    Use this method to send a low level command to the server. It has to be in the
    format specified in KMessageServer.

    If you want to send messages to other clients, you should use sendBroadcast()
    and sendForward().
    @param msg The message to be sent to the server. Must be in the format specified in KMessageServer.
  */
  void sendServerMessage (const QByteArray &msg);

  /**
    Sends a message to all the clients connected to the server, including ourself.
    The message consists of an arbitrary block of data with arbitrary length.

    All the clients will receive an exact copy of this block of data, which will be
    processed in their processBroadcast() method.
    @param msg The message to be sent to the clients
  */
  //AB: processBroadcast doesn't exist!! is processIncomingMessage meant?
  void sendBroadcast (const QByteArray &msg);

  /**
    Sends a message to all the clients in a list.
    The message consists of an arbitrary block of data with arbitrary length.

    All clients will receive an exact copy of this block of data, which will be
    processed in their processForward() method.

    If the list contains client IDs that are not defined, they are ignored. If
    it contains an ID several times, that client will receive the message several
    times.

    To send a message to the admin of the KMessageServer, you can use 0 as clientID,
    instead of using the real client ID.
    @param msg The message to be sent to the clients
    @param clients A list of clients the message should be sent to
  */
  //AB: processForward doesn't exist!! is processIncomingMessage meant?
  void sendForward (const QByteArray &msg, const QList <quint32> &clients);

  /**
    Sends a message to a single client. This is a convenieance method. It calls
    sendForward (const QByteArray &msg, const QValueList &ltquint32> &clients)
    with a list containing only one client ID.

    To send a message to the admin of the  KMessageServer, you can use 0 as clientID,
    instead of using the real client ID.
    @param msg The message to be sent to the client
    @param client The id of the client the message shall be sent to
  */
  void sendForward (const QByteArray &msg, quint32 client);

  /**
    Once this function is called no message will be received anymore.
    processIncomingMessage() gets delayed until unlock() is called.

    Note that all messages are still received, but their delivery (like
    broadcastReceived()) get delayed only.
   */
  void lock();

  /**
    Deliver every message that was delayed by lock() and actually deliver 
    all messages that get received from now on.
   */
  void unlock();

  /**
    @return The number of messages that got delayed since lock() was called
   */
  unsigned int delayedMessageCount() const;

Q_SIGNALS:
  /**
    This signal is emitted when the client receives a broadcast message from the
    KMessageServer, sent by another client. Connect to this signal to analyze the
    received message and do the right reaction.

    senderID contains the ID of the client that sent the broadcast message. You can
    use this e.g. to send a reply message to only that client. Or you can use it
    to ignore broadcast messages that were sent by yourself:

    \code
      void myObject::myBroadcastSlot (const QByteArray &msg, quint32 senderID)
      {
        if (senderID == ((KMessageClient *)sender())->id())
          return;
        ...
      }
    \endcode
    @param msg The message that has been sent to us
    @param senderID The ID of the client which sent the message
  */
  void broadcastReceived (const QByteArray &msg, quint32 senderID);

  /**
    This signal is emitted when the client receives a forward message from the
    KMessageServer, sent by another client. Connect to this signal to analyze the
    received message and do the right reaction.

    senderID contains the ID of the client that sent the broadcast message. You can
    use this e.g. to send a reply message to only that client.

    receivers contains the list of the clients that got the message. (If this list
    only contains one number, this will be your client ID, and it was exclusivly
    sent to you.)

    If you don't want to distinguish between broadcast and forward messages and
    treat them the same, you can connect forwardReceived signal to the
    broadcastReceived signal. (Yes, that's possible! You can connect a Qt signal to
    a Qt signal, and the second one can have less parameters.)

    \code
      KMessageClient *client = new KMessageClient ();
      connect (client, SIGNAL (forwardReceived (const QByteArray &, quint32, const QValueList <quint32>&)),
               client, SIGNAL (broadcastReceived (const QByteArray &, quint32)));
    \endcode

    Then connect the broadcast signal to your slot that analyzes the message.
    @param msg The message that has been sent to us
    @param senderID The ID of the client which sent the message
    @param receivers All clients which receive this message
  */
  void forwardReceived (const QByteArray &msg, quint32 senderID, const QList <quint32> &receivers);

  /**
    This signal is emitted when the connection to the KMessageServer is broken.
    Reasons for this can be: a network error, a server breakdown, or you were just kicked
    from the server.

    When this signal is sent, the connection is already lost and the client is unconnected.
    You can connect to another server by calling setServer() afterwards. But keep in mind that
    some important messages might have vanished.
  */
  void connectionBroken ();

  /**
    This signal is emitted right before the client disconnects. It can be used
    to this store the id of the client which is about to be lost.
  */
  void aboutToDisconnect(quint32 id);

  /**
    This signal is emitted when this client becomes the admin client or when it loses
    the admin client status. Connect to this signal if you have to do any initialization
    or cleanup.
    @param isAdmin Whether we are now admin or not
  */
  void adminStatusChanged (bool isAdmin);

  /**
    This signal is emitted when another client has connected
    to the server. Connect to this method if that clients needs initialization.
    This should usually only be done in one client, e.g. the admin client.
    @param clientID The ID of the client that has newly connectd.
  */
  void eventClientConnected (quint32 clientID);

  /**
    This signal is emitted when the server has lost the
    connection to one of the clients (This could be because of a bad internet connection
    or because the client disconnected on purpose).
    @param clientID The ID of the client that has disconnected
    @param broken true if it was disconnected because of a network error
  */
  void eventClientDisconnected (quint32 clientID, bool broken);

  /**
    This signal is emitted on every message that came from the server. You can connect to this
    signal to see the messages directly. They are in the format specified in KMessageServer.

    @param msg The message that has been sent to us
    @param unknown True when KMessageClient didn't recognize the message, i.e. it contained an unknown
    message ID. If you want to add additional message types to the client, connect to this signal,
    and if unknown is true, analyze the message by yourself. If you recognized the message,
    set unknown to false (Otherwise a debug message will be printed).
  */
  //AB: maybe add a setNoEmit() so that the other signals can be deactivated?
  //Could be a performance benefit (note: KMessageClient is a time critical
  //class!!!)
  void serverMessageReceived (const QByteArray &msg, bool &unknown);

protected:
  /**
    This slot is called from processIncomingMessage or 
    processFirstMessage, depending on whether the client is locked or a delayed
    message is still here (see lock)

    It processes the message and analyzes it. If it is a broadcast or a forward message from
    another client, it emits the signal processBroadcast or processForward accordingly.

    If you want to treat additional server messages, you can overwrite this method. Don't
    forget to call processIncomingMessage of your superclass!

    At the moment, the following server messages are interpreted:

    MSG_BROADCAST, MSG_FORWARD, ANS_CLIENT_ID, ANS_ADMIN_ID, ANS_CLIENT_LIST
    @param msg The incoming message
  */

  virtual void processMessage (const QByteArray& msg);

protected Q_SLOTS:
  /**
    This slot is called from the signal KMessageIO::received whenever a message from the
    KMessageServer arrives.

    It processes the message and analyzes it. If it is a broadcast or a forward message from
    another client, it emits the signal processBroadcast or processForward accordingly.

    If you want to treat additional server messages, you can overwrite this method. Don't
    forget to call processIncomingMessage() of your superclass!

    At the moment, the following server messages are interpreted:

    MSG_BROADCAST, MSG_FORWARD, ANS_CLIENT_ID, ANS_ADMIN_ID, ANS_CLIENT_LIST
    @param msg The incoming message
  */
  virtual void processIncomingMessage (const QByteArray &msg);

  /**
    Called from unlock() (using QTimer::singleShot) until all delayed 
    messages are delivered.
  */
  void processFirstMessage();

  /**
    This slot is called from the signal KMessageIO::connectionBroken.

    It deletes the internal KMessageIO object, and resets the client to default
    values. To connect again to another server, use setServer.
  */
  virtual void removeBrokenConnection ();
  void removeBrokenConnection2 ();

private:
  KMessageClientPrivate * const d;
};

#endif