Skip to content

class UDPSocketGeneric

methods

UDPSocketGeneric.close

function UDPSocketGeneric.close()

Closes a UDP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket.

Note: It is important to close all used sockets once they are not needed, since, in many systems, each socket uses a file descriptor, which are limited system resources. Garbage-collected objects are automatically closed before destruction, though.

😱 Types incomplete or incorrect? 🙏 Please contribute!

UDPSocketGeneric.getoption

function UDPSocketGeneric.getoption(option: UDPOption)
 ->  any
 ->  SocketReturnError

Gets an option value from the UDP object.

Option is a string with the option name.

The method returns the option value in case of success, or nil followed by an error message otherwise.

UDPSocketGeneric.getsockname

function UDPSocketGeneric.getsockname()
 ->  string?
 ->  number?
 ->  SocketFamily?

Returns the local address information associated to the object.

The method returns a string with local IP address, a number with the local port, and a string with the family ("inet" or "inet6"). In case of error, the method returns nil.

Note: UDP sockets are not bound to any address until the setsockname or the sendto method is called for the first time (in which case it is bound to an ephemeral port and the wild-card address).

UDPSocketGeneric.gettimeout

function UDPSocketGeneric.gettimeout() -> timeout number

Returns the current timeout value.

UDPSocketGeneric.receive

function UDPSocketGeneric.receive(size: number?)
 -> datagram Datagram?
 -> err "timeout"?

@return err - 'timeout' in case of timeout

😱 Types incomplete or incorrect? 🙏 Please contribute!

Receives a datagram from the UDP object. If the UDP object is connected, only datagrams coming from the peer are accepted. Otherwise, the returned datagram can come from any host.

The optional size parameter specifies the maximum size of the datagram to be retrieved. If there are more than size bytes available in the datagram, the excess bytes are discarded. If there are less then size bytes available in the current datagram, the available bytes are returned. If size is omitted, the compile-time constant socket._DATAGRAMSIZE is used (it defaults to 8192 bytes). Larger sizes will cause a temporary buffer to be allocated for the operation.

In case of success, the method returns the received datagram. In case of timeout, the method returns nil followed by the string 'timeout'.

Note: don't call this from unconnected sockets. Since you wont be able to know where it came from. Use receivefrom instead.

UDPSocketGeneric.setoption

function UDPSocketGeneric.setoption(
  option: UDPOption,
  value: any
)
 ->  SocketReturnResult
 ->  SocketReturnError

Sets options for the UDP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.

Option is a string with the option name, and value depends on the option being set

The method returns 1 in case of success, or nil followed by an error message otherwise.

UDPSocketGeneric.setpeername

function UDPSocketGeneric.setpeername(
  address: string,
  port: number
)
 ->  SocketReturnResult
 ->  SocketReturnError
@param address - can be a host name

Changes the peer of a UDP object. This method turns an unconnected UDP object into a connected UDP object or vice versa.

For connected objects, outgoing datagrams will be sent to the specified peer, and datagrams received from other peers will be discarded by the OS. Connected UDP objects must use the send and receive methods instead of sendto and receivefrom.

Address can be an IP address or a host name. Port is the port number. If address is '*' and the object is connected, the peer association is removed and the object becomes an unconnected object again. In that case, the port argument is ignored.

In case of error the method returns nil followed by an error message. In case of success, the method returns 1.

Note: Since the address of the peer does not have to be passed to and from the OS, the use of connected UDP objects is recommended when the same peer is used for several transmissions and can result in up to 30% performance gains.

Note: Starting with LuaSocket 3.0, the host name resolution depends on whether the socket was created by socket.udp or socket.udp6. Addresses from the appropriate family are tried in succession until the first success or until the last failure.

UDPSocketGeneric.setpeername

function UDPSocketGeneric.setpeername(address: "*")
 ->  SocketReturnResult
 ->  SocketReturnError
@param address - will turn it unconnected

Changes the peer of a UDP object. This method turns an unconnected UDP object into a connected UDP object or vice versa.

For connected objects, outgoing datagrams will be sent to the specified peer, and datagrams received from other peers will be discarded by the OS. Connected UDP objects must use the send and receive methods instead of sendto and receivefrom.

Address can be an IP address or a host name. Port is the port number. If address is '*' and the object is connected, the peer association is removed and the object becomes an unconnected object again. In that case, the port argument is ignored.

In case of error the method returns nil followed by an error message. In case of success, the method returns 1.

Note: Since the address of the peer does not have to be passed to and from the OS, the use of connected UDP objects is recommended when the same peer is used for several transmissions and can result in up to 30% performance gains.

Note: Starting with LuaSocket 3.0, the host name resolution depends on whether the socket was created by socket.udp or socket.udp6. Addresses from the appropriate family are tried in succession until the first success or until the last failure.

UDPSocketGeneric.setsockname

function UDPSocketGeneric.setsockname(
  address,
  port
)
 ->  SocketReturnResult
 ->  SocketReturnError

Binds the UDP object to a local address.

Address can be an IP address or a host name. If address is '*' the system binds to all local interfaces using the constant INADDR_ANY. If port is 0, the system chooses an ephemeral port.

If successful, the method returns 1. In case of error, the method returns nil followed by an error message.

Note: This method can only be called before any datagram is sent through the UDP object, and only once. Otherwise, the system automatically binds the object to all local interfaces and chooses an ephemeral port as soon as the first datagram is sent. After the local address is set, either automatically by the system or explicitly by setsockname, it cannot be changed.

UDPSocketGeneric.settimeout

function UDPSocketGeneric.settimeout(timeout: number)

Sets the timeout value for the socket

Sets the time to blocks the process when calling receive and receivefrom until the timeout is reached or a packet arrives.