File indexing completed on 2024-06-23 04:04:19

 /*
     This file is part of the KDE games library
     SPDX-FileCopyrightText: 2001 Martin Heni <kde at heni-online.de>
     SPDX-FileCopyrightText: 2001 Andreas Beckermann <b_mann@gmx.de>
 
     SPDX-License-Identifier: LGPL-2.0-only
 */
 
 #ifndef __KGAMENETWORK_H_
 #define __KGAMENETWORK_H_
 
 // own
 #include "kdegamesprivate_export.h"
 // Qt
 #include <QObject>
 #include <QString>
 // Std
 #include <memory>
 
 class KGameIO;
 class KMessageIO;
 class KMessageClient;
 class KMessageServer;
 
 class KGameNetworkPrivate;
 
 /**
  * \class KGameNetwork kgamenetwork.h <KGame/KGameNetwork>
  *
  * The KGameNetwork class is the KGame class with network
  * support. All other features are the same but they are
  * now network transparent. It is not used directly but
  * only via a KGame object. So you do not really have
  * to bother with this object.
  *
  * @short The main KDE game object
  */
 class KDEGAMESPRIVATE_EXPORT KGameNetwork : public QObject
 {
     Q_OBJECT
 
 public:
     /**
      * Create a KGameNetwork object
      */
     explicit KGameNetwork(int cookie = 42, QObject *parent = nullptr);
     ~KGameNetwork() override;
 
     /**
      * Gives debug output of the game status
      */
     virtual void Debug();
 
     /**
      * @return TRUE if this is a network game - i.e. you are either MASTER or
      * connected to a remote MASTER.
      */
     bool isNetwork() const;
 
     /**
      * Is this the game MASTER (i.e. has started theKMessageServer). A
      * game has always exactly one MASTER. This is either a KGame object (i.e. a
      * Client) or an own MessageServer-process. A KGame object that has the
      * MASTER status is always admin.
      *
      * You probably don't want to use this. It is a mostly internal method which
      * will probably become protected. Better use isAdmin
      *
      * @see isAdmin
      * @return Whether this client has started the KMessageServer
      */
     bool isMaster() const;
 
     /**
      * The admin of a game is the one who initializes newly connected clients
      * using  negotiateNetworkGame and is allowed to configure the game.
      * E.g. only the admin is allowed to use KGame::setMaxPlayers.
      *
      * If one KGame object in the game is MASTER then this client is the admin
      * as well. isMaster and isAdmin differ only if the KMessageServer
      * is running in an own process.
      * @return Whether this client (KGame object) is the admin
      */
     bool isAdmin() const;
 
     /**
      * The unique ID of this game
      *
      * @return int id
      */
     quint32 gameId() const;
 
     /**
      * Inits a network game as network MASTER. Note that if the
      * KMessageServer is not yet started it will be started here (see
      * setMaster). Any existing connection will be disconnected.
      *
      * If you already offer connections the port is changed.
      *
      * @param port The port on which the service is offered
      * @return true if it worked
      */
     bool offerConnections(quint16 port);
 
     void setDiscoveryInfo(const QString &type, const QString &name = QString());
 
     /**
      * Inits a network game as a network CLIENT
      *
      * @param host the host to which we want to connect
      * @param port the port we want to connect to
      *
      * @return true if connected
      */
     bool connectToServer(const QString &host, quint16 port);
     bool connectToServer(KMessageIO *connection);
 
     /**
      * @return The port we are listening to if offerConnections was called
      * or the port we are connected to if connectToServer was called.
      * Otherwise 0.
      */
     quint16 port() const;
 
     /**
      * @return The name of the host that we are currently connected to is
      * isNetwork is TRUE and we are not the MASTER, i.e. if connectToServer
      * was called. Otherwise this will return "localhost".
      */
     QString hostName() const;
 
     /**
      * Stops offering server connections - only for game MASTER
      * @return true
      */
     bool stopServerConnection();
 
     /**
      * Changes the maximal connection number of the KMessageServer to max.
      * -1 Means infinite connections are possible. Note that existing
      * connections are not affected, so even if you set this to 0 in a running
      * game no client is being disconnected. You can call this only if you are
      * the ADMIN!
      *
      * @see KMessageServer::setMaxClients
      * @param max The maximal number of connections possible.
      */
     void setMaxClients(int max);
 
     // AB: is this now internal only? Can we make it protected (maybe with
     // friends)? sendSystemMessage AND sendMessage is very confusing to the
     // user.
     /**
      * Sends a network message msg with a given msg id msgid to all clients.
      * Use this to communicate with KGame (e.g. to add a player ot to configure
      * the game - usually not necessary).
      *
      * For your own messages use  sendMessage instead! This is mostly
      * internal!
      *
      * @param buffer the message which will be send. See messages.txt for contents
      * @param msgid an id for this message. See
      * KGameMessage::GameMessageIds
      * @param receiver the KGame / KPlayer this message is for.
      * @param sender The KGame / KPlayer this message is from (i.e.
      * you). You
      * probably want to leave this 0, then KGameNetwork will create the correct
      * value for you. You might want to use this if you send a message from a
      * specific player.
      * @return true if worked
      */
     // AB: TODO: doc on how "receiver" and "sender" should be created!
     bool sendSystemMessage(const QByteArray &buffer, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * @overload
      */
     bool sendSystemMessage(int data, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * @overload
      */
     bool sendSystemMessage(const QDataStream &msg, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * @overload
      */
     bool sendSystemMessage(const QString &msg, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * Sends a network message
      * @param error The error code
      * @param message The error message - use KGameError
      * @param receiver the KGame / KPlayer this message is for. 0 For
      * all
      * @param sender The KGame / KPlayer this message is from (i.e.
      * you). You probably want to leave this 0, then KGameNetwork will create
      * the correct value for you. You might want to use this if you send a
      * message from a specific player.
      */
     void sendError(int error, const QByteArray &message, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * Are we still offer offering server connections - only for game MASTER
      * @return true/false
      */
     bool isOfferingConnections() const;
 
     /**
      * Application cookie. this identifies the game application. It
      * help to distinguish between e.g. KPoker and KWin4
      * @return the application cookie
      */
     int cookie() const;
 
     /**
      * Send a network message msg with a given message ID msgid to all clients.
      * You want to use this to send a message to the clients.
      *
      * Note that a message is always sent to ALL clients! This is necessary so
      * that all clients always have the same data and can easily be changed from
      * network to non-network without restarting the game. If you want a
      * specific KGame / KPlayer to react to the message use the
      * receiver and sender parameters. See KGameMessage::calsMessageId
      *
      * SendMessage differs from sendSystemMessage only by the msgid parameter.
      * sendSystemMessage is thought as a KGame only method while
      * sendMessage is for public use. The msgid parameter will be
      * +=KGameMessage::IdUser and in KGame::signalNetworkData msgid will
      * be -= KGameMessage::IdUser again, so that one can easily distinguish
      * between system and user messages.
      *
      * Use sendSystemMessage to communicate with KGame (e.g. by adding a
      * player) and sendMessage for your own user message.
      *
      * Note: a player should send messages through a KGameIO!
      *
      * @param buffer the message which will be send. See messages.txt for contents
      * @param msgid an id for this message. See KGameMessage::GameMessageIds
      * @param receiver the KGame / KPlayer this message is for.
      * @param sender The KGame / KPlayer this message is from (i.e.
      * you). You
      * probably want to leave this 0, then KGameNetwork will create the correct
      * value for you. You might want to use this if you send a message from a
      * specific player.
      * @return true if worked
      */
     // AB: TODO: doc on how "receiver" and "sender" should be created!
     bool sendMessage(const QByteArray &buffer, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * This is an overloaded member function, provided for convenience.
      */
     bool sendMessage(const QDataStream &msg, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * This is an overloaded member function, provided for convenience.
      */
     bool sendMessage(const QString &msg, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * This is an overloaded member function, provided for convenience.
      */
     bool sendMessage(int data, int msgid, quint32 receiver = 0, quint32 sender = 0);
 
     /**
      * Called by ReceiveNetworkTransmission(). Will be overwritten by
      * KGame and handle the incoming message.
      */
     virtual void networkTransmission(QDataStream &, int, quint32, quint32, quint32 clientID) = 0;
 
     /**
      * Disconnect the current connection and establish a new local one.
      */
     void disconnect();
 
     /**
      * If you are the ADMIN of the game you can give the ADMIN status away to
      * another client. Use this e.g. if you want to quit the game or if you want
      * another client to administrate the game (note that disconnect calls
      * this automatically).
      * @param clientID the ID of the new ADMIN (note: this is the _client_ID
      * which has nothing to do with the player IDs. See KMessageServer)
      */
     void electAdmin(quint32 clientID);
 
     /**
      * Don't use this unless you really know what you're doing! You might
      * experience some strange behaviour if you send your messages directly
      * through the KMessageClient!
      *
      * @return a pointer to the KMessageClient used internally to send the
      * messages. You should rather use one of the send functions!
      */
     KMessageClient *messageClient() const;
 
     /**
      * Don't use this unless you really know what you are doing! You might
      * experience some strange behaviour if you use the message server directly!
      *
      * @return a pointer to the message server if this is the MASTER KGame
      * object. Note that it might be possible that no KGame object contains
      * the KMessageServer at all! It might even run stand alone!
      */
     KMessageServer *messageServer() const;
 
     /**
      * You should call this before doing thigs like, e.g. qApp->processEvents().
      * Don't forget to call unlock once you are done!
      *
      * @see KMessageClient::lock
      */
     virtual void lock();
 
     /**
      * @see KMessageClient::unlock
      */
     virtual void unlock();
 
 Q_SIGNALS:
     /**
      * A network error occurred
      * @param error the error code
      * @param text the error text
      */
     void signalNetworkErrorMessage(int error, const QString &text);
 
     /**
      * Our connection to the KMessageServer has broken.
      * See KMessageClient::connectionBroken
      */
     void signalConnectionBroken();
 
     /**
      * This signal is emitted whenever the KMessageServer sends us a message that a
      * new client connected. KGame uses this to call KGame::negotiateNetworkGame
      * for the newly connected client if we are admin (see isAdmin)
      *
      * @see KMessageClient::eventClientConnected
      *
      * @param clientID the ID of the newly connected client
      */
     void signalClientConnected(quint32 clientID);
 
     /**
      * This signal is emitted whenever the KMessageServer sends us a message
      * that a connection to a client was detached. The second parameter can be used
      * to distinguish between network errors or removing on purpose.
      *
      * @see KMessageClient::eventClientDisconnected
      *
      * @param clientID the client that has disconnected
      * @param broken true if the connection was lost because of a network error, false
      *        if the connection was closed by the message server admin.
      */
     void signalClientDisconnected(quint32 clientID, bool broken);
 
     /**
      * This client gets or loses the admin status.
      * @see KMessageClient::adminStatusChanged
      * @param isAdmin True if this client gets the ADMIN status otherwise FALSE
      */
     void signalAdminStatusChanged(bool isAdmin);
 
 protected:
     /**
      * @internal
      * Start a KMessageServer object and use it as the MASTER of the game.
      * Note that you must not call this if there is already another master
      * running!
      */
     void setMaster();
 
 protected Q_SLOTS:
     /**
      * Called by KMessageClient::broadcastReceived() and will check if the
      * message format is valid. If it is not, it will generate an error (see
      * signalNetworkVersionError and signalNetworkErorrMessage).
      * If it is valid, the pure virtual method networkTransmission() is called.
      * (This one is overwritten in KGame.)
      */
     void receiveNetworkTransmission(const QByteArray &a, quint32 clientID);
 
     /**
      * This KGame object receives or loses the admin status.
      * @param isAdmin Whether we are admin or not
      */
     void slotAdminStatusChanged(bool isAdmin);
 
     /**
      * Called when the network connection is about to terminate. Is used
      * to store the network parameter like the game id
      */
     void aboutToLoseConnection(quint32 id);
 
     /**
      * Called when the network connection is terminated. Used to clean
      * up the disconnect parameter
      */
     void slotResetConnection();
 
 private:
     void tryPublish();
     void tryStopPublishing();
 
 private:
     std::unique_ptr<KGameNetworkPrivate> const d;
 };
 
 #endif