Detailed Description

v1.00 (1 May 2023)
The Network TCP/IP interface provides a complete network system based on TCP/IP client/server architecture.

It is based on CRM32Pro INetwork code with several code parts reworked from scratch and others being heavily improved.

Main features:

high performance and low latency system
up to 8 clients with optional password login
logins can be enabled or disabled
secure transmission layer to avoid to expose information and any modification or hack.
log system with optional debugging mode
statistics and client latency information
server can run as stand-alone process or shared with a client
server has two working modes:
- non-authoritative mode:
  - sent data is not processed by the server
  - each client has full rights for doing any action
  - the client behaviour is: "I do my action and report it to others"
  - this mode is useful on games where the clients dont have to fight for getting an unique item or performing an unique action
- authoritative mode:
  - sent data is processed by the server using a callback function that will accept or deny the data
  - the clients can not do any action as it must be accepted by the callback function on the server
  - the client behaviour is: "Can I do this action? and wait for the server message: if it is accepted I can proceed, otherwise can not perform the action"
  - this mode is useful on games where clients have to fight for getting an unique item or performing an unique action
  - a well designed callback function will avoid impossible situations

Server modes

Only a single instance of the Network TCP/IP interface exists which is created once Main is instantiated.
You can get a reference to this manager using Main::INetTCP() method.

Note: The Network TCP/IP interface is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::NetTCP
	NetTCP class. More...

Macros
#define	NETFEATURE_DISABLE_LOGIN 1

Enumerations
enum	CRM64Pro::eNetMsg { CRM64Pro::NETMSG_NOTHING = 0 , CRM64Pro::NETMSG_DATA = 64 , CRM64Pro::NETMSG_DATA_ACCEPTED = 66 , CRM64Pro::NETMSG_DATA_DENIED = 67 , CRM64Pro::NETMSG_NEWCLIENT = 132 , CRM64Pro::NETMSG_QUITCLIENT = 133 , CRM64Pro::NETMSG_CLOSE = 134 , CRM64Pro::NETMSG_INFO = 135 , CRM64Pro::NETMSG_PING = 136 , CRM64Pro::NETMSG_ERROR = 192 }
	Network messages. More...

Functions
Sint32	CRM64Pro::NetTCP::info (Sint32 iMode=0)
	Request NetTCP Interface information.

Sint32	CRM64Pro::NetTCP::init (Uint8 iLM)
	Initialize the NetTCP system.

Sint32	CRM64Pro::NetTCP::close ()
	Close the NetTCP system.

Sint32	CRM64Pro::NetTCP::isServer ()
	Check if the server is running.

Sint32	CRM64Pro::NetTCP::isClient ()
	Check if the client is running.

Uint32	CRM64Pro::NetTCP::getIP ()
	Get the IP address.

Sint32	CRM64Pro::NetTCP::getClientName (string &sClientName)
	Get the client name.

Sint32	CRM64Pro::NetTCP::features (Sint32 iFeatures)
	Set or get advance features.

Sint32	CRM64Pro::NetTCP::connectTo (const string &sHost, Uint16 iPort, const string &sClient, Uint32 iPasswd)
	Connect to a server.

Sint32	CRM64Pro::NetTCP::sendData (void *pData, Sint32 iSize, Uint8 bIsQuery=1)
	Send a data package (blocking method).

eNetMsg	CRM64Pro::NetTCP::receiveData (void *pData, Uint32 iSize)
	Receive a data package (non-blocking method).

Sint32	CRM64Pro::NetTCP::freeData (void *&buf)
	Free a received data package.

Sint32	CRM64Pro::NetTCP::queryKillServer ()
	Query to close the server (and all the connected clients).

Sint32	CRM64Pro::NetTCP::queryKillClient ()
	Query to kill this client.

Sint32	CRM64Pro::NetTCP::queryClientsInfo ()
	Query to get updated the information of all connected clients.

Sint32	CRM64Pro::NetTCP::getClientsInfo (ClientInfo **cinfo)
	Get information stored locally about all connected clients.

Sint32	CRM64Pro::NetTCP::setTimeOut (Sint32 iMs)
	Set the connection timeout.

Sint32	CRM64Pro::NetTCP::setSimDelay (Sint32 iMs, Sint32 iMode=0)
	Simulate a connection delay.

Sint32	CRM64Pro::NetTCP::createServer (Uint16 iPort, Sint32 iPasswd, Sint32 iDedicated)
	Create a server.

Sint32	CRM64Pro::NetTCP::setCoreServerCallback (Sint32(myCoreServer)(void pData, Sint32 iSize, void pObj), void pObj=nullptr)
	Set a callback function into the server thread for handling data.

Macro Definition Documentation

◆ NETFEATURE_DISABLE_LOGIN

#define NETFEATURE_DISABLE_LOGIN 1

Used with Features() method. Disables the log into the server for new clients

Enumeration Type Documentation

◆ eNetMsg

enum CRM64Pro::eNetMsg

Network messages.

Enumerator
NETMSG_NOTHING	No message received.
NETMSG_DATA	User data received, pData has it!
NETMSG_DATA_ACCEPTED	Data sent by us was accepted, pData has it.
NETMSG_DATA_DENIED	Data sent by us was denied, pData has the it.
NETMSG_NEWCLIENT	New client connected, pData has the client name.
NETMSG_QUITCLIENT	A client has exited, pData has the client name.
NETMSG_CLOSE	Server has closed us.
NETMSG_INFO	After request a fresh client info, it has arrived and ready to be check with getClientsInfo().
NETMSG_PING	Periodic ping that the server send us.
NETMSG_ERROR	Error, it usually means the client lost the connection with the server.

Function Documentation

◆ info()

Sint32 CRM64Pro::NetTCP::info ( Sint32 iMode = 0 )

Request NetTCP Interface information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ init()

Sint32 CRM64Pro::NetTCP::init ( Uint8 iLM )

Initialize the NetTCP system.

Before using any other method as createServer() or connectTo(), NetTCP must be initialized.

Parameters

iLM	dedicated network log mode. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE for further information. You can OR'ed them. By default, it is set to LM_NULL.

Returns: 0 on success or a negative error code on failure.

◆ close()

Sint32 CRM64Pro::NetTCP::close ( )

Close the NetTCP system.

Returns: 0 on success or a negative error code on failure.

◆ isServer()

Sint32 CRM64Pro::NetTCP::isServer ( )

Check if the server is running.

Returns: 0 server is not runinng or 1 when it is.

◆ isClient()

Sint32 CRM64Pro::NetTCP::isClient ( )

Check if the client is running.

Returns: 0 client is not runinng or 1 when it is.

◆ getIP()

Uint32 CRM64Pro::NetTCP::getIP ( )

Get the IP address.

Returns: return the IP v4.

◆ getClientName()

Sint32 CRM64Pro::NetTCP::getClientName ( string & sClientName )

Get the client name.

Parameters

sClientName a string containing the client name when it is connected to a server.

Returns: 0 on success or a negative error code on failure.

◆ features()

Sint32 CRM64Pro::NetTCP::features ( Sint32 iFeatures )

Set or get advance features.

Check NETFEATURE_x defines for a list of supported features.

Parameters

iFeatures 32bits signed integer with desired flags enabled.
Enabling a current enabled flag will disable it.
When you want to get only current enabled flags, use -1.

Returns: greater than 0 on success(current features) or a negative error code on failure.

◆ connectTo()

Sint32 CRM64Pro::NetTCP::connectTo	(	const string &	sHost,
		Uint16	iPort,
		const string &	sClient,
		Uint32	iPasswd
	)

Connect to a server.

This method will try to connect to the server during the timeout (set by SetTimeOut()) before to return with an error. With ESCAPE key it halts the attempt.

Parameters

sHost	host name or IP of the server to connect to.
iPort	the listening server port (1024 to 65536).
sClient	client name, must be unique and with a maximum of 16 characters.
iPasswd	password to connect to the server.

Returns: 0 on success or a negative error code on failure.

◆ sendData()

Sint32 CRM64Pro::NetTCP::sendData	(	void *	pData,
		Sint32	iSize,
		Uint8	bIsQuery = `1`
	)

Send a data package (blocking method).

This method will send the data package to the server and depending on the server mode, these are the different behaviour:

Authoritative server mode: the data package is evaluated by the CoreServer callback function
- if it is accepted: the data package is sent to all clients, including the one who sent it.
- but if it is rejected: the data package is discarded and a notification is sent to the client who sent it.
- Note that it is possible to bypass this evaluation using bIsQuery = 0.
Non-Authoritative server mode: the data package is send to all clients but the one who sent it.

Parameters

pData	pointer to your data.
iSize	size in bytes of your data.
bIsQuery	only has mean on Authoritative server mode. By default is to 1 allowing the CoreServer callback function to evaluate the data package. Any other value will bypass this evaluation.

Returns: 0 on success or a negative error code on failure.

◆ receiveData()

eNetMsg CRM64Pro::NetTCP::receiveData	(	void **	pData,
		Uint32 *	iSize
	)

Receive a data package (non-blocking method).

The data packages may be generated by the server or by other clients.
Incoming data packages are stored on an internal queue so you can fetch all data elements calling this function until you get a return value of 0.

Parameters

pData	pointer to received data package.
iSize	pointer to integer with the size of received data (if any).

Returns: check eNetMsg for further information.
When NETMSG_NOTHING is returned, pData and iSize are set to nullptr.

Note: Data packages are automatically allocated and deallocated but once you have receive any of it using this method,
NetTCP will not manage it anymore, so you MUST CALL freeData() method when you finish to work with the data in order to free it and to avoid a memory leaks.

◆ freeData()

Sint32 CRM64Pro::NetTCP::freeData ( void *& pData )

Free a received data package.

Do no try to use any other free function for removing this data and use this method for it.

Parameters

pData pointer to the received data.

Returns: 0 on success or a negative error code on failure.

◆ queryKillServer()

Sint32 CRM64Pro::NetTCP::queryKillServer ( )

Query to close the server (and all the connected clients).

Returns: 0 on success(next receiveData() will return an NETTCP_ERROR code) or a negative error code on failure.

◆ queryKillClient()

Sint32 CRM64Pro::NetTCP::queryKillClient ( )

Query to kill this client.

Returns: 0 on success(next receiveData() will return an INETWORK_ERROR code) or a negative error code on failure.

◆ queryClientsInfo()

Sint32 CRM64Pro::NetTCP::queryClientsInfo ( )

Query to get updated the information of all connected clients.

Returns: 0 on success or a negative error code on failure.

◆ getClientsInfo()

Sint32 CRM64Pro::NetTCP::getClientsInfo ( ClientInfo ** cinfo )

Get information stored locally about all connected clients.

When a new client is connected or disconnected, the table containing the info is automatically updated.
In case you want to know the real latency on a client, you have to call to queryClientsInfo() before to call this method.
However, if the client is running together with the server, a call to queryClientsInfo() is not needed.

Parameters

cinfo a pointer to the information.
See sClientInfo struct to further information.

Returns: a positive integer with the number of clients (used to browse through the received pointer to cinfo) on success or a negative error code on failure.

◆ setTimeOut()

Sint32 CRM64Pro::NetTCP::setTimeOut ( Sint32 iMs )

Set the connection timeout.

Parameters

iMs	desired timeout in milliseconds used when connectTo() is used for connecting to a server. Minimum is 500ms. By default, the timeout is set to 2000ms.

Returns: 0 on success or a negative error code on failure.

◆ setSimDelay()

Sint32 CRM64Pro::NetTCP::setSimDelay	(	Sint32	iMs,
		Sint32	iMode = `0`
	)

Simulate a connection delay.

It only works for clients and could be changed at any time.

Parameters

iMs	simulated connection delay in milliseconds with this range [0,2500]. By default it's set to 0.
iMode	Reserved for future usages.

Returns: 0 on success or a negative error code on failure.

◆ createServer()

Sint32 CRM64Pro::NetTCP::createServer	(	Uint16	iPort,
		Sint32	iPasswd,
		Sint32	iDedicated
	)

Create a server.

Parameters

iPort	the listening server port (1024 to 65536).
iPasswd	integer with the server password.
iDedicated	1 for running in stand-alone mode (the call to this method will not return till the server is closed). 0 for running the server on a separated thread (the call to this method will return).

Returns: 0 on success or a negative error code on failure.

Note: Only one server can be created.

◆ setCoreServerCallback()

Sint32 CRM64Pro::NetTCP::setCoreServerCallback	(	Sint32()(void pData, Sint32 iSize, void *pObj)	myCoreServer,
		void *	pObj = `nullptr`
	)

Set a callback function into the server thread for handling data.

Parameters

myCoreServer your callback function which takes a pointer to the data and its size. An optional pObj pointer to the data/function/static method fixed when calling this method.
When a callback function is used, the server run on authoritative mode, otherwise, it will run on non-authoritative mode.
Using nullptr will disable any callback function.
The callback function run on the server thread.
It must return 0 when sent data is accepted or a negative error code when it is denied.

pObj pointer to data/function/static method.
By default, it is not used and set to nullptr.

Returns: 0 on success or a negative error code on failure.

Detailed Description

Classes

Macros

Enumerations

Functions

Macro Definition Documentation

◆ NETFEATURE_DISABLE_LOGIN

Enumeration Type Documentation

◆ eNetMsg

Function Documentation

◆ info()

◆ init()

◆ close()

◆ isServer()

◆ isClient()

◆ getIP()

◆ getClientName()

◆ features()

◆ connectTo()

◆ sendData()

◆ receiveData()

◆ freeData()

◆ queryKillServer()

◆ queryKillClient()

◆ queryClientsInfo()

◆ getClientsInfo()

◆ setTimeOut()

◆ setSimDelay()

◆ createServer()

◆ setCoreServerCallback()