Server Application, Sockets

Server Application in CumulusServer uses LUA engine. This engine can be extended with some LUA extensions to add some required features (for more details see Server Application page.) Usually to add sockets feature in LUA, the extension LUASocket is used. But this extension has three disavantages to create Server Application in CumulusServer:

• All methods to receive and send data are in a blocking mode by default. It can be changed, but it works not correctly especially in TCP. LUA is essentialy single-threaded, and the handle have to return to Cumulus quickly on each script processing. We have need of non-blocking socket features which works with performance in all circumstances.
• LUASocket don't work always fine on Windows.
• It duplicates uselessly socket cross-platform features already provided by Cumulus in its core.

For all these reason, I am making available a new LUA socket features mapping on Cumulus socket intern framework, with only non-blocking methods.

TCP Client

Warning This feature requires POCO dependency greater or equal to 1.4.0, otherwise the send method will not work correctly.

To create a TCP client, call cumulus:createTCPClient() method (see cumulus object description on Server Application, API page). Here a complete sample to understand its usage:

	socket = cumulus:createTCPClient()
	function socket:onReception(data)
		NOTE("Reception from "..self.peerAddress.." to "..self.address)
		self:send(data) -- echo sample
		return 0 -- return rest (all has been consumed here)
	end
	function socket:onDisconnection()
		if self.error then -- error? or normal disconnection?
			ERROR(self.error)
		end
		NOTE("TCP disconnection")
	end

	local err = socket:connect("localhost",1234)
	if err then ERROR(err) end
	...
	if socket.connected then -- useless if already disconnected
		socket:disconnect()
	end

properties

• connected (read-only), return true if the client is connected, otherwise return false.
• address (read-only), address local of connection for this TCP socket.
• peerAddress (read-only), peer address of connection for this TCP socket.
• error (read-only), return the last error or nil if no error.

methods

• connect(host,port), connect to the host:port indicated. If this method fails, it returns an error message, otherwise it returns nothing.
• disconnect(), shutdown the socket.
• send(data), send data (LUA string).

events

• onReception(data), call on data reception (data is a LUA string). Have to return the number of bytes remaining, it means that if you return #data (size of data received), on the next reception, data will contain precedent value concatenated with new data received.
• onDisconnection(), call on socket disconnection.

TCP Server

Warning This feature requires POCO dependency greater or equal to 1.4.0, otherwise the send of a TCP client method will not work correctly.

To create a TCP server, call cumulus:createTCPServer() method (see cumulus object description on Server Application, API page). Here a complete sample to understand its usage:

	server = cumulus:createTCPServer()
	function server:clientHandler(client)
		-- Here we have a TCPClient object, same usage than TCPClient
		function client:onReception(data)
			NOTE("Reception from "..self.peerAddress.." to "..self.address)
			self:send(data) -- echo sample
			return 0 -- return rest (all has been consumed here)
		end
		function client:onDisconnection()
			NOTE("TCP client disconnection")
		end
	end
	server:start(1234); -- start the server on the port 1234

properties

• port (read-only), return the listening port for the TCP server.
• running (read-only), return true if the TCP server is running.

methods

• start(port), start the TCP server on the port given. This method returns true if successful, otherwise it returns false and displays a ERROR log in CumulusServer logs.
• stop(), stop the TCP server.

events

• clientHandler(client), call on client connection. Client parameter is a TCP client as described in the precedent TCP Client part (see above).

Mails feature

Actually, it boils down to send an email from server application script code. In first, you have to configure a SMTP server in CumulusServer configurations (see Installation page for a complete description of these configurations).

	;CumulusServer.ini
	[smtp]
	host=smtp.isp.com
	port=25
	timeout=60

Then you have to use cumulus.sendMail(sender,subject,content,...) method to send an email from sender to recipients given in the last mutiple arguments field (see cumulus object description on Server Application, API page). It returns a mail object which contains only one event, onSent(error). You can use this event to get one notification on sent, and if error is not null it means that the send has failed.

Here a simple sample:

	mail = cumulus:sendMail("[email protected]","Hello","Mail sent from script code","[email protected]")
	function mail:onSent(err)
		if err then ERROR(err) else NOTE("Sent") end
	end

UDP Socket

To create a UDP socket, call cumulus:createUDPSocket([allowBroadcast]) method (see cumulus object description on Server Application, API page). Here a echo sample to understand its usage:

	socket = cumulus:createUDPSocket()
	function socket:onReception(data,address)
		NOTE("Reception from "..address)
		self:send(data,address) -- echo sample
	end
	err = socket:bind("0.0.0.0:1234") -- start the server
	if error then ERROR(err) end

Following a sample in a client form, in connected mode:

	socket = cumulus:createUDPSocket()
	function socket:onReception(data,address)
		NOTE("Reception from "..address..": "..data)
	end
	socket:connect("0.0.0.0:1234")
	NOTE("UDP socket opened on ",socket.address," connected to ",socket.peerAddress)
	socket:send("salut")

properties

• address (read-only), address local of connection for this UDP socket (returns NULL in an unconnected socket mode)
• peerAddress (read-only), peer address of connection for this UDP socket (returns NULL in an unconnected socket mode)

methods

• connect(address), connect to the address indicated. Then UDP packets can be sent without using address argument in send method (see below).
• bind(address), bind to the address indicated. It can not be done on a connected socket. If this method fails, it returns an error message, otherwise it returns nothing.
• send(data[,address]), send data (LUA string) to the address indicated. This address argument can be omitted if the UDP socket is in a connected mode (see connect method above).
• close(), close the socket.

events

• onReception(data,address), call on data reception (data is a LUA string). The address argument is the sender.

Other protocols

All is possible in a non-blocking mode, and without using LUASocket extension, contact [email protected] if need.