API 参考

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

核心概念

任务数据结构 (Task Data)

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

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

回调函数定义

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

C 语言定义:

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

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 对象描述了当前发生的事件类型和元数据。

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

事件类型详解:

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

2. 消息结构 (Message)

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

start / end

• 内容: 空对象 {}

startOne / endOne

• 内容:

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

update

• 内容:

{
  "Total": 1048576,      // 文件总字节数
  "Downloaded": 524288   // 已下载字节数
}

msg

msg 类型的事件用于传递各种状态信息，其 JSON Key 不固定，请务必进行兼容处理。

• 错误 (Error): (通常在 startDownload 初始化失败时)

{ "Error": "具体的错误描述信息" }

• 文本 (Text): (通常在下载过程中发生错误或停止时)

{ "Text": "下载文件失败: ..." }

{ "Text": "下载已停止" }

• 消息 (Msg): (通常在暂停/恢复时)

{ "Msg": "下载已暂停" }

{ "Msg": "下载已恢复" }

TIP

最佳实践：在处理 msg 事件时，建议同时检查 Error, Text, Msg 这三个 Key。

通用规则

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

• tasksData 指向的内存需在调用期间保持有效。
• 回调函数中的 event 和 msg 指针仅在回调执行期间有效，不要在回调外部保存这些指针。

线程安全

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

错误处理

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