#hs.socket.udp
Talk to custom protocols using asynchronous UDP sockets.
For TCP sockets see hs.socket
.
You can do a lot of neat trivial and non-trivial things with these. A simple ping ponger:
function ping(data, addr) print(data) addr = hs.socket.parseAddress(addr) hs.timer.doAfter(1, function() client:send("ping", addr.host, addr.port) end) end function pong(data, addr) print(data) addr = hs.socket.parseAddress(addr) hs.timer.doAfter(1, function() server:send("pong", addr.host, addr.port) end) end server = hs.socket.udp.server(9001, pong):receive() client = hs.socket.udp.new(ping):send("ping", "localhost", 9001):receive()
Resulting in the following endless exchange:
20:26:56 LuaSkin: (secondary thread): Data written to UDP socket LuaSkin: (secondary thread): Data read from UDP socket ping 20:26:57 LuaSkin: (secondary thread): Data written to UDP socket LuaSkin: (secondary thread): Data read from UDP socket pong 20:26:58 LuaSkin: (secondary thread): Data written to UDP socket LuaSkin: (secondary thread): Data read from UDP socket ping 20:26:59 LuaSkin: (secondary thread): Data written to UDP socket LuaSkin: (secondary thread): Data read from UDP socket pong ...
You can do some silly things with a callback factory and enabling broadcasting:
local function callbackMaker(name) local fun = function(data, addr) addr = hs.socket.parseAddress(addr) print(name.." received data:\n"..data.."\nfrom host: "..addr.host.." port: "..addr.port) end return fun end local listeners = {} local port = 9001 for i=1,3 do table.insert(listeners, hs.socket.udp.new(callbackMaker("listener "..i)):reusePort():listen(port):receive()) end broadcaster = hs.socket.udp.new():broadcast() broadcaster:send("hello!", "255.255.255.255", port)
Since neither IPv4 nor IPv6 have been disabled, the broadcast is received on both protocols ('dual-stack' IPv6 addresses shown):
listener 2 received data: hello! from host: ::ffff:192.168.0.3 port: 53057 listener 1 received data: hello! from host: ::ffff:192.168.0.3 port: 53057 listener 3 received data: hello! from host: ::ffff:192.168.0.3 port: 53057 listener 1 received data: hello! from host: 192.168.0.3 port: 53057 listener 3 received data: hello! from host: 192.168.0.3 port: 53057 listener 2 received data: hello! from host: 192.168.0.3 port: 53057
#API Overview
Variables - Configurable values
Functions - API calls offered directly by the extension
Constructors - API calls which return an object, typically one that offers API methods
Methods - API calls which can only be made on an object returned by a constructor
- broadcast
- close
- closed
- connect
- connected
- enableIPv
- info
- listen
- pause
- preferIPv
- read
- readOne
- receive
- receiveOne
- reusePort
- send
- setBufferSize
- setCallback
- setTimeout
- write
#API Documentation
#Variables
Signature | hs.socket.udp.timeout |
Type | Variable |
Description | Timeout for the socket operations, in seconds. |
Notes |
|
Source | extensions/socket/socket.lua line 173 |
#Functions
Signature | hs.socket.udp.parseAddress(sockaddr) -> table or nil |
Type | Function |
Description | Alias for hs.socket.parseAddress |
Parameters | |
Returns | |
Notes | None |
Source | extensions/socket/socket.lua line 184 |
#Constructors
Signature | hs.socket.udp.new([fn]) -> hs.socket.udp object |
Type | Constructor |
Description | Creates an unconnected asynchronous UDP socket object. |
Parameters |
|
Returns |
|
Notes | None |
Examples | None |
Source | extensions/socket/libsocket_udp.m line 111 |
Signature | hs.socket.udp.server(port[, fn]) -> hs.socket.udp object |
Type | Constructor |
Description | Creates a UDP socket, and binds it to a port for listening. |
Parameters |
|
Returns |
|
Notes | None |
Examples | None |
Source | extensions/socket/socket.lua line 208 |
#Methods
Signature | hs.socket.udp:broadcast([flag]) -> self or nil |
Type | Method |
Description | Enables broadcasting on the underlying socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 418 |
Signature | hs.socket.udp:close() -> self |
Type | Method |
Description | Immediately closes the socket, freeing it for reuse. Any pending send operations are discarded. |
Parameters |
|
Returns |
|
Notes | None |
Examples | None |
Source | extensions/socket/libsocket_udp.m line 222 |
Signature | hs.socket.udp:closed() -> bool |
Type | Method |
Description | Returns the closed status of the socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 675 |
Signature | hs.socket.udp:connect(host, port[, fn]) -> self or nil |
Type | Method |
Description | Connects an unconnected socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 145 |
Signature | hs.socket.udp:connected() -> bool |
Type | Method |
Description | Returns the connection status of the socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 652 |
Signature | hs.socket.udp:enableIPv(version[, flag]) -> self or nil |
Type | Method |
Description | Enables or disables IPv4 or IPv6 on the underlying socket. By default, both are enabled. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 486 |
Signature | hs.socket.udp:info() -> table |
Type | Method |
Description | Returns information about the socket. |
Parameters |
|
Returns |
|
Notes | None |
Examples | None |
Source | extensions/socket/libsocket_udp.m line 699 |
Signature | hs.socket.udp:listen(port) -> self or nil |
Type | Method |
Description | Binds an unconnected socket to a port for listening. |
Parameters |
|
Returns |
|
Notes | None |
Examples | None |
Source | extensions/socket/libsocket_udp.m line 192 |
Signature | hs.socket.udp:pause() -> self |
Type | Method |
Description | Suspends reading of packets from the socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 243 |
Signature | hs.socket.udp:preferIPv([version]) -> self |
Type | Method |
Description | Sets the preferred IP version: IPv4, IPv6, or neutral (first to resolve). |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 523 |
Signature | hs.socket.udp:read(delimiter[, tag]) -> self |
Type | Method |
Description | Alias for hs.socket.udp:receive |
Parameters | |
Returns | |
Notes | None |
Source | extensions/socket/socket.lua line 237 |
Signature | hs.socket.udp:readOne(delimiter[, tag]) -> self |
Type | Method |
Description | Alias for hs.socket.udp:receiveOne |
Parameters | |
Returns | |
Notes | None |
Source | extensions/socket/socket.lua line 243 |
Signature | hs.socket.udp:receive([fn]) -> self or nil |
Type | Method |
Description | Reads packets from the socket as they arrive. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 295 |
Signature | hs.socket.udp:receiveOne([fn]) -> self or nil |
Type | Method |
Description | Reads a single packet from the socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 321 |
Signature | hs.socket.udp:reusePort([flag]) -> self or nil |
Type | Method |
Description | Enables port reuse on the socket. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 452 |
Signature | hs.socket.udp:send(message[, host, port][, tag, fn]) -> self |
Type | Method |
Description | Sends a packet to the destination address. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 347 |
Signature | hs.socket.udp:setBufferSize(size[, version]) -> self |
Type | Method |
Description | Sets the maximum size of the buffer that will be allocated for receive operations. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 555 |
| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.socket.udp:setCallback([fn]) -> self
| | Type | Method | | Description | Sets the read callback for the socket. | | Parameters |
fn
- An optional callback function to process data read from the socket.nil
or no argument clears the callback. The callback receives 2 parameters:data
- The data read from the socket as a string.sockaddr
- The sending address as a binary socket address structure. SeeparseAddress
.
- The
hs.socket.udp
object.
- A callback must be set in order to read data from the socket.
Signature | hs.socket.udp:setTimeout(timeout) -> self |
Type | Method |
Description | Sets the timeout for the socket operations. |
Parameters |
|
Returns |
|
Notes |
|
Examples | None |
Source | extensions/socket/libsocket_udp.m line 628 |
Signature | hs.socket.udp:write(message[, tag]) -> self |
Type | Method |
Description | Alias for hs.socket.udp:send |
Parameters | |
Returns | |
Notes | None |
Source | extensions/socket/socket.lua line 249 |