Lua Network Library

From Hopmod Wiki

lnetlib, or Lua Network Library, is a Lua module that is being developed for Hopmod that will provide an API for socket-level programming to allow network applications, client or server, to be written and run on Hopmod game servers. The lnetlib module is a loose Lua binding of the Boost.Asio library.

Limitations

• No support for IPv6.
• No support for scatter/gather operations.
• There won't be support for local datagram sockets.

TODO

• Source and sink streams
• ICMP echo requests

API Reference

Top-level classes and functions of the net module

• async_resolve (function)
• tcp_acceptor (class)
• tcp_client (class)
• udp_socket (class)
• local_acceptor (class)
• local_socket (class)
• buffer (function)

net.async_resolve(hostname, completionHandler)

Perform a DNS resolution of the hostname to get an IP address. The result of the resolution is passed as the first argument of the called completionHandler function as an array of IPv4 addresses.

net.tcp_acceptor(ip, port)

Create and return a TCP acceptor/server object. The given ip and port arguments form a local endpoint which is used as the address of the server.

tcp_acceptor:listen()

Enter the listening state on the bound address (local endpoint).

tcp_acceptor:async_accept(completionHandler)

Start an asynchronous accept. The completionHandler function is called when the operation completes, passing a socket object for the new connection.

tcp_acceptor:close()

Close the acceptor socket.

tcp_acceptor.cancel()

Cancel all pending asynchronous operations.

net.tcp_client()

Create and return a TCP socket object for client use. This object inherits functions from the tcp_socket class.

tcp_client:async_connect(ip, port)

Start an asynchronous connect. The ip argument must be an IP address.

tcp_socket:close()

Close the socket.

tcp_socket:cancel()

Cancel all pending asynchronous operations.

tcp_socket:set_option(name, value)

Set a socket option. Options supported are: "keep_alive" and "linger".

socket:set_option("keep_alive", 1) -- enable TCP to send keep-alive packets periodically to check that the remote end of the connection is still alive.
socket:set_option("linger", 1,  10) -- block the process on socket close until the queued output is sent, and give up in 10 seconds. 

tcp_socket:get_option(name)

Get a socket option value.

tcp_socket:local_endpoint()

Get local endpoint information. Returns a table of the form {ip=, port=, iplong=}.

tcp_socket:remote_endpoint()

Get remote endpoint information. Returns a table of the form {ip=, port=, iplong=}.

tcp_socket:async_read(buffer, [readsize], completionHandler)

Start an asynchronous read. Reads readsize or the remaining write capacity of the buffer from the socket to the buffer.

tcp_socket:async_read_until(delim, completionHandler)

Start an asynchronous read. Reads data from a socket until delim is encountered. The read string is passed as the first argument to the called completionHandler function.

tcp_socket:async_send([[buffer, [writesize]] or string], completionHandler)

Start an asynchronous send/write. The function will accept either a string or a buffer as a piece of data to send. The arguments passed to the completionHandler function depend on the input given to this function.

function readBufferHandler(errorMsg)

end

function readUntilHandler(data, errorMsg)
   
   if not data then
       -- use errorMsg
   end

end

tcp_socket:shutdown()

Disable sends and receives on the socket.

tcp_socket:shutdown_send()

Disable sends on the socket.

tcp_socket:shutdown_receive()

Disable receives on the socket.

net.udp_socket()

Create and return a UDP socket object.

udp_socket:close()

Close the socket.

udp_socket:cancel()

Cancel all pending asynchronous operations.

udp_socket:set_option(name, value)

udp_socket:get_option(name)

udp_socket:bind(ip, port)

Bind a socket to a local endpoint. The ip and port arguments given form a local endpoint.

udp_socket:async_read_from(buffer, [commitSize], completionHandler)

Start an asynchronous read. Write commitSize amount or the remaining write capacity of the buffer of data to the buffer, reading the required amount of data from the socket.

function completionHandler(endpoint, errorMsg)
    if not endpoint then
        -- use errorMsg
    end
end

udp_socket:async_send_to(buffer, [consumeSize], remoteEndpoint, completionHandler)

Start an asynchronous send. Read consumeSize amount or the read capacity size of data from the buffer and send it to the specified remote endpoint.

net.buffer(size)

Create and return a buffer for reading and/or writing. The buffer object is useful for binary data manipulation of data sent or received over a socket.

buffer:size()

Returns the size of the buffer in bytes.

buffer:read_left()

Returns the number of bytes that remain to be read.

buffer:write_left()

Returns the number of bytes left for writing.

buffer:reset()

Reset the produced and consumed pointer to the beginning of the buffer. This has the effect of erasing the data but keeping the same memory allocation for reuse.

buffer:to_string()

Consume the remainder of the buffer and return the data as a string.

buffer:read_uint8()

Reads one byte from the buffer and returns the data as a positive integer.

buffer:read_uint16()

Reads three bytes from the buffer and returns the data as a positive integer.

buffer:read_uint32()

Reads four bytes from the buffer and returns the data as a positive integer.

buffer:read_string(n)

Reads n bytes from the buffer and returns the data as a string.

buffer:write_uint8(x)

Writes a one-byte positive integer to the buffer.

buffer:write_uint16(x)

Writes a two-byte positive integer to the buffer.

buffer:write_uint32(x)

Write a four-byte positive integer to the buffer.

buffer:write_string(x)

Write a string to the buffer.