MCServer/Plugins/APIDump/Classes/Network.lua

@@ -0,0 +1,183 @@

-- Network.lua

-- Defines the documentation for the cNetwork-related classes





return
{
	cNetwork =
	{
		Desc =
		[[
			This is the namespace for high-level network-related operations. Allows plugins to make TCP
			connections to the outside world using a callback-based API.</p>
			<p>
			All functions in this namespace are static, they should be called on the cNetwork class itself:
<pre class="prettyprint lang-lua">
local Server = cNetwork:Listen(1024, ListenCallbacks);
</pre></p>
		]],
		AdditionalInfo =
		{
			{
				Header = "Using callbacks",
				Contents =
				[[
					The entire Networking API is callback-based. Whenever an event happens on the network object, a
					specific plugin-provided function is called. The callbacks are stored in tables which are passed
					to the API functions, each table contains multiple callbacks for the various situations.</p>
					<p>
					There are three different callback variants used: LinkCallbacks, LookupCallbacks and
					ListenCallbacks. Each is used in the situation appropriate by its name - LinkCallbacks are used
					for handling the traffic on a single network link (plus additionally creation of such link when
					connecting as a client), LookupCallbacks are used when doing DNS and reverse-DNS lookups, and
					ListenCallbacks are used for handling incoming connections as a server.</p>
					<p>
					LinkCallbacks have the following structure:<br/>
<pre class="prettyprint lang-lua">
local LinkCallbacks =
{
	OnConnected = function ({{cTCPLink|a_TCPLink}})
		-- The specified {{cTCPLink|link}} has succeeded in connecting to the remote server.
		-- Only called if the link is being connected as a client (using cNetwork:Connect() )
		-- Not used for incoming server links
		-- All returned values are ignored
	end,
	
	OnError = function ({{cTCPLink|a_TCPLink}}, a_ErrorCode, a_ErrorMsg)
		-- The specified error has occured on the {{cTCPLink|link}}
		-- No other callback will be called for this link from now on
		-- For a client link being connected, this reports a connection error (destination unreachable etc.)
		-- It is an Undefined Behavior to send data to a_TCPLink in or after this callback
		-- All returned values are ignored
	end,
	
	OnReceivedData = function ({{cTCPLink|a_TCPLink}}, a_Data)
		-- Data has been received on the {{cTCPLink|link}}
		-- Will get called whenever there's new data on the {{cTCPLink|link}}
		-- a_Data contains the raw received data, as a string
		-- All returned values are ignored
	end,
	
	OnRemoteClosed = function ({{cTCPLink|a_TCPLink}})
		-- The remote peer has closed the {{cTCPLink|link}}
		-- The link is already closed, any data sent to it now will be lost
		-- No other callback will be called for this link from now on
		-- All returned values are ignored
	end,
}
</pre></p>
				<p>
				LookupCallbacks have the following structure:<br/>
<pre class="prettyprint lang-lua">
local LookupCallbacks =
{
	OnError = function (a_Query, a_ErrorCode, a_ErrorMsg)
		-- The specified error has occured while doing the lookup
		-- a_Query is the hostname or IP being looked up
		-- No other callback will be called for this lookup from now on
		-- All returned values are ignored
	end,

	OnFinished = function (a_Query)
		-- There are no more DNS records for this query
		-- a_Query is the hostname or IP being looked up
		-- No other callback will be called for this lookup from now on
		-- All returned values are ignored
	end,

	OnNameResolved = function (a_Hostname, a_IP)
		-- A DNS record has been found, the specified hostname resolves to the IP
		-- Called for both Hostname -&gt; IP and IP -&gt; Hostname lookups
		-- May be called multiple times if a hostname resolves to multiple IPs
		-- All returned values are ignored
	end,
}
</pre></p>
				<p>
				ListenCallbacks have the following structure:<br/>
<pre class="prettyprint lang-lua">
local ListenCallbacks =
{
	OnAccepted = function ({{cTCPLink|a_TCPLink}})
		-- A new connection has been accepted and a {{cTCPLink|Link}} for it created
		-- It is safe to send data to the link now
		-- All returned values are ignored
	end,
	
	OnError = function (a_ErrorCode, a_ErrorMsg)
		-- The specified error has occured while trying to listen
		-- No other callback will be called for this lookup from now on
		-- This callback is called before the cNetwork:Listen() call returns
		-- All returned values are ignored
	end,

	OnIncomingConnection = function (a_RemoteIP, a_RemotePort, a_LocalPort)
		-- A new connection is being accepted, from the specified remote peer
		-- This function needs to return either nil to drop the connection,
		-- or valid LinkCallbacks to use for the new connection's {{cTCPLink|TCPLink}} object
		return SomeLinkCallbacks
	end,
}
</pre></p>
				]],
			},
		},  -- AdditionalInfo
		
		Functions =
		{
				Connect = { Params = "Host, Port, LinkCallbacks", Return = "bool", Notes = "(STATIC) Begins establishing a (client) TCP connection to the specified host. Uses the LinkCallbacks table to report progress, success, errors and incoming data. Returns false if it fails immediately (bad port value, bad hostname format), true otherwise. Host can be either an IP address or a hostname." },
				HostnameToIP = { Params = "Host, LookupCallbacks", Return = "bool", Notes = "(STATIC) Begins a DNS lookup to find the IP address(es) for the specified host. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad hostname format), true if the lookup started successfully. Host can be either a hostname or an IP address." },
				IPToHostname = { Params = "Address, LookupCallbacks", Return = "bool", Notes = "(STATIC) Begins a reverse-DNS lookup to find out the hostname for the specified IP address. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad address format), true if the lookup started successfully." },
				Listen = { Params = "Port, ListenCallbacks", Return = "{{cServerHandle|ServerHandle}}", Notes = "(STATIC) Starts listening on the specified port. Uses the ListenCallbacks to report incoming connections or errors. Returns a {{cServerHandle}} object representing the server. If the listen operation failed, the OnError callback is called with the error details and the returned server handle will report IsListening() == false. The plugin needs to store the server handle object for as long as it needs the server running, if the server handle is garbage-collected by Lua, the listening socket will be closed and all current connections dropped." },
		},
	},  -- cNetwork
	
	cTCPLink =
	{
		Desc =
		[[
			This class wraps a single TCP connection, that has been established. Plugins can create these by
			calling {{cNetwork}}:Connect() to connect to a remote server, or by listening using
			{{cNetwork}}:Listen() and accepting incoming connections. The links are callback-based - when an event
			such as incoming data or remote disconnect happens on the link, a specific callback is called. See the
			additional information in {{cNetwork}} documentation for details.
		]],
		
		Functions =
		{
			GetLocalIP = { Params = "", Return = "string", Notes = "Returns the IP address of the local endpoint of the TCP connection." },
			GetLocalPort = { Params = "", Return = "number", Notes = "Returns the port of the local endpoint of the TCP connection." },
			GetRemoteIP = { Params = "", Return = "string", Notes = "Returns the IP address of the remote endpoint of the TCP connection." },
			GetRemotePort = { Params = "", Return = "number", Notes = "Returns the port of the remote endpoint of the TCP connection." },
			Send = { Params = "Data", Return = "", Notes = "Sends the data (raw string) to the remote peer. The data is sent asynchronously and there is no report on the success of the send operation, other than the connection being closed or reset by the underlying OS." },
		},
	},  -- cTCPLink

	cServerHandle =
	{
		Desc =
		[[
			This class provides an interface for TCP sockets listening for a connection. In order to listen, the
			plugin needs to use the {{cNetwork}}:Listen() function to create the listening socket.</p>
			<p>
			Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin
			should keep it referenced in a global variable for as long as it wants the server running.
		]],
		
		Functions =
		{
			Close = { Params = "", Return = "", Notes = "Closes the listening socket. No more connections will be accepted, and all current connections will be closed." },
			IsListening = { Params = "", Return = "bool", Notes = "Returns true if the socket is listening." },
		},

	},  -- cServerHandle
}

MCServer/Plugins/NetworkTest/NetworkTest.lua

@@ -20,14 +20,14 @@ local g_Fortunes =
}

--- Map of all services that can be run as servers
-- g_Services[ServiceName] = function() -> callbacks
-- g_Services[ServiceName] = function() -> accept-callbacks
local g_Services =
{
	-- Echo service: each connection echoes back what has been sent to it
	echo = function (a_Port)
		return
		{
			-- A new connection has come, give it new link callbacks:
			-- A new connection has come, give it new link-callbacks:
			OnIncomingConnection = function (a_RemoteIP, a_RemotePort)
				return
				{
@@ -57,10 +57,11 @@ local g_Services =
		}  -- Listen callbacks
	end,  -- echo
	
	-- Fortune service: each incoming connection gets a welcome message plus a random fortune text; all communication is ignored afterwards
	fortune = function (a_Port)
		return
		{
			-- A new connection has come, give it new link callbacks:
			-- A new connection has come, give it new link-callbacks:
			OnIncomingConnection = function (a_RemoteIP, a_RemotePort)
				return
				{
@@ -77,7 +78,7 @@ local g_Services =
				}  -- Link callbacks
			end,  -- OnIncomingConnection()
			
			-- Send a welcome message to newly accepted connections:
			-- Send a welcome message and the fortune to newly accepted connections:
			OnAccepted = function (a_Link)
				a_Link:Send("Hello, " .. a_Link:GetRemoteIP() .. ", welcome to the fortune server @ MCServer-Lua\r\n\r\nYour fortune:\r\n")
				a_Link:Send(g_Fortunes[math.random(#g_Fortunes)] .. "\r\n")
@@ -90,17 +91,19 @@ local g_Services =
		}  -- Listen callbacks
	end,  -- fortune
	
	-- TODO: Other services (fortune, daytime, ...)
	-- TODO: Other services (daytime, ...)
}





function Initialize(a_Plugin)
	-- Load the splashes.txt file into g_Fortunes:
	-- Load the splashes.txt file into g_Fortunes, overwriting current content:
	local idx = 1
	for line in io.lines(a_Plugin:GetLocalFolder() .. "/splashes.txt") do
		table.insert(g_Fortunes, line)
		g_Fortunes[idx] = line
		idx = idx + 1
	end
	
	-- Use the InfoReg shared library to process the Info.lua file:

src/Bindings/ManualBindings_Network.cpp

@@ -218,7 +218,7 @@ static int tolua_cNetwork_Listen(lua_State * L)
static int tolua_cTCPLink_Send(lua_State * L)
{
	// Function signature:
	// LinkInstance:Send(DataString) -> bool
	// LinkInstance:Send(DataString)

	cLuaState S(L);
	if (