跳到主要内容

错误码

除注明 void 的函数外，一律返回 int32_t 错误码：0（DARRA_OK）= 成功；非 0 = darra_error_code 之一，返回值 == 本线程 darra_last_error 的 code。细节用 darra_last_error 取。

hint 对外可原样展示给最终用户。逐码 hint 文案见 运行时错误码（与 SDK 填进 darra_error_t.hint 的字符串逐字相同）。

公开 SDK 是 runtime 构建：密码 / 授权相关错误码描述的是「消费已签发容器」失败，不是公开包能签发。

相关页面

错误模型​

  • 每个线程一条错误槽；任何 API 调用进入时先清空本线程槽，失败时填满，成功后保持空。
  • 一次失败调用之后、同一线程下一次 API 调用之前，darra_last_error 取到的就是这次失败的细节。
  • message / hint 为定长数组，SDK 保证 NUL 结尾，调用方无需释放。
  • 参数契约违反（NULL 句柄 / NULL 出参 / size 字段未填 / 裸缓冲缺宽高）属调用方 bug：返回 DARRA_INTERNAL，message 指明是哪个参数。SDK 在任何非法入参下都不崩溃。
int32_t rc = darra_xxx(...);
if (rc != DARRA_OK) {
    darra_error_t err; err.size = sizeof(err);
    darra_last_error(&err);   /* err.message 是什么错，err.hint 怎么修 */
}

错误码表​

类别属性类型访问说明
成功DARRA_OK0只读成功
IODARRA_IO_NOT_FOUND1只读文件不存在（容器 / 授权 / 图片 / 离线包路径错）
DARRA_IO_DENIED2只读文件存在但读 / 写被拒（权限、占用、目录需管理员）
容器与授权DARRA_BAD_CONTAINER3只读.darmodel 损坏 / 非 DARM1 / 被截断篡改
DARRA_BAD_LICENSE4只读.darmkey 损坏或与容器不配对
DARRA_PASSWORD_REQUIRED5只读该容器需要密码但调用方没给
DARRA_PASSWORD_WRONG6只读密码错误
DARRA_MACHINE_MISMATCH7只读绑机授权在非目标机器上使用
DARRA_TRIAL_EXHAUSTED8只读试用计次已用完
平台与载荷DARRA_UNSUPPORTED_PAYLOAD9只读载荷类型在当前平台 / Provider 下不支持。Windows 收到 rknn 载荷即此码。.pt / .pth 亦此码
DARRA_UNSUPPORTED_PLATFORM10只读整个 OS / 架构不在支持矩阵（如 macOS、x86）。Windows 上指名 edge-rknn 即此码
运行时包DARRA_PROVIDER_MISSING11只读需要的运行时 Provider 包未安装
DARRA_PROVIDER_ABI_MISMATCH12只读Provider 包与 Core 的 ABI 版本不匹配
DARRA_HARDWARE_MISSING13只读未探测到所需硬件（N 卡 / Intel / RK3588 NPU）
DARRA_DRIVER_TOO_OLD14只读驱动版本低于 Provider 包要求（SDK 不代装）
DARRA_NETWORK_FAILED15只读清单 / 运行时包下载失败
DARRA_CHECKSUM_MISMATCH16只读下载包或离线包 sha256 校验不过（fail-closed）
DARRA_CANCELLED17只读操作被取消（见 darra_runtime_ensure_cancel）
内部DARRA_INTERNAL18只读SDK 内部错误；也用于调用方参数契约违反

darra_last_error()​

int32_t darra_last_error(darra_error_t* out);

取本线程最近一次失败的细节。

参数:

  • out (darra_error_t*) — 可为 NULL（只查码不管细节）。非 NULL 时调用方须先填 out->size = sizeof(*out)

返回值:

  • int32_t — 本线程错误槽里的码；无错误（或上次调用成功）返回 DARRA_OK

相关结构:

typedef struct darra_error_t {
    uint32_t size;             /* 调用方填 sizeof(darra_error_t) */
    int32_t  code;             /* darra_error_code */
    char     message[256];     /* 错误描述（UTF-8，保证 NUL 结尾） */
    char     hint[512];        /* 修复建议（UTF-8，可为空串） */
} darra_error_t;

示例:

int32_t rc = darra_session_open(path, key, NULL, NULL, &s);
if (rc != DARRA_OK) {
    darra_error_t err; err.size = sizeof(err);
    darra_last_error(&err);
    fprintf(stderr, "[%d] %s\n建议: %s\n", err.code, err.message, err.hint);
}

darra_clear_error()​

void darra_clear_error(void);

显式清空本线程错误槽。一般不需要手动调（每次 API 进入自动清），供绑定层在特殊时序下使用。