TLD Core 泰勒下载器核心

Appearance

API 参考 ​

本节详细介绍了 TLD 的 API 接口、数据结构和回调机制。

TIP

本文档介绍的是 TLD（Rust 版本）的 API。API 接口与 TTHSD Golang 完全兼容，可以直接替换动态库使用。

TTHSD Golang 已停止开发，建议使用 TLD。

核心概念 ​

任务数据结构 (Task Data) ​

传递给 start_download 等函数的任务列表必须是 JSON 格式字符串：

json
[
  {
    "url": "https://example.com/file.zip",
    "save_path": "/path/to/save/file.zip",
    "show_name": "文件显示名称",
    "id": "unique-task-id-123",
    "headers": {
      "X-Custom-Header": "custom-value"
    }
  }
]

任务字段说明 ​

字段类型必填说明
urlstring是下载链接
save_pathstring是保存路径
show_namestring否显示名称（默认为 URL 文件名）
idstring否任务唯一标识（自动生成 UUID）
headersobject否该任务额外的 HTTP 请求头

NOTE

任务中的 headers 会与下载器的全局 headers 合并，任务级别会覆盖全局同名 header。

回调函数定义 ​

回调函数用于接收下载过程中的所有事件和状态更新。

C 语言定义:

c
typedef void (*progress_callback_t)(void* event, void* msg);

Python 定义:

python
def callback(event_json_str, msg_json_str):
    # event_json_str 和 msg_json_str 是 JSON 字符串
    pass

事件与消息结构 (Event & Message) ​

回调函数的两个参数 event 和 msg 均为 JSON 格式字符串。

1. 事件结构 (Event) ​

Event 对象描述了当前发生的事件类型和元数据。

字段类型说明注意事项
Typestring事件类型start, startOne, update, endOne, end, msg, err
Namestring事件名称仅在部分事件中包含（如 msg 类型可能包含 "错误"、"停止" 等）
ShowNamestring显示名称update 和 start/end 事件中为空字符串
IDstring任务 IDupdate 事件中包含对应任务 ID

事件类型详解:

  • start: 批量任务开始（ID为空）
  • startOne: 单个文件开始（包含完整 ID 和 ShowName）
  • update: 进度更新（包含任务 ID）
  • endOne: 单个文件结束（包含完整 ID 和 ShowName）
  • end: 批量任务结束（ID为空）
  • msg: 消息通知（包括错误、暂停、恢复、停止等状态）
  • err: 错误通知

2. 消息结构 (Msg) ​

Msg 对象的内容取决于 Event.Type，且在 msg 类型下对应的 Key 可能不同。

start / end ​

  • Msg 内容: 空对象 {}

startOne / endOne ​

  • Msg 内容:
json
{
  "URL": "任务URL",
  "SavePath": "保存路径",
  "ShowName": "显示名称",
  "Index": 1,       // 当前任务索引 (从1开始)
  "Total": 5        // 总任务数
}

update ​

  • Msg 内容:
json
{
  "Total": 1048576,      // 文件总字节数
  "Downloaded": 524288   // 已下载字节数
}

msg ​

msg 类型的事件用于传递各种状态信息，其 JSON Key 固定为 "Text"

  • Msg 内容:
json
{ "Text": "下载已停止" }
json
{ "Text": "下载已暂停" }
json
{ "Text": "下载已恢复" }

err ​

err 类型的事件用于传递错误信息，其 JSON Key 固定为 "Error"

  • Msg 内容:
json
{ "Error": "下载文件失败: ..." }

通用规则 ​

内存管理 (C/C++ 调用者) ​

  • tasksData 指向的内存需在调用期间保持有效。
  • 回调函数中的 event 和 msg 指针仅在回调执行期间有效，不要在回调外部保存这些指针。
  • stop_download 会清理下载器内部所有资源，包括异步任务和网络连接，当前下载器也会被销毁。
  • 在 Python 接口封装 端调用 close() 后，应确保不再使用对应的下载器 ID。
  • 暂停/恢复功能在并行下载（is_multiple=true）时可能存在限制，建议顺序下载时使用暂停/恢复功能。

线程安全 ​

  • API 函数是线程安全的。
  • 可以同时管理多个不同的 download 实例。
  • 对同一个 download ID 的操作（如 暂停 -> 恢复）应顺序执行。

错误处理 ​

  • API 函数返回 -1 表示失败（如参数错误）。
  • 异步过程中的错误（如网络超时）将通过 err 事件类型的 Error 字段回调通知。

API 函数列表 ​

以下是所有可用的 API 函数：

函数名功能描述
get_downloader创建下载器实例但不启动下载
start_download创建下载器实例并立即启动下载
start_download_id启动已创建的下载器（顺序下载）
start_multiple_downloads_id启动已创建的下载器（并行下载）
pause_download暂停下载
resume_download恢复下载
stop_download停止下载并清理资源
set_speed_limit设置下载速度限制
set_proxy设置代理服务器
set_retry_config配置重试参数
get_performance_stats获取性能统计信息
free_string释放字符串内存（C/C++ 调用者）

TLD 的性能优势 ​

相比 TTHSD Golang 版本，TLD 具有以下性能优势：

特性TLD (Rust)TTHSD Golang
下载速度更快较快
内存占用更低较高
并发数可达数十万有限制
内存安全Rust 所有权机制依赖 GC
GC 暂停无有
Android 支持支持不支持

新增功能 (v0.1.0-dev.6) ​

自动重试机制（指数退避） ​

下载失败时自动进行重试，采用指数退避策略：

  • 最大重试次数：默认 3 次，可通过 set_retry_config 配置
  • 初始延迟：默认 1000ms
  • 最大延迟：默认 30000ms
  • 退避策略：每次失败后延迟翻倍，上限为最大延迟

速度限制 ​

支持对下载速度进行限制，避免占用过多带宽：

  • 使用 set_speed_limit 函数设置
  • 单位：bytes/s，0 表示不限速

代理支持 ​

支持通过 HTTP/HTTPS/SOCKS5 代理服务器下载：

  • 使用 set_proxy 函数设置
  • 支持 http://、https://、socks5:// 协议

性能统计 ​

提供实时性能监控数据：

  • 使用 get_performance_stats 函数获取
  • 包括当前速度、平均速度、峰值速度等

Headers 支持 ​

支持在全局和任务级别设置 HTTP 请求头：

  • 全局 headers：通过 headersJson 参数设置（start_download / get_downloader）
  • 任务级别：在任务 JSON 中设置 headers 字段

SFTP 主机密钥验证 ​

增强 SFTP 下载的安全性，支持主机密钥验证。

条件编译 ​

可通过 Cargo features 启用/禁用特定协议：

toml
[features]
default = ["full"]
full = ["ftp", "sftp", "torrent", "metalink", "ed2k", "http3", "websocket", "socket"]

版本说明 ​

TLD (当前版本) ​

  • 基于 Rust 语言开发
  • 高性能、低内存占用
  • 支持 Windows、Linux、macOS、Android 平台
  • 持续维护和更新

TTHSD Golang (已停止开发) ​

  • 基于 Go 语言开发
  • 已停止维护
  • API 接口与 TLD 完全兼容
  • 建议迁移到 TLD

如需了解各个函数的详细信息，请点击上表中的函数名称查看对应文档。