net UDP 通信
net UDP 通信
功能
net.listen({type: 'udp'}) 创建 UDP 监听 socket,net.connect({type: 'udp'}) 创建带默认远端地址的 UDP socket。
语法
server = net.listen({ type: 'udp', bind: '127.0.0.1:9001', on_message: fn(message, remote_addr) {}, on_error: fn(message) {} }) client = net.connect({type: 'udp', host: '127.0.0.1', port: 9001}) client.send('ping') client.close()
监听配置字段
net.listen({type: 'udp', ...}) 使用以下字段:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type | String | 是 | 无 | 固定为 udp。 |
| bind | String | 是 | 无 | UDP 本地监听地址,格式为 主机:端口,例如 127.0.0.1:9001。端口写 0 时由系统分配空闲端口。 |
| binary | Bool | 否 | false | 为 true 时,on_message 的 message 参数返回 Bytes;默认保持 String 兼容行为。 |
| on_message | Fn | 否 | 无 | 收到 UDP 数据时调用,回调参数为 message, remote_addr。 |
| on_error | Fn | 否 | 无 | UDP socket 出错时调用,回调参数为 message。 |
连接配置字段
net.connect({type: 'udp', ...}) 创建带默认远端地址的 UDP socket。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type | String | 是 | 无 | 固定为 udp。 |
| host | String | 是 | 无 | 默认远端主机名或 IP 地址。 |
| port | Int | 是 | 无 | 默认远端端口号。 |
返回值
| 类型 | 说明 |
|---|---|
| UdpSocket | UDP socket 句柄。net.listen({type:'udp'}) 返回监听 socket,net.connect({type:'udp'}) 返回带默认远端地址的 socket。 |
UdpSocket 字段和方法
| 名称 | 类型 | 说明 |
|---|---|---|
| addr | String | UDP socket 本地地址,格式通常为 host:port。 |
| type | String | 固定为 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 是对象,字段如下:
| 字段 | 类型 | 说明 |
|---|---|---|
| ip | String | 发送方 IP 地址。地址无法解析时保留原始地址文本。 |
| port | Int/Null | 发送方端口。地址无法解析端口时为 null。 |
| addr | String | 发送方完整地址文本,通常为 ip:port。 |
示例
// 创建 UDP 客户端 socket,并把默认远端地址设为 127.0.0.1:9001。 socket = net.connect({ type: 'udp', host: '127.0.0.1', port: 9001 }) result = socket.type socket.close() // 输出:udp print result
注意事项
- 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。