NetBasicManager Class Reference
[Networking, Single inited classes]

Basic class for managing network transfers. More...

#include <netmanager.h>

Inheritance diagram for NetBasicManager:

[legend]Collaboration diagram for NetBasicManager:

[legend]List of all members.

Public Member Functions
DECLSPEC	NetBasicManager (const char *name, BasicObject *p)
DECLSPEC	NetBasicManager (TiXmlElement *el, BasicObject *p)
DECLSPEC bool	init (unsigned int port=NETWORK_PORT, unsigned int udpport=NETWORK_UDPPORT, int udpmaxsize=1024)
void	destroy ()
DECLSPEC unsigned int	send (char *data, int size)
DECLSPEC bool	sendUDP (char *data, int size, const IPaddress &ip)
virtual DECLSPEC bool	checkPeers ()
virtual DECLSPEC bool	checkServer ()
DECLSPEC NetSocket *	getSocket (const IPaddress &ip)
DECLSPEC void	deleteDisconnected ()
int	numConnections ()
void	setConnectCallback (BasicObject::Callback func, BasicObject *pData)
void	setPeerCallback (BasicObject::Callback func, BasicObject *pData)
void	setUDPCallback (BasicObject::Callback func, BasicObject *pData)
int	localPort ()
DECLSPEC const char *	localIP ()
	Note: this method is only IPv4 compatible
Static Public Member Functions
static DECLSPEC bool	initSDL ()
static DECLSPEC void	quitSDL ()
Static Public Attributes
static NetBasicManager *	the
Protected Member Functions
virtual DECLSPEC void	onInit ()
virtual DECLSPEC void	onDestroy ()
virtual DECLSPEC void	onReceiveUDP (UDPpacket *udp)
virtual NetSocket *	createSocket (TCPsocket socket)=0
Static Protected Member Functions
static DECLSPEC NetBasicManager *	getThe ()
Protected Attributes
bool	bInited
int	nListenPort
unsigned int	nUDPPort
Friends
class	NetSocket

---

Detailed Description

Basic class for managing network transfers.

To use network, initialize a derived class from this, because NetBasicManager contains virtual prototype functions.

Every network managing class works closely together with a socket class, which has to be derived from NetSocket. All Sockets have to be children of a class derived from NetBasicManager and all children of a NetBasicManager have to be NetSocket objects.

Similar to the creation of GuiElements via XML-file, it is possible to create NetSockets by XML-data, if the concerning NetSocket-derived class has a valid slot registered for creating it. In comparison to the Gui-objects, the sockets have to be direct children of the Net*Manager and they have to be compatible to the Net*Manager (i.e. NetStandardSocket must not be a child of NetPeerManager)

UDP
The NetBasicManager will always (try to) initialize UDP. But if UDP cannot be initialized, the init() method will return true though (provided that TCP could be set up). The reason for this is, that UDP is a protocol, that cannot guarantee that packet reach the destination host. So UDP not initialized is equal to loosing all packets.

This class must not be used in two variables at a time.

See also:

Single inited classes

---

Member Function Documentation

bool NetBasicManager::init	(	unsigned int	port = NETWORK_PORT,
		unsigned int	udpport = NETWORK_UDPPORT,
		int	udpmaxsize = 1024
	)

Initializes the network manager. If you do not use the constructor NetBasicManager(TiXmlElement *, BasicObject *) calling this is neccessary before using further network functions.

Parameters:

	port	port number on which to listen for connections or zero, if it should only work as client and does not need server abilities If you do not specify a param, the default netrinjo network port will be used, as defined in NETWORK_PORT.
	udpport	the port number on which to send/receive UDP packets. This must be <port>+1 when using UDP with NetSockets! If zero, the port number is chosen by the system.
	udpmaxsize	the maximum size (in bytes), an incomming UDP packet must not exceed.

Returns:

true, if everything (except UDP) could be initialized correctly and false, if an error occured

void NetBasicManager::destroy

(

)

[inline]

Uninitializes the network manager. Call this before closing the app.

Reimplemented from BasicObject.

unsigned int NetBasicManager::send	(	char *	data,
		int	size
	)

Sends data to all connected hosts by calling sendData(data,size) of all sockets.

Parameters:

	data	a pointer to the data to be sent
	size	the size (in bytes) of the data to be sent

Returns:

the number of hosts to whom the message was sent successfully

bool NetBasicManager::sendUDP	(	char *	data,
		int	size,
		const IPaddress &	ip
	)

Sends data via UDP to the specified host.

Parameters:

	data	the data to send
	size	the size of the data (in bytes)
	ip	the destination IP-address

Returns:

true on success, false on error

bool NetBasicManager::checkPeers

(

)

[virtual]

Checks all connections, whether there was an incomming message and, if so, the callback function will be called on every message.
This function should be called regularly to be able to act on the messages.

See also:

setPeerCallBack

Returns:

true, if there was at least one incomming message and false, if either no message came, or an error occured

bool NetBasicManager::checkServer

(

)

[virtual]

Checks on incomming connection requests. If someone wants to connect, the callback function will be called. There is only one new connection possible per checkServer-call.
This function should be called regularly to be able to act on connection requests.

See also:

setConnectCallBack

Returns:

true, if a socket was added to the manager's socket list, but however it is possible, that the socket is disconnected;
false, if no socket was added to the list, so either no request came, an error occured or the number of connections exeeds MAX_PEERS

NetSocket * NetBasicManager::getSocket

(

const IPaddress &

ip

)

Parameters:

ip

the address of the socket to return (its port can be set to zero in order to ignore it)

Returns:

the socket belonging to the given ip address, or NULL if no socket matches the address

void NetBasicManager::deleteDisconnected

(

)

Deletes all disconnected sockets and removes them from the manager's socket list.

int NetBasicManager::numConnections

(

)

[inline]

Returns:

the number of connections, that are currently valid

void NetBasicManager::setConnectCallback	(	BasicObject::Callback	func,
		BasicObject *	pData
	)			[inline]

Sets the callback function, that is called, when a connection request is comming in

Parameters:

	func	the function to call
	pData	a pointer to data, that should be sent to the callback as 2nd param

void NetBasicManager::setPeerCallback	(	BasicObject::Callback	func,
		BasicObject *	pData
	)			[inline]

Sets the default callback function, that is called, when a socket receives data.

Parameters:

	func	the function to call
	pData	a pointer to data, that should be sent to the callback as 2nd param

void NetBasicManager::setUDPCallback	(	BasicObject::Callback	func,
		BasicObject *	pData
	)			[inline]

Sets the default callback function, that is called, when the UDP socket receives data.

Parameters:

	func	the function to call
	pData	a pointer to data, that should be sent to the callback as 2nd param

int NetBasicManager::localPort

(

)

[inline]

Returns:

the port on which the network manager is listening, if it works as server; zero, if it does not use server functions

See also:

init

const char * NetBasicManager::localIP

(

)

Note:

this method is only IPv4 compatible

Returns:

the local IP address as string in the format

 xxx.xxx.xxx.xxx 

Warning:

on linux-OSes it might fail, because it just reads the IP address written in the /etc/hosts file. If there is not the correct IP address or the file's format is not compatible to this function, the result will be garbage.

Test:

verify result

bool NetBasicManager::initSDL

(

)

[static]

Initialises SDL-networking, by calling SDLNet_Init() - if not done already. If initialisation succedes, or if it was already done, the reference counter is increased.

Returns:

true, on success or if it has already been initialized.

void NetBasicManager::quitSDL

(

)

[static]

Decreases the reference counter and uninitialises SDL-networking, if it becomes zero by calling SDLNet_Quit().

NetBasicManager * NetBasicManager::getThe

(

)

[static, protected]

This function is protected, so use the getThe function of the derived class that was inited.

Returns:

a pointer to the NetBasicManager-variable, or NULL if not initialized. (There is only one NetBasicManager-variable allowed in an application)

Every netrinjo-class that can only exist once at a time, has this static function.

See also:

Single inited classes, NetSimpleManager::getThe(), NetPeerManager::getThe()

Reimplemented in NetSimpleManager, and NetPeerManager.

void NetBasicManager::onInit

(

)

[protected, virtual]

Initializes the object's variables by reading data from the XML element. If there were no XML data used for creation, nothing is done. This function calls onInit() of its children recursively (after it has inited itself). It is highly recommended to call BasicObject::onInit(), usually at the end of the onInit() method, when overwriting it in a derived class.

Reimplemented from BasicObject.

Reimplemented in NetPeerManager.

void NetBasicManager::onDestroy

(

)

[protected, virtual]

May be called to reinitialise this object or stop an initialised module. Calls all children's onDestroy(). Most classes do not use this method. But sometimes it is useful to reset the functionality of an object.

Reimplemented from BasicObject.

void NetBasicManager::onReceiveUDP

(

UDPpacket *

udp

)

[protected, virtual]

Called after a UDP packet has been received.
NetBasicManager::onReceiveUDP() looks for a NetSocket, that uses the same address (IP + port) as the packet's source is and calls its onReceiveUDP() method.

Parameters:

udp

the received packet (the content will be overwritten when receiving the next packet)

virtual NetSocket* NetBasicManager::createSocket

(

TCPsocket

socket

)

[protected, pure virtual]

Creates a class, derived from NetSocket, that is compatible to the managing class.

Parameters:

socket

the SDL-TCP socket which is used by the new NetSocket

Returns:

a pointer to the created class, converted to NetSocket*

Implemented in NetSimpleManager, and NetPeerManager.

---

Member Data Documentation

NetBasicManager * NetBasicManager::the [static]

only accessible in Linux, and equals the result of getThe()

bool NetBasicManager::bInited [protected]

Signals, whether the manager has been inited.

int NetBasicManager::nListenPort [protected]

Contains the TCP port number on which the manager listens for connection requests. It is zero, if it does not work as server.

See also:

localPort()

unsigned int NetBasicManager::nUDPPort [protected]

The port on which is listened for UDP data, if zero the port is unknown

---

The documentation for this class was generated from the following files:

• netmanager.h
• netmanager.cpp

---