错误与诊断

本页描述 Python 与 C API 的错误报告方式。

30 秒版本：

• Python 失败会抛 RuntimeError。

• C API 通常返回 sqzc3d_STATUS_*；用 sqzc3d_last_error(...) 拿到可读错误信息。

• 如果某个 build 缺失能力，可能会遇到 sqzc3d_STATUS_NOT_IMPLEMENTED。

形象化：把错误当成“可行动的提示”，不要把失败当作“默默降级成功”。

Python

Python bindings 在失败时会抛出 RuntimeError。

示例：

import sqzc3d

try:
    v = sqzc3d.read("missing.c3d")
except RuntimeError as e:
    print("failed:", e)

功能探测（feature discovery）：

import sqzc3d

features = sqzc3d.features()
print("features=", features)

如果某个 build 缺失能力，API 可能以 sqzc3d_STATUS_NOT_IMPLEMENTED 失败（Python 中会体现为异常）。

C API

大多数 API 返回一个 sqzc3d_STATUS_* code（见 sqzc3d_types.h）。

当调用失败时，使用：

• sqzc3d_last_error(dec) 获取可读的错误信息

• sqzc3d_last_error(NULL) 用于在 decoder handle 尚不存在时的错误（例如 open 失败）

示例：

sqzc3d_dec_t* dec = NULL;
int st = sqzc3d_open_file(&dec, path, &open_opt);
if (st != sqzc3d_STATUS_SUCCESS) {
  fprintf(stderr, "open failed: %s\n", sqzc3d_last_error(NULL));
  return 1;
}

结构化错误详情（可选）：

• sqzc3d_last_error_detail(dec, &detail)