eLua reference manual - net module

Overview

This module contains functions for accessing a TCP/IP network from eLua. It can be enabled only if networking support is also enabled (see building for details).

NOTE: TCP/IP support is experimental in eLua. While functional, it's still slow and suffers from a number of other issues. It will most likely change a lot in the future, so expect major changes to this module as well.

NOTE: currently, only TCP sockets are supported by eLua.

Data structures, constants and types

// eLua net error codes
enum
{
  ELUA_NET_ERR_OK = 0,            // exported as net.ERR_OK
  ELUA_NET_ERR_TIMEDOUT,          // exported as net.ERR_TIMEDOUT
  ELUA_NET_ERR_CLOSED,            // exported as net.ERR_CLOSED
  ELUA_NET_ERR_ABORTED,           // exported as net.ERR_ABORTED
  ELUA_NET_ERR_OVERFLOW           // exported as net.ERR_OVERFLOW
};

These are the error codes defined by the eLua networking layer and they are also returned by a number of functions in this module.

Functions

net.packip net.packip net.unpackip net.unpackip net.lookup net.socket net.close net.connect net.accept net.send net.recv

ip = net.packip( ip1, ip2, ip3, ip4 )

Returns an internal representation of an IP address that can be used with all function from the net module that expect an IP address argument. The IP is considered to be in the format ip1.ip2.ip3.ip4.

Arguments:

  • ip1 - the first part of the IP address.
  • ip2 - the second part of the IP address.
  • ip3 - the third part of the IP address.
  • ip4 - the fourth part of the IP address.

Returns: An integer that encodes the IP address in an internal format.

ip = net.packip( 'ip' )

Returns an internal representation of an IP address that can be used with all function from the net module that expect an IP address argument. The IP is given as a string.

Arguments: ip - the IP address in string format.

Returns: An integer that encodes the IP address in an internal format.

ip1, ip2, ip3, ip4 = net.unpackip( ip, '*n' )

Returns an unpacked representation of an IP address encoded by net.packip.

Arguments: ip - the encoded IP address.

Returns:

  • ip1 - the first part of the IP address.
  • ip2 - the second part of the IP address.
  • ip3 - the third part of the IP address.
  • ip4 - the fourth part of the IP address.

ip = net.unpackip( ip, '*s' )

Returns an unpacked representation of an IP address encoded by net.packip.

Arguments: ip - the encoded IP address.

Returns: The IP address in string format.

ip = net.lookup( hostname )

Does a DNS lookup.

Arguments: hostname - the name of the computer.

Returns: The IP address of the computer.

socket = net.socket( type )

Create a socket for TCP/IP communication.

Arguments: type - can be either net.SOCK_STREAM for TCP sockets or net.SOCK_DGRAM for UDP sockets (not yet supported).

Returns: The socket that will be used in subsequent operations.

res = net.close( socket )

Close a socket.

Arguments: socket - the socket to close.

Returns: An error code, as defined here.

err = net.connect( sock, ip, port )

Connect a socket to a remote system.

Arguments:

Returns: err - the error code, as defined here.

socket, remoteip, err = net.accept( port, [timer_id, timeout] )

Accept a connection from a remote system with an optional timeout.

Arguments:

  • port - the port to wait for connections from the remote system.
  • timer_id (optional) - the timer ID of the timer used to timeout the accept function after a specified time. If this is specified, timeout must also be specified.
  • timeout (optional) - the timeout after which the accept function returns if no connection was requested. If this is specified, timer_id must also be specified.

Returns:

res, err = net.send( sock, str )

Send data to a socket.

Arguments:

  • sock - the socket.
  • str - the data to send.

Returns:

res, err = net.recv( sock, format, [timer_id, timeout] )

Read data from a socket.

Arguments:

  • sock - the socket.
  • format - how to read the data. This can be either:
    • "*l": read a line (until the next '\n' character).
    • an integer: read up to that many bytes.
  • timer_id (optional) - the timer ID of the timer used to timeout the recv function after a specified time. If this is specified, timeout must also be specified.
  • timeout (optional) - the timeout after which the recv function returns if no connection was requested. If this is specified, timer_id must also be specified.

Returns: