libkdegames Library API Documentation

KGameNetwork Class Reference

The KGameNetwork class is the KGame class with network support. The main KDE game object. More...

#include <kgamenetwork.h>

Inheritance diagram for KGameNetwork:

QObject KGame List of all members.

Signals

void signalNetworkErrorMessage (int error, QString text)
void signalConnectionBroken ()
void signalClientConnected (Q_UINT32 clientID)
void signalClientDisconnected (Q_UINT32 clientID, bool broken)
void signalAdminStatusChanged (bool isAdmin)

Public Methods

 KGameNetwork (int cookie=42, QObject *parent=0)
virtual ~KGameNetwork ()
virtual void Debug ()
bool isNetwork () const
bool isMaster () const
bool isAdmin () const
Q_UINT32 gameId () const
bool offerConnections (Q_UINT16 port)
bool connectToServer (const QString &host, Q_UINT16 port)
Q_UINT16 port () const
QString hostName () const
bool stopServerConnection ()
void setMaxClients (int max)
bool sendSystemMessage (const QByteArray &buffer, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendSystemMessage (int data, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendSystemMessage (const QDataStream &msg, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendSystemMessage (const QString &msg, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
void sendError (int error, const QByteArray &message, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool isOfferingConnections () const
int cookie () const
bool sendMessage (const QByteArray &buffer, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendMessage (const QDataStream &msg, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendMessage (const QString &msg, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
bool sendMessage (int data, int msgid, Q_UINT32 receiver=0, Q_UINT32 sender=0)
virtual void networkTransmission (QDataStream &, int, Q_UINT32, Q_UINT32, Q_UINT32 clientID)=0
void disconnect ()
void electAdmin (Q_UINT32 clientID)
KMessageClientmessageClient () const
KMessageServermessageServer () const
virtual void lock ()
virtual void unlock ()

Protected Slots

void receiveNetworkTransmission (const QByteArray &a, Q_UINT32 clientID)
void slotAdminStatusChanged (bool isAdmin)
void aboutToLoseConnection (Q_UINT32 id)
void slotResetConnection ()

Protected Methods

void setMaster ()

Detailed Description

The KGameNetwork class is the KGame class with network support. The main KDE game object.

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.

Author:
Martin Heni <martin@heni-online.de>
Version:
Id:
kgamenetwork.h,v 1.29 2003/10/12 13:32:56 bhards Exp

Definition at line 46 of file kgamenetwork.h.


Constructor & Destructor Documentation

KGameNetwork::KGameNetwork int    cookie = 42,
QObject   parent = 0
 

Create a KGameNetwork object.

Definition at line 57 of file kgamenetwork.cpp.

References cookie().


Member Function Documentation

void KGameNetwork::Debug   [virtual]
 

Gives debug output of the game status.

Reimplemented in KGame.

Definition at line 472 of file kgamenetwork.cpp.

References gameId(), isAdmin(), and isMaster().

Referenced by KGame::Debug().

bool KGameNetwork::isNetwork   const
 

Returns:
TRUE if this is a network game - i.e. you are either MASTER or connected to a remote MASTER.

Definition at line 77 of file kgamenetwork.cpp.

References isOfferingConnections().

Referenced by port().

bool KGameNetwork::isMaster   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 also:
isAdmin
Returns:
Whether this client has started the KMessageServer

Definition at line 95 of file kgamenetwork.cpp.

Referenced by Debug(), and offerConnections().

bool KGameNetwork::isAdmin   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.

Returns:
Whether this client (KGame object) is the admin

Definition at line 98 of file kgamenetwork.cpp.

Referenced by Debug(), electAdmin(), KGame::negotiateNetworkGame(), setMaxClients(), KGame::setMaxPlayers(), KGame::setMinPlayers(), slotAdminStatusChanged(), KGame::slotClientConnected(), KGame::systemActivatePlayer(), and KGame::systemInactivatePlayer().

Q_UINT32 KGameNetwork::gameId   const
 

The unique ID of this game.

Returns:
int id

Definition at line 80 of file kgamenetwork.cpp.

Referenced by KGame::addPlayer(), Debug(), disconnect(), KPlayer::networkTransmission(), KGame::networkTransmission(), receiveNetworkTransmission(), and sendSystemMessage().

bool KGameNetwork::offerConnections Q_UINT16    port
 

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.

Parameters:
port  The port on which the service is offered
Returns:
true if it worked

Definition at line 144 of file kgamenetwork.cpp.

References isMaster(), and port().

bool KGameNetwork::connectToServer const QString   host,
Q_UINT16    port
 

Inits a network game as a network CLIENT.

Parameters:
host  the host to which we want to connect
port  the port we want to connect to
Returns:
true if connected

Definition at line 172 of file kgamenetwork.cpp.

References QString::isEmpty(), port(), signalAdminStatusChanged(), and stopServerConnection().

Q_UINT16 KGameNetwork::port   const
 

Since:
3.2.

Returns:
The port we are listening to if offerConnections was called or the port we are connected to if connectToServer was called. Otherwise 0.

Definition at line 210 of file kgamenetwork.cpp.

References isNetwork(), and isOfferingConnections().

Referenced by connectToServer(), and offerConnections().

QString KGameNetwork::hostName   const
 

Since:
3.2.

Returns:
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".

Definition at line 222 of file kgamenetwork.cpp.

bool KGameNetwork::stopServerConnection  
 

Stops offering server connections - only for game MASTER.

Returns:
true

Definition at line 227 of file kgamenetwork.cpp.

Referenced by connectToServer(), and disconnect().

void KGameNetwork::setMaxClients int    max
 

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 also:
KMessageServer::setMaxClients
Parameters:
max  The maximal number of connections possible.

Definition at line 315 of file kgamenetwork.cpp.

References isAdmin().

bool KGameNetwork::sendSystemMessage const QByteArray   buffer,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

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!

Parameters:
buffer  the message which will be send. See messages.txt for contents
msgid  an id for this message. See KGameMessage::GameMessageIds
receiver  the KGame / KPlayer this message is for.
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.
Returns:
true if worked

Definition at line 363 of file kgamenetwork.cpp.

References gameId(), QObject::sender(), and QDataStream::writeRawBytes().

Referenced by KGame::activatePlayer(), KGame::addPlayer(), KPlayer::forwardMessage(), KGame::inactivatePlayer(), KGame::negotiateNetworkGame(), KGame::networkTransmission(), KGame::playerDeleted(), sendError(), sendMessage(), KGame::sendPlayerInput(), KGame::sendPlayerProperty(), KGame::sendProperty(), sendSystemMessage(), and KGame::syncRandom().

bool KGameNetwork::sendSystemMessage int    data,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 344 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

bool KGameNetwork::sendSystemMessage const QDataStream   msg,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 360 of file kgamenetwork.cpp.

References QDataStream::device(), QObject::sender(), and sendSystemMessage().

bool KGameNetwork::sendSystemMessage const QString   msg,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 352 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

void KGameNetwork::sendError int    error,
const QByteArray   message,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

Sends a network message.

Parameters:
error  The error code
message  The error message - use KGameError
receiver  the KGame / KPlayer this message is for. 0 For all
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.

Definition at line 417 of file kgamenetwork.cpp.

References QObject::sender(), sendSystemMessage(), and QDataStream::writeRawBytes().

Referenced by KGame::networkTransmission().

bool KGameNetwork::isOfferingConnections   const
 

Are we still offer offering server connections - only for game MASTER.

Returns:
true/false

Definition at line 237 of file kgamenetwork.cpp.

Referenced by isNetwork(), and port().

int KGameNetwork::cookie   const
 

Application cookie.

this idendifies the game application. It help to distinguish between e.g. KPoker and KWin4

Returns:
the application cookie

Definition at line 92 of file kgamenetwork.cpp.

Referenced by KGameNetwork(), KGame::loadgame(), KGame::negotiateNetworkGame(), KGame::networkTransmission(), and KGame::savegame().

bool KGameNetwork::sendMessage const QByteArray   buffer,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

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 mehtod 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 comunicate with KGame (e.g. by adding a player) and sendMessage for your own user message.

Note: a player should send messages through a KGameIO!

Parameters:
buffer  the message which will be send. See messages.txt for contents
msgid  an id for this message. See KGameMessage::GameMessageIds
receiver  the KGame / KPlayer this message is for.
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.
Returns:
true if worked

Definition at line 414 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

Referenced by KGame::sendGroupMessage().

bool KGameNetwork::sendMessage const QDataStream   msg,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience.

Definition at line 411 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

bool KGameNetwork::sendMessage const QString   msg,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience.

Definition at line 408 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

bool KGameNetwork::sendMessage int    data,
int    msgid,
Q_UINT32    receiver = 0,
Q_UINT32    sender = 0
 

This is an overloaded member function, provided for convenience.

Definition at line 405 of file kgamenetwork.cpp.

References QObject::sender(), and sendSystemMessage().

virtual void KGameNetwork::networkTransmission QDataStream  ,
int   ,
Q_UINT32   ,
Q_UINT32   ,
Q_UINT32    clientID
[pure virtual]
 

Called by ReceiveNetworkTransmission().

Will be overwritten by KGame and handle the incoming message.

Implemented in KGame.

Referenced by receiveNetworkTransmission().

void KGameNetwork::disconnect  
 

Disconnect the current connection and establish a new local one.

Definition at line 240 of file kgamenetwork.cpp.

References QValueList::begin(), QValueList::end(), gameId(), KMessageIO::rtti(), and stopServerConnection().

Referenced by KGame::networkTransmission().

void KGameNetwork::electAdmin Q_UINT32    clientID
 

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).

Parameters:
clientID  the ID of the new ADMIN (note: this is the _client_ID which has nothing to do with the player IDs. See KMessageServer)

Definition at line 302 of file kgamenetwork.cpp.

References isAdmin().

KMessageClient * KGameNetwork::messageClient   const
 

Don't use this unless you really know what youre doing! You might experience some strange behaviour if you send your messages directly through the KMessageClient!

Returns:
a pointer to the KMessageClient used internally to send the messages. You should rather use one of the send functions!

Definition at line 101 of file kgamenetwork.cpp.

Referenced by lock(), and unlock().

KMessageServer * KGameNetwork::messageServer   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!

Returns:
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!

Definition at line 104 of file kgamenetwork.cpp.

void KGameNetwork::lock   [virtual]
 

You should call this before doing thigs like, e.g.

qApp->processEvents(). Don't forget to call unlock once you are done!

See also:
KMessageClient::lock

Definition at line 328 of file kgamenetwork.cpp.

References KMessageClient::lock(), and messageClient().

void KGameNetwork::unlock   [virtual]
 

See also:
KMessageClient::unlock

Definition at line 335 of file kgamenetwork.cpp.

References messageClient(), and KMessageClient::unlock().

void KGameNetwork::signalNetworkErrorMessage int    error,
QString    text
[signal]
 

A network error occurred.

Parameters:
error  the error code
text  the error text

Referenced by receiveNetworkTransmission().

void KGameNetwork::signalConnectionBroken   [signal]
 

Our connection to the KMessageServer has broken.

See KMessageClient::connectionBroken

Referenced by KGame::KGame().

void KGameNetwork::signalClientConnected Q_UINT32    clientID [signal]
 

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 also:
KMessageClient::eventClientConnected
Parameters:
clientID  the ID of the newly connected client

Referenced by KGame::KGame().

void KGameNetwork::signalClientDisconnected Q_UINT32    clientID,
bool    broken
[signal]
 

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 also:
KMessageClient::eventClientDisconnected
Parameters:
clientID  the client that has disconnected
broken  true if the connection was lost because of a network error, false if the connection was closed by the message server admin.

Referenced by KGame::KGame().

void KGameNetwork::signalAdminStatusChanged bool    isAdmin [signal]
 

This client gets or loses the admin status.

See also:
KMessageClient::adminStatusChanged
Parameters:
isAdmin  True if this client gets the ADMIN status otherwise FALSE

Referenced by connectToServer(), and slotAdminStatusChanged().

void KGameNetwork::receiveNetworkTransmission const QByteArray   a,
Q_UINT32    clientID
[protected, slot]
 

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.)

Definition at line 428 of file kgamenetwork.cpp.

References gameId(), QString::latin1(), networkTransmission(), QObject::sender(), and signalNetworkErrorMessage().

void KGameNetwork::slotAdminStatusChanged bool    isAdmin [protected, slot]
 

This KGame object receives or loses the admin status.

Parameters:
isAdmin  Whether we are admin or not

Definition at line 465 of file kgamenetwork.cpp.

References isAdmin(), and signalAdminStatusChanged().

void KGameNetwork::aboutToLoseConnection Q_UINT32    id [protected, slot]
 

Called when the network connection is about to terminate.

Is used to store the network parameter like the game id

Definition at line 290 of file kgamenetwork.cpp.

void KGameNetwork::slotResetConnection   [protected, slot]
 

Called when the network connection is terminated.

Used to clean up the disconnect parameter

Definition at line 296 of file kgamenetwork.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for libkdegames Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 10:06:39 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003