| CRM64Pro GDK v0.15.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Network TCP/IP client/server
Network modules

## Description

Network TCP/IP interface providing a client/server architecture [v25.12.0].

### Overview

The Network TCP/IP interface provides a complete networking system based on TCP/IP client/server architecture. It is based on CRM32Pro INetwork code with several parts reworked from scratch and others heavily improved.

Server modes

### Key features

- High performance: Low latency networking system
- Multi-client: Support for up to 8 simultaneous clients
- Authentication: Optional password login system (can be enabled or disabled)
- Secure transmission: Protection layer to prevent information exposure, modification or hacking
- Diagnostics: Log system with optional debugging mode, statistics and client latency information
- Flexible deployment: Server can run as stand-alone process or shared with a client

### Server configuration

Max clients | Up to 8 simultaneous connections
Login system | Optional password authentication (can be enabled or disabled)
Deployment | Stand-alone server process or shared with a client instance

### Server modes

The server supports two working modes depending on how client actions are validated:

Non-authoritative mode

Data processing | Sent data is not processed by the server
Client rights | Each client has full rights for performing any action
Client behavior | "I do my action and report it to others"
Use case | Games where clients do not compete for unique items or actions

Authoritative mode

Data processing | Sent data is processed by the server using a callback function that accepts or denies the data
Client rights | Clients cannot perform actions until accepted by the server callback
Client behavior | "Can I do this action?" → wait for server response → proceed if accepted
Use case | Games where clients compete for unique items or actions

### Best practices

- Choose the appropriate server mode based on your game design requirements
- Use authoritative mode when clients compete for unique resources to prevent race conditions
- Design callback functions carefully in authoritative mode to avoid impossible situations
- Enable the secure transmission layer to protect sensitive game data
- Use the statistics and latency information to monitor network performance
- Enable the debug logging mode during development to diagnose connection issues
- Consider running the server as a stand-alone process for production deployments
- Access the interface exclusively through Main::INetTCP()

Note
  The Network TCP/IP interface is a singleton, automatically created once Main is instantiated. You can get a reference to this interface using Main::INetTCP() method.
  The Network TCP/IP interface is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding 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
bool | CRM64Pro::NetTCP::info (Sint32 iMode=0) override
| Request NetTCP Interface information.
Sint32 | CRM64Pro::NetTCP::init (eLogMode eLM)
| Initialize the NetTCP system.
Sint32 | CRM64Pro::NetTCP::close ()
| Close the NetTCP system.
bool | CRM64Pro::NetTCP::isServer () const
| Check if the server is running.
bool | CRM64Pro::NetTCP::isClient () const
| Check if the client is running.
Uint32 | CRM64Pro::NetTCP::getIP () const
| 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 *&pData)
| 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()

bool CRM64Pro::NetTCP::info | ( | Sint32 | iMode = 0 | ) |
| override

Request NetTCP Interface information.

Writes information to the default log.

Parameters

  iMode | unused for the time being.

Returns
  true on success, or false on failure.

## ◆ init()

Sint32 CRM64Pro::NetTCP::init | ( | eLogMode | eLM | ) |

Initialize the NetTCP system.

Before using createServer() or connectTo(), NetTCP must be initialized.

Parameters

  eLM | dedicated network log mode. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE (can be OR'ed). Default is 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()

bool CRM64Pro::NetTCP::isServer | ( |  | ) | const

Check if the server is running.

Returns
  false if server is not running or true when it is.

## ◆ isClient()

bool CRM64Pro::NetTCP::isClient | ( |  | ) | const

Check if the client is running.

Returns
  false if client is not running or true when it is.

## ◆ getIP()

Uint32 CRM64Pro::NetTCP::getIP | ( |  | ) | const

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 supported features.

Parameters

  iFeatures | 32bits signed integer with desired flags. Enabling an already enabled flag disables it. Use -1 to only get current flags.

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

Sends data to server. Behavior depends on server mode: Authoritative mode evaluates data via CoreServer callback (accepted: sent to all clients; rejected: discarded with notification; bypass with bIsQuery=0). Non-Authoritative mode sends to all clients except sender.

Parameters

  pData | pointer to your data.
  iSize | size in bytes of your data.
  bIsQuery | for Authoritative mode only. Default 1 allows callback evaluation. Other values bypass 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).

Data packages come from server or other clients. Incoming packages are queued; call repeatedly until return value is 0.

Parameters

  pData | pointer to received data package.
  iSize | pointer to integer with size of received data.

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

Note
  Data is auto-allocated but after receiving via this method, YOU MUST call freeData() when done to avoid 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.

Client info table auto-updates on connect/disconnect. For real latency, call queryClientsInfo() first (not needed if client runs with server).

Parameters

  cinfo | pointer to the information. See sClientInfo struct.

Returns
  positive integer with number of clients (for browsing cinfo) on success or a negative error code on failure.

## ◆ setTimeOut()

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

Set the connection timeout.

Parameters

  iMs | timeout in milliseconds for connectTo(). Minimum 500ms. Default 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.

Only works for clients. Can be changed at any time.

Parameters

  iMs | simulated delay in milliseconds [0-2500]. Default 0.
  iMode | Reserved for future use.

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 stand-alone mode (call blocks until server closes). 0 for threaded mode (call returns immediately).

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

Note
  Only one server can be created.

## ◆ setCoreServerCallback()

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.

Parameters

  myCoreServer | callback function taking data pointer, size, and optional pObj. With callback, server runs in authoritative mode; without, non-authoritative mode. Use nullptr to disable callback. Runs on server thread. Return 0 for accepted data or negative for denied.
  pObj | pointer to data/function/static method. Default nullptr (unused).

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