5.2 KiB
5.2 KiB
文件传输
用户流程：选择文件 → 上传/下载 → 等待传输完成 对应程序流程：FileTransferInit → DialFileTransfer → UploadFileData / DownloadFileData 注：文件传输 API 暂未在
TsClient中封装，需通过TSBridge直接调用 gomobile 对象
一、状态树
文件状态
flowchart TD
FILE[文件状态<br/>维护上传和下载过程]
FILE --> F0[空闲 Idle<br/>没有文件传输任务]
FILE --> F1[初始化 Initializing<br/>请求 FileTransferInitUpload 或 Download]
FILE --> F2[连接中 Dialing<br/>DialFileTransfer 建立 TCP 连接]
FILE --> F3[传输中 Transferring<br/>UploadFileData 或 DownloadFileData 搬运数据]
FILE --> F4[完成 Completed<br/>文件数据传输结束]
FILE --> F5[失败 Failed<br/>初始化、连接或传输发生错误]
二、时序：文件上传与下载
sequenceDiagram
participant UI as 文件操作 UI<br/>选择上传或下载任务
participant SDK as teamspeak-go SDK<br/>初始化文件传输并提供辅助函数
participant TS as TeamSpeak 服务器<br/>分配文件传输连接信息
participant TCP as 文件 TCP 连接<br/>承载实际文件字节流
participant IO as 本地 Reader/Writer<br/>提供上传源或接收下载结果
alt 上传文件
UI->>SDK: FileTransferInitUpload(channelID, path, password, size, overwrite)<br/>中文注释：请求初始化频道文件上传
SDK->>TS: ftinitupload<br/>中文注释：提交目标路径、大小和覆盖选项
TS-->>SDK: FileUploadInfo<br/>中文注释：返回 host、port 和传输 key
SDK-->>UI: uploadInfo<br/>中文注释：初始化成功后才能建立数据连接
UI->>SDK: DialFileTransfer(host, port, key)<br/>中文注释：建立独立 TCP 文件连接
SDK->>TCP: TCP connect<br/>中文注释：连接服务器文件传输端口
UI->>SDK: UploadFileData(host, info, reader)<br/>中文注释：从本地 Reader 读取上传内容
IO-->>SDK: 文件字节流<br/>中文注释：持续提供待上传数据
SDK->>TCP: 上传字节流<br/>中文注释：通过 TCP 发送文件内容
TCP->>TS: 完成上传<br/>中文注释：服务器保存频道文件
else 下载文件
UI->>SDK: FileTransferInitDownload(channelID, path, password)<br/>中文注释：请求初始化频道文件下载
SDK->>TS: ftinitdownload<br/>中文注释：提交目标频道和文件路径
TS-->>SDK: FileDownloadInfo<br/>中文注释：返回 host、port 和传输 key
SDK-->>UI: downloadInfo<br/>中文注释：初始化成功后才能建立数据连接
UI->>SDK: DialFileTransfer(host, port, key)<br/>中文注释：建立独立 TCP 文件连接
SDK->>TCP: TCP connect<br/>中文注释：连接服务器文件传输端口
UI->>SDK: DownloadFileData(host, info, writer)<br/>中文注释：指定本地 Writer 接收文件
TS->>TCP: 下载字节流<br/>中文注释：服务器持续发送文件内容
TCP->>SDK: 文件字节流<br/>中文注释：SDK 从 tcp 读取下载数据
SDK->>IO: 写入本地 Writer<br/>中文注释：保存或消费下载内容
end
三、事件依赖
文件传输前置依赖矩阵
| 操作或事件 | 必须依赖 | 建议依赖 | 依赖失败时的处理 |
|---|---|---|---|
DialFileTransfer |
上传或下载初始化结果 | 初始化信息尚未过期 | 不得跳过初始化直接拨号 |
UploadFileData |
上传信息、Reader、有效 TCP 条件 | 文件大小与声明一致 | 中止任务并展示传输错误 |
DownloadFileData |
下载信息、Writer、有效 TCP 条件 | 本地空间和写权限可用 | 中止任务并清理不完整结果 |
事件依赖图（文件传输）
flowchart TD
READY --> FTINIT[文件传输初始化<br/>请求上传或下载连接信息]
FTINIT --> FTDIAL[DialFileTransfer<br/>依赖 host、port 和 key 建立 TCP]
FTDIAL --> FTDATA[上传或下载数据<br/>依赖已初始化的文件连接]
命令响应与事件事实的区别
flowchart LR
INTENT[用户意图<br/>上传或下载文件] --> COMMAND[客户端请求<br/>FileTransferInit]
COMMAND --> RESPONSE{命令响应<br/>判断服务器是否接受请求}
RESPONSE -- 失败 --> FAILED[请求失败<br/>展示错误原因]
RESPONSE -- 成功 --> INFO[获得传输参数<br/>host、port、key]
INFO --> DIAL[建立 TCP 连接<br/>DialFileTransfer]
DIAL --> TRANSFER[数据传输<br/>Upload/DownloadFileData]
关键区分：
FileTransferInitUpload/Download成功：只获得传输参数；文件内容仍依赖后续 TCP 连接和数据传输。- 文件传输严格遵守"初始化 → TCP 连接 → 数据传输"三个阶段，不能跳过。
权威性划分
| 数据 | 推荐权威来源 | 原因 |
|---|---|---|
| 文件传输进度 | SDK 内部文件状态事件 | notifystartupload、notifystartdownload、notifystatusfiletransfer |
统一实现原则（文件传输相关）
- 文件传输严格遵守"初始化 → TCP 连接 → 数据传输"。 三个阶段不能跳过。