net UDP communication

net UDP communication

Function

net.listen({type: 'udp'}) creates a UDP listening socket, net.connect({type: 'udp'}) creates a UDP socket with the default remote address.

Syntax

The listener configuration field

net.listen({type: 'udp', ...}) uses the following fields:

Field	Type	Required	Default	Description
type	String	Yes	None	Fixed to udp.
bind	String	Yes	None	UDP local listening address in host:port format, such as 127.0.0.1:9001. When the port is 0, the operating system allocates an available port.
binary	Bool	No	false	When true, the message parameter of on_message returns Bytes; the default behavior is to maintain String compatibility.
on_message	Fn	No	None	Called when UDP data is received, the callback parameter is message, remote_addr.
on_error	Fn	No	None	Called when UDP socket error occurs, the callback parameter is message.

Connection configuration field

net.connect({type: 'udp', ...}) creates a UDP socket with the default remote address.

Field	Type	Required	Default value	Description
type	String	Yes	None	Fixed to udp.
host	String	Yes	None	Default remote host name or IP address.
port	Int	Yes	None	Default remote port number.

Return Value

Type	Description
UdpSocket	UDP socket handle. net.listen({type:'udp'}) returns the listening socket, and net.connect({type:'udp'}) returns the socket with the default remote address.

UdpSocket fields and methods

Name	Type	Description
addr	String	UDP socket local address, usually in the format host:port.
type	String	Fixed to udp.
send(data)	Fn -> Int	Send String, byte array or Bytes to the default remote address and return the number of bytes sent; only applicable to sockets created by net.connect.
send(data, addr)	Fn -> Int	Send String, byte array or Bytes to the specified host:port address and return the number of bytes sent.
close()	Fn -> Bool	Close UDP socket, return true successfully.

remote_addr field

remote_addr of on_message(message, remote_addr) is an object, the fields are as follows:

Field	Type	Description
ip	String	Sender IP address. The original address text is retained when the address cannot be resolved.
port	Int/Null	Sender port. null if the address cannot resolve the port.
addr	String	The sender's complete address text, usually ip:port.

Examples

Notes

• The addr of send(data, addr) is optional; when addr is not passed in client mode, the default remote address configured by connect is used.
• The UDP socket in listening mode does not have a default remote address, and calling send(data) will report that the target address is missing; send(data, addr) should be used.
• The default message of on_message is a string; when the listener is configured with binary: true, it is Bytes.
• UDP socket uses the shared Tokio runtime to receive and send messages.

- The UDP receive buffer is limited by BT_NET_MESSAGE_LIMIT, but will not exceed the UDP single message payload limit of 65507 bytes.

• When the network event queue is full, UDP packets will be discarded and BT.stats().net.event_queue_rejected will be added.