Listens for inbound TCP or UDP communication.

The NetServer class extends NetSocket with local bind, listen and accepted-client management. For TCP listeners, each accepted connection is represented by a ClientSocket and grouped by client IP address in NetClient records. For UDP listeners, incoming datagrams are received through the inherited Incoming callback and can be read with RecvFrom().

SSL Server Certificates

For SSL NetServer listeners, custom certificates can be specified using the SSLCertificate field. Both PEM and PKCS#12 formats are supported across all platforms.

Example with PKCS#12 certificate:

netserver = obj.new('netserver', {
   flags = 'SSL',
   port = 8443,
   sslCertificate = 'config:ssl/server.p12',
   sslKeyPassword = 'password123'
})

Example with PEM certificate and separate private key:

netserver = obj.new('netserver', {
   flags = 'SSL',
   port = 8443,
   sslCertificate = 'config:ssl/server.crt',
   sslPrivateKey = 'config:ssl/server.key'
})

If no custom certificate is specified, the framework will automatically use a localhost self-signed certificate for development purposes. For production use, always specify a proper certificate signed by a trusted CA.

Structure

The NetServer class consists of the following fields:

Access	Name	Type	Comment
	Backlog	INT	The maximum number of connections that can be queued against the socket.
Incoming TCP connections to NetServer objects are queued until they are accepted by the object. Setting the Backlog adjusts the maximum number of connections on the queue, which otherwise defaults to 10. If the backlog is exceeded, subsequent connections to the socket should expect a connection refused error.
	ClientLimit	INT	The maximum number of clients (unique IP addresses) that can be connected to a NetServer.
The ClientLimit value limits the maximum number of IP addresses that can be connected to the socket at any one time. For socket limits per client, see the SocketLimit field.
	Clients	OBJECTPTR	Lists all NetClient records connected to the NetServer.
	SSLCertificate	STRING	SSL certificate file to use for SSL NetServer listeners.
Set SSLCertificate to the path of an SSL certificate file to use when the NetServer is initialised with SSL enabled. The certificate file must be in a supported format such as PEM, CRT, or P12. If no certificate is defined, the NetServer will either self-sign or use a localhost certificate, if available.
	SSLKeyPassword	STRING	SSL private key password.
If the SSL private key is encrypted, set this field to the password required to decrypt it. If the private key is not encrypted, this field can be left empty.
	SocketLimit	INT	The maximum number of sockets that can be connected from a single client IP address.
The SocketLimit value limits how many simultaneous ClientSocket connections may be opened by one NetClient record.
	TotalClients	INT	Indicates the total number of clients currently connected to the NetServer.
NetServer maintains a count of the total number of currently connected TCP client sockets. You can read the total number of connections from this field.

Actions

The following actions are currently supported:

Read

Reads raw data information from objects.

ERR acRead(*Object, std::span<int8_t> Buffer, INT *Result)

Parameter	Description
Buffer	A mutable buffer that will receive the data.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

Write

Writes data to objects that provide storage or output services.

ERR acWrite(*Object, std::span<const int8_t> Buffer, INT *Result)

Parameter	Description
Buffer	A buffer containing the data that will be written to the object.
Result	This parameter with be updated with the total number of bytes written from the Buffer.

Methods

The following methods are currently supported:

DisconnectClient Disconnects all sockets connected to a specific client IP.

ERR ns::DisconnectClient(OBJECTPTR Object, objNetClient * Client)

Parameter	Description
Client	The client to be disconnected.

For NetServer listeners with client IP connections, this method will terminate all socket connections made to a specific client IP and free the resources allocated to it. If #Feedback is defined, a DISCONNECTED state message will also be issued for each socket connection.

If only one socket connection needs to be disconnected, please use DisconnectSocket().

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)
WrongClass	The Client object is not of type `NetClient`.

DisconnectSocket Disconnects a single socket that is connected to a client IP address.

ERR ns::DisconnectSocket(OBJECTPTR Object, objClientSocket * Socket)

Parameter	Description
Socket	The client socket to be disconnected.

This method will disconnect a socket connection for a given client. If #Feedback is defined, a DISCONNECTED state message will also be issued.

NOTE: To terminate the connection of a socket acting as the client, either free the object or return/raise ERR::Terminate during Incoming feedback.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)
WrongClass	An object is not of the required class type

NSF Type

NetSocket options

Name	Description
NSF::BROADCAST	Enable broadcast (UDP only).
NSF::DISABLE_SERVER_VERIFY	Disable SSL server certificate verification for client sockets (testing only).
NSF::KEEP_ALIVE	Enable TCP keep-alive probes using operating system defaults.
NSF::LOG_ALL	Print extra log messages.
NSF::MULTI_CONNECT	Allow multiple connections from the same IP (NetServer only).
NSF::SSL	Use Secure Sockets Layer for all communication.
NSF::SYNCHRONOUS	Use synchronous (blocking) network calls.
NSF::UDP	Use UDP (connectionless datagram protocol) instead of TCP.

NTC Type

NetSocket states