TTHSD TT 高速下载器

Appearance

API 参考 ​

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

核心概念 ​

任务数据结构 (Task Data) ​

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

json
[
  {
    "URL": "https://example.com/file.zip",
    "SavePath": "/path/to/save/file.zip",
    "ShowName": "文件显示名称",
    "ID": "unique-task-id-123"
  }
]

回调函数定义 ​

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

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
Namestring事件名称仅在部分事件中包含（如 msg 类型可能包含 "错误"、"停止" 等）
ShowNamestring显示名称update 和 start/end 事件中为空字符串
IDstring任务 IDupdate 事件中包含对应任务 ID

事件类型详解:

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

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 指针仅在回调执行期间有效，不要在回调外部保存这些指针。

线程安全 ​

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

错误处理 ​

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