TCP类

Y++ / YStudio 开发文档 · 一点滴

类对象支持库（不是扁平命令）。路径：支持库 → 扩展类库 → TCP类。

类型名必须写完整「TCP类」。声明时自动创建，一般无需再调 创建*。

硬约束

类型名必须写「TCP类」。
客户端/服务端能力以方法与事件表为准；事件在 UI 线程时勿长时间阻塞。
TLS 等相关方法按签名使用。

快速开始

TCP类 tcp
// 连接 / 发送 / 事件：见下方命令介绍

TCP类/创建

共 1 条。

`创建TCP`

签名：通用创建TCP()
说明：创建一个 TCP 会话。一般直接写「TCP类 t」即可（声明时自动创建）；「创建TCP()」仅在需要显式赋值时使用。

TCP类/事件

共 9 条。

`客户进入`

签名：无客户进入(子程序指针回调)
说明：注册「有客户端接入 / 异步连接成功」回调；传 0 清除。（推荐名；旧名「用户进入」仍可用）
参数一│子程序指针回调: 须指向已定义函数。形参固定为：函数名(整数连接ID, 文本 IP, 整数端口, 文本 IP端口) · 服务端：accept 成功；连接ID>0；IP/端口为对端（连接时缓存）。 · 客户端：异步连接() 成功；连接ID=1。 · 同步连接_同步成功不触发。 · 不需要的参数可声明后不用；回发必须用连接ID。

`用户进入`

签名：无用户进入(子程序指针回调)
说明：同「客户进入」（兼容旧名）。回调形参已升级为带 IP/端口。
参数一│子程序指针回调: 形参同客户进入。

`数据到达`

签名：无数据到达(子程序指针回调)
说明：注册「收到文本」回调；传 0 清除。
参数一│子程序指针回调: 形参固定为：函数名(整数连接ID, 文本 IP, 整数端口, 文本 IP端口, 文本数据) · 分包模式 0：可能粘包/半包；1/2：完整一帧。 · 二进制用「数据到达字节集」；可与文本回调同时注册。 · 对端地址连接时已缓存，回调零开销带上；也可取客户IP(id) 再查。

`数据到达字节集`

签名：无数据到达字节集(子程序指针回调)
说明：注册「收到原始字节」回调；传 0 清除。与「数据到达」互补，可同时注册。
参数一│子程序指针回调: 形参固定为：函数名(整数连接ID, 文本 IP, 整数端口, 文本 IP端口, 字节集数据)

`发送进度`

签名：无发送进度(子程序指针回调)
说明：注册「发送文件进度」回调；传 0 清除。由「发送文件」触发。
参数一│子程序指针回调: 形参固定为：函数名(整数连接ID, 长整数已发送, 长整数总计)。 · 开始时会先报一次 (0, 总计)；之后每发出一块再报。 · 空文件也会报 (0, 0)。

`发送完毕`

签名：无发送完毕(子程序指针回调)
说明：注册「发送文件结束」回调；传 0 清除。成功或失败都会触发。
参数一│子程序指针回调: 形参固定为：函数名(整数连接ID, 逻辑成功, 文本错误)。 · 成功：成功=真，错误为空文本。 · 失败：成功=假，错误为原因（打开失败/读失败/发送失败/已取消等）。 · 断开、关闭全部会取消进行中的发送文件并触发失败。

`客户离开`

签名：无客户离开(子程序指针回调)
说明：注册「连接断开」回调；传 0 清除。（推荐名；旧名「用户离开」仍可用）
参数一│子程序指针回调: 形参固定为：函数名(整数连接ID, 文本 IP, 整数端口, 文本 IP端口) 对端关闭、本端断开、关闭全部、网络错误时触发；地址为断开前缓存。

`用户离开`

签名：无用户离开(子程序指针回调)
说明：同「客户离开」（兼容旧名）。回调形参已升级为带 IP/端口。
参数一│子程序指针回调: 形参同客户离开。

`连接失败`

签名：无连接失败(子程序指针回调)
说明：注册「异步连接失败」回调（仅客户端连接使用）；传 0 清除。
参数一│子程序指针回调: 形参固定为：函数名(文本原因)。仅连接()（异步）失败时触发；连接_同步失败看返回值与取错误()。

TCP类/属性

共 15 条。

`超时`

签名：整数超时
说明：当前超时毫秒数（无括号属性读，等价取超时()）。

`错误信息`

签名：文本错误信息
说明：最近失败原因（无括号属性读）。

`模式`

签名：文本模式
说明：「客户端」「服务端」或「空闲」。

`是否已连接`

签名：逻辑是否已连接
说明：客户端是否仍保持连接。

`是否在监听`

签名：逻辑是否在监听
说明：服务端是否正在监听。

`是否连接中`

签名：逻辑是否连接中
说明：异步连接是否进行中。

`客户端数`

签名：整数客户端数
说明：服务端当前在线连接数。

`端口`

签名：整数端口
说明：当前端口（服务端=监听端口，客户端=连接端口）。

`绑定地址`

签名：文本绑定地址
说明：服务端监听绑定 IP。

`远程地址`

签名：文本远程地址
说明：已连接远端 ip:port。

`连接地址`

签名：文本连接地址
说明：客户端连接目标主机。

`TLS`

签名：逻辑 TLS
说明：是否启用 TLS（无括号属性读）。

`TLS协议`

签名：文本 TLS协议
说明：协商的 TLS 协议版本文本。

`要求客户端证书`

签名：逻辑要求客户端证书
说明：服务端是否要求客户端证书（无括号属性读）。

`分包模式`

签名：整数分包模式
说明：当前粘包拆包模式（0/1/2）。

TCP类/方法

共 57 条。

`置超时`

签名：无置超时([整数毫秒=30000])
说明：设置连接/收发超时（毫秒）。
参数一│[整数毫秒=30000]: >0 生效；≤0 时回退为 30000。

`取超时`

签名：整数取超时()
说明：取当前超时（毫秒）。

`置NoDelay`

签名：无置NoDelay([逻辑启用=真])
说明：设置 TCP_NODELAY（默认开，降低小包延迟）。
参数一│[逻辑启用=真]: 真=低延迟；假=允许 Nagle。

`置KeepAlive`

签名：无置KeepAlive([逻辑启用=真])
说明：设置 SO_KEEPALIVE（默认开，长连接更稳）。
参数一│[逻辑启用=真]: 真=开启保活探测。

`置TLS`

签名：无置TLS([逻辑启用=真])
说明：启用/禁用 TLS（须在监听/连接之前调用）。
参数一│[逻辑启用=真]: 真=后续连接走 TLS 握手。

`置TLS验证`

签名：无置TLS验证([逻辑验证=真])
说明：客户端是否验证服务端证书（默认真，走系统信任链）。
参数一│[逻辑验证=真]: 假=不验证（仅测试环境）。

`置TLS主机名`

签名：无置TLS主机名(文本主机名)
说明：客户端 SNI/证书校验用的主机名；省略时自动用连接地址。
参数一│文本主机名: 如 127.0.0.1 或 api.example.com。

`置TLS证书`

签名：逻辑置TLS证书(文本证书文件, [文本密码=""])
说明：服务端 TLS 证书（PFX/P12）；须在监听前设置。
参数一│文本证书文件:.pfx /.p12 路径。
参数二│[文本密码=”“]: 证书密码，无密码可省略。

`置TLS根证书`

签名：逻辑置TLS根证书(文本根证书文件)
说明：追加自定义根/自签 CA（DER/CER）；用于信任非系统证书。
参数一│文本根证书文件:.cer /.der 路径。

`置TLS客户端证书`

签名：逻辑置TLS客户端证书(文本证书文件, [文本密码=""])
说明：客户端双向 TLS 证书（PFX/P12）；须在连接前设置。
参数一│文本证书文件:.pfx /.p12 路径。
参数二│[文本密码=”“]: 证书密码，无密码可省略。

`置TLS要求客户端证书`

签名：无置TLS要求客户端证书([逻辑要求=真], [逻辑验证=真])
说明：服务端要求客户端出示证书（双向 TLS）；须在监听前设置。
参数一│[逻辑要求=真]: 真=握手时要求客户端证书。
参数二│[逻辑验证=真]: 真=用置TLS根证书或系统信任链验证客户端证书。

`是否要求客户端证书`

签名：逻辑是否要求客户端证书()
说明：服务端是否已启用「要求客户端证书」。

`是否TLS`

签名：逻辑是否TLS()
说明：是否已启用 TLS 模式。

`取TLS协议`

签名：文本取TLS协议()
说明：最近一次 TLS 握手协商的协议（如 TLS 1.2 / TLS 1.3）。

`置分包模式`

签名：无置分包模式([整数模式=0])
说明：粘包拆包：0=原始流；1=4字节小端长度前缀；2=分隔符。须在收发前设置。
参数一│[整数模式=0]: 0 = 原始字节流（数据到达可能粘包/半包，需自拆） 1 = 每帧前加 4 字节小端无符号长度（推荐二进制/JSON 消息） 2 = 按置分包分隔符切帧（适合文本行协议）服务端与客户端须用同一模式。

`取分包模式`

签名：整数取分包模式()
说明：取当前分包模式。

`置分包分隔符`

签名：无置分包分隔符([文本分隔符="\n"])
说明：模式=2 时按此分隔符切帧（UTF-8）；默认换行。
参数一│[文本分隔符=”\n”]: 如 “\n” 或 “\r\n”。

`置分包最大长度`

签名：无置分包最大长度([整数字节=1048576])
说明：单帧最大字节数，超限丢弃缓冲（防恶意超大包）。
参数一│[整数字节=1048576]: 单帧最大字节数（默认 1048576=1MB）。 · ≤0 时回退为 1MB · 聊天/指令：建议 4KB～64KB · 普通业务包：256KB～1MB · 传文件：优先用发送文件（自动分片+进度）；或自行循环发送字节集（如每块 64KB～512KB），对端用数据到达字节集拼文件；1MB 是单帧上限不是整文件上限 · 更大单帧会占内存；超大内容务必分片

`取分包最大长度`

签名：整数取分包最大长度()
说明：取单帧最大字节数。

`发送分包`

签名：整数发送分包([整数连接ID], 文本数据)
说明：按当前分包模式自动打包后发送（长度前缀或追加分隔符）。
参数一│[整数连接ID]: 服务端必填（来自事件回调 id）；客户端省略。
参数二│文本数据: 帧内容（不含长度前缀/分隔符，由运行时自动加）。

`启动`

签名：逻辑启动(整数端口, [文本绑定地址="0.0.0.0"], [整数积压队列=0])
说明：启动服务端监听（推荐名；同「监听」）。须先注册客户进入/数据到达/客户离开。
参数一│整数端口: 1~65535，本机监听端口。
参数二│[文本绑定地址=”0.0.0.0”]: 0.0.0.0=全部网卡；本机联调常用 127.0.0.1。
参数三│[整数积压队列=0]: listen backlog；0 或负数=系统默认；高并发可试 128/256。

`监听`

签名：逻辑监听(整数端口, [文本绑定地址="0.0.0.0"], [整数积压队列=0])
说明：同「启动」（兼容旧名）。
参数一│整数端口: 1~65535，本机监听端口。
参数二│[文本绑定地址=”0.0.0.0”]: 监听 IP；0.0.0.0=全部网卡；本机联调常用 127.0.0.1。
参数三│[整数积压队列=0]: listen 的 backlog（等待 accept 的连接队列长度），单位是「连接个数」不是毫秒/秒。 · 0 或负数 = 使用系统默认 SOMAXCONN（推荐一般业务保持 0） · 正整数 = 自定义队列上限，高并发可试 128/256；过大无益且占资源

`停止`

签名：无停止()
说明：停止接受新连接；已有连接保留。（推荐名；旧名「停止监听」）

`停止监听`

签名：无停止监听()
说明：同「停止」（兼容旧名）。

`关闭全部`

签名：无关闭全部()
说明：停止监听并断开全部连接。

`发送`

签名：整数发送([整数连接ID], 文本数据)
说明：发送文本（UTF-8）。服务端传连接ID+数据；客户端只传数据。
参数一│[整数连接ID]: 服务端必填——来自「用户进入/数据到达」回调的 id，或取连接ID列表() 中的项；客户端必须省略此参数。
参数二│文本数据: 要发送的文本（按 UTF-8 写出）。

`发送字节集`

签名：整数发送字节集([整数连接ID], 字节集数据)
说明：发送原始字节集。
参数一│[整数连接ID]: 服务端必填（同发送）；客户端省略。
参数二│字节集数据: 原始数据。

`发送文件`

签名：逻辑发送文件([整数连接ID], 文本路径, [整数分片大小=65536])
说明：异步按块发送本地文件（原始字节流，不套分包封装）；返回真=已启动。
参数一│[整数连接ID]: 服务端必填（同发送）；客户端省略。
参数二│文本路径: 本地文件路径。
参数三│[整数分片大小=65536]: 每块字节数；≤0 用 65536；上限 1MB。 · 进度走「发送进度」，结束走「发送完毕」。 · 建议双方置分包模式(0)，对端用「数据到达字节集」拼文件。 · 同一会话新的发送文件 / 断开 / 关闭全部会取消进行中的发送。

`发送文件同步`

签名：逻辑发送文件同步([整数连接ID], 文本路径, [整数分片大小=65536])
说明：同步按块发送本地文件（阻塞至发完）；可与「发送字节集」同连接先发自定义头再发文件体。
参数一│[整数连接ID]: 服务端必填（同发送）；客户端省略。
参数二│文本路径: 本地文件路径。
参数三│[整数分片大小=65536]: 每块字节数；≤0 用 65536；上限 1MB。返回真=整文件已写入套接字。进度/完毕回调与异步发送文件相同。HTTP：先发送字节集(响应头)，再发送文件同步(正文)，最后断开。

`断开`

签名：无断开([整数连接ID])
说明：断开连接（优雅半关闭：先排空未发完数据再关，避免大响应 RST）。服务端传连接ID；客户端省略参数。
参数一│[整数连接ID]: 服务端必填，指定要踢掉的连接（来自事件回调或取连接ID列表）；客户端省略=断开本端唯一连接。

`取客户端数`

签名：整数取客户端数()
说明：当前在线客户端数量（服务端）。

`广播`

签名：整数广播(文本数据)
说明：向全部在线客户端发送文本（UTF-8）；返回成功发送的连接数。
参数一│文本数据: 广播内容。

`广播字节集`

签名：整数广播字节集(字节集数据)
说明：向全部在线客户端发送原始字节集。
参数一│字节集数据: 广播内容。

`取连接ID列表`

签名：通用取连接ID列表()
说明：返回当前全部在线连接 ID（整数数组，服务端）。

`取本地地址`

签名：文本取本地地址([整数连接ID=1])
说明：取本端 ip:port。服务端传连接 ID；客户端可省略。
参数一│[整数连接ID=1]: 服务端指定连接；客户端默认 1。

`取端口`

签名：整数取端口()
说明：取当前端口：服务端=监听端口，客户端=连接端口。

`取绑定地址`

签名：文本取绑定地址()
说明：取服务端监听绑定地址（如 0.0.0.0）。

`取客户端地址`

签名：文本取客户端地址([整数连接ID=1])
说明：取远端「IP:端口」（同取客户地址）。服务端传连接 ID；客户端可省略。
参数一│[整数连接ID=1]: 服务端指定连接；客户端默认 1。

`取客户地址`

签名：文本取客户地址([整数连接ID=1])
说明：取远端「IP:端口」（推荐名；同取客户端地址）。
参数一│[整数连接ID=1]: 服务端指定连接；客户端默认 1。

`取客户IP`

签名：文本取客户IP([整数连接ID=1])
说明：取远端 IP（不含端口）。连接时缓存，可随时查询。
参数一│[整数连接ID=1]: 服务端指定连接；客户端默认 1。

`取客户端口`

签名：整数取客户端口([整数连接ID=1])
说明：取远端端口。连接时缓存，可随时查询。
参数一│[整数连接ID=1]: 服务端指定连接；客户端默认 1。

`是否在监听`

签名：逻辑是否在监听()
说明：是否正在监听端口。

`连接`

签名：逻辑连接(文本地址, [整数端口=0])
说明：异步连接；立即返回。端口省略或 0 时从「地址:端口」解析。
参数一│文本地址: IP、域名，或「IP:端口」「[IPv6]:端口」。
参数二│[整数端口=0]: 1~65535；0 或省略=从地址字符串里解析端口。

`连接_同步`

签名：逻辑连接_同步(文本地址, [整数端口=0])
说明：阻塞连接至成功或超时；端口规则同连接。
参数一│文本地址: IP、域名，或「IP:端口」。
参数二│[整数端口=0]: 0=从地址解析。

`取连接地址`

签名：文本取连接地址()
说明：取客户端最近一次连接目标主机（不含端口）。

`取连接端口`

签名：整数取连接端口()
说明：取客户端最近一次连接目标端口。

`是否连接中`

签名：逻辑是否连接中()
说明：异步连接是否仍在进行。

`接收`

签名：文本接收([整数最大长度=4096])
说明：同步接收文本（配合连接_同步使用）。
参数一│[整数最大长度=4096]: 本次最多读多少字节（默认 4096）。 · ≤0 按 4096 · 硬上限 1MB（1048576）；再大也会被截到 1MB · 聊天/短应答：4KB～64KB 足够 · 较大业务包：建议 ≤256KB，并配合超时 · 注意：这是「单次 read」上限，不等于完整消息；粘包请用分包模式+数据到达

`接收字节集`

签名：字节集接收字节集([整数最大长度=4096])
说明：同步接收字节集。
参数一│[整数最大长度=4096]: 同接收——默认 4096，硬上限 1MB。

`是否已连接`

签名：逻辑是否已连接()
说明：客户端是否仍保持连接。

`取远程地址`

签名：文本取远程地址()
说明：客户端模式下取远端「IP:端口」。

`取远程IP`

签名：文本取远程IP()
说明：客户端模式下取远端 IP。

`取远程端口`

签名：整数取远程端口()
说明：客户端模式下取远端端口。

`取模式`

签名：文本取模式()
说明：返回「客户端」「服务端」或「空闲」；也可用属性 t.模式。

`取错误`

签名：文本取错误()
说明：取最后一次失败原因；也可用属性 t.错误信息。

`错误信息`

签名：文本错误信息()
说明：同取错误()；支持无括号属性读。

`重置`

签名：无重置()
说明：断开全部并恢复默认（超时/NoDelay/KeepAlive）；不清回调。

易错对照

错误	正确
类型写成 TCP	必须「TCP类」
事件里做重活	短逻辑；重活丢线程