错误处理

失败返回 darra_ai::Error。每个变体对应一个 darra_error_code（1..=18）；未知新码走 Error::Unknown code / message / hint（#[non_exhaustive]，向前容忍）。message / hint 原样透传 Core，不改写。hint 文案权威见 错误码目录。

实现 std::error::Error + Display。Display 格式：[码] 描述 或 [码] 描述 | 建议: hint。

提示

公开 crate 是 runtime 构建：可以打开 Studio 已签发的 .darmodel（解密、验票、推理），不含加密与签发能力。密码 / 授权相关错误描述的是「消费已签发容器」失败，不是本包能签发。

类别	属性	类型	访问	说明
Error	code	i32	方法	对应 darra_error_code 整数值
	message	&str	方法	错误描述（Core 原文）
	hint	&str	方法	修复建议，可为空串；可原样展示给最终用户
	from_code	Error	关联函数	按错误码构造对应变体；未知码走 Unknown
	from_last	Error	关联函数	读本线程错误槽。须在失败 API 返回后、同线程下一次 API 之前调用

变体

码	变体	说明
1	IoNotFound	文件不存在（容器 / 授权 / 图片 / 离线包路径错）
2	IoDenied	文件存在但读 / 写被拒
3	BadContainer	.darmodel 损坏 / 非 DARM1 / 被截断篡改
4	BadLicense	.darmkey 损坏或与容器不配对
5	PasswordRequired	该容器需要密码但调用方没给
6	PasswordWrong	密码错误
7	MachineMismatch	绑机授权在非目标机器上使用
8	TrialExhausted	试用计次已用完
9	UnsupportedPayload	载荷类型在当前平台 / Provider 下不支持。Windows 收到 rknn 载荷走此码
10	UnsupportedPlatform	整个 OS / 架构不在支持矩阵（如 macOS、x86）。Windows 上指名 edge-rknn 走此码
11	ProviderMissing	需要的运行时 Provider 包未安装
12	ProviderAbiMismatch	Provider 包与 Core 的 ABI 版本不匹配
13	HardwareMissing	未探测到所需硬件（N 卡 / Intel / RK3588 NPU）
14	DriverTooOld	驱动版本低于 Provider 包要求（SDK 不代装）
15	NetworkFailed	清单 / 运行时包下载失败
16	ChecksumMismatch	下载包或离线包 sha256 校验不过（fail-closed）
17	Cancelled	操作被取消（见 runtime::cancel）
18	Internal	SDK 内部错误；也用于调用方参数契约违反
其它	Unknown 变体	新 dll 追加的码，向前容忍，不丢 code

每个变体（除 Unknown）字段均为 message 与 hint 两个 String 字段。

参数契约违反（NULL 句柄 / size 未填 / 裸缓冲缺宽高）属调用方 bug：归 Internal，message 指明哪个参数。SDK 在任何非法入参下都不崩溃。

方法

code()

pub fn code(&self) -> i32

对应的 darra_error_code 整数值。

返回值:

• i32 — 错误码

message()

pub fn message(&self) -> &str

错误描述（Core 原文）。

返回值:

• &str — 描述

hint()

pub fn hint(&self) -> &str

修复建议（error-catalog 标准文案，可为空串）。可原样展示给最终用户。

返回值:

• &str — 建议；可为空串

Error::from_code(code, message, hint)

pub fn from_code(code: i32, message: String, hint: String) -> Self

按错误码构造对应变体。未知码走 Unknown。

参数:

• code (i32) — darra_error_code
• message (String) — 描述
• hint (String) — 建议

返回值:

• Error — 对应变体

Error::from_last()

pub fn from_last() -> Self

读本线程错误槽并构造对应变体。须在失败 API 返回后、同线程下一次 API 之前调用。绑定在失败 API 返回后立刻取槽并翻成 Error，调用方拿到的已经是完整变体，不必再调 from_last。from_last 留给绑定内部 / 特殊时序。

返回值:

• Error — 本线程槽里的变体；槽空则 Internal（Core 实现缺口）

完整示例

use darra_ai::{Error, Session};

match Session::open("model.darmodel", Some("model.darmkey"), None, None) {
    Ok(session) => { let _ = session; }
    Err(Error::IoNotFound { message, hint }) => {
        eprintln!("找不到文件: {message}");
        if !hint.is_empty() {
            eprintln!("建议: {hint}");
        }
    }
    Err(Error::UnsupportedPayload { message, hint }) => {
        eprintln!("{message}");
        eprintln!("{hint}");
    }
    Err(Error::UnsupportedPlatform { .. }) => {
        eprintln!("当前平台不支持该 Provider");
    }
    Err(Error::Cancelled { .. }) => {}
    Err(e) => {
        eprintln!("[{}] {} | 建议: {}", e.code(), e.message(), e.hint());
    }
}

? 可直接向上传，因为 Error 实现了 std::error::Error：

fn load() -> Result<Session, Error> {
    Session::open("model.darmodel", Some("model.darmkey"), None, None)
}

Windows 与 RKNN

场景	变体
Windows 打开 rknn 载荷	UnsupportedPayload (9)
Windows 上 runtime::ensure(Some("edge-rknn"), …) 或 prefer_provider = edge-rknn	UnsupportedPlatform (10)
linux-arm64 + RK3588 + 已装 edge-rknn	正常打开

rknn 载荷只在 linux-arm64 运行。Windows 无 RKNN，不是「即将支持」。