net UDP 通信

net UDP 通信

net UDP 通信

功能

net.listen({type: 'udp'}) 创建 UDP 监听 socket,net.connect({type: 'udp'}) 创建带默认远端地址的 UDP socket。

语法

监听配置字段

net.listen({type: 'udp', ...}) 使用以下字段:

字段类型必填默认值说明
typeString固定为 udp
bindStringUDP 本地监听地址,格式为 主机:端口,例如 127.0.0.1:9001。端口写 0 时由系统分配空闲端口。
binaryBoolfalse为 true 时,on_message 的 message 参数返回 Bytes;默认保持 String 兼容行为。
on_messageFn收到 UDP 数据时调用,回调参数为 message, remote_addr
on_errorFnUDP socket 出错时调用,回调参数为 message

连接配置字段

net.connect({type: 'udp', ...}) 创建带默认远端地址的 UDP socket。

字段类型必填默认值说明
typeString固定为 udp
hostString默认远端主机名或 IP 地址。
portInt默认远端端口号。

返回值

类型说明
UdpSocketUDP socket 句柄。net.listen({type:'udp'}) 返回监听 socket,net.connect({type:'udp'}) 返回带默认远端地址的 socket。

UdpSocket 字段和方法

名称类型说明
addrStringUDP socket 本地地址,格式通常为 host:port
typeString固定为 udp
send(data)Fn -> Int向默认远端地址发送 String、字节数组或 Bytes,返回发送字节数;只适用于 net.connect 创建的 socket。
send(data, addr)Fn -> Int向指定 host:port 地址发送 String、字节数组或 Bytes,返回发送字节数。
close()Fn -> Bool关闭 UDP socket,成功返回 true。

remote_addr 字段

on_message(message, remote_addr)remote_addr 是对象,字段如下:

字段类型说明
ipString发送方 IP 地址。地址无法解析时保留原始地址文本。
portInt/Null发送方端口。地址无法解析端口时为 null。
addrString发送方完整地址文本,通常为 ip:port

示例

注意事项

  • send(data, addr) 的 addr 可选;客户端模式未传 addr 时使用 connect 配置的默认远端地址。
  • 监听模式的 UDP socket 没有默认远端地址,调用 send(data) 会报缺少目标地址;应使用 send(data, addr)。
  • 默认 on_message 的 message 是字符串;监听配置 binary: true 时为 Bytes。
  • UDP socket 使用共享 Tokio runtime 接收和发送报文。
  • UDP 接收缓冲受 BT_NET_MESSAGE_LIMIT 限制,但不会超过 UDP 单报文有效负载上限 65507 字节。
  • 网络事件队列满时,UDP 报文会被丢弃,并增加 BT.stats().net.event_queue_rejected