类型

darra_ai.h 里的公开类型与宏。ABI 只导出 C 函数 + 不透明句柄 + 定长结构体，永不导出 C++ 类型 / STL。C++ 消费方按 C ABI 填字段，示例用 nullptr / {} 初始化。

提示

• 会话 API 见 会话。
• 推理 API 见 推理。
• 错误码见 错误。

公开 runtime 没有加密 / 签发类型（darra_key_options 仅 DARRA_AUTHORING 段，不进本页）。Windows 无 RKNN：DARRA_IMAGE_* 与会话类型在 Windows 上同样可用，只是 rknn 载荷 / edge-rknn 包被拒绝。

功能概览

类别	属性	类型	访问	说明
句柄	darra_session	struct	不透明	会话句柄；绑定侧永远只持有指针
选项	darra_session_options	struct	入参	线程数 / CPU 亲和；调用方填 size
图像	darra_image_format	enum	入参	AUTO/ENCODED 或裸缓冲通道序
	darra_image_desc	struct	入参	图像描述；调用方填 size
回调	darra_progress_cb	typedef	入参	ensure 进度回调；工作线程触发
字符串	darra_string_free	void	释放	释放 SDK 堆字符串；nullptr 安全

句柄

darra_session

不透明句柄。定义只在 Core 内部，绑定侧永远只持有 darra_session*。close 后句柄失效，再用 = 未定义行为。

typedef struct darra_session darra_session;

选项

darra_session_options

会话打开选项。首字段 size 做版本扩展：调用方填 sizeof(darra_session_options)。旧 darra_session_open / open_plain 等价于本结构传 nullptr（全部走默认）。

typedef struct darra_session_options {
    uint32_t size;
    int32_t  intra_op_threads;
    int32_t  inter_op_threads;
    uint64_t cpu_affinity_mask;
} darra_session_options;

类别	属性	类型	访问	说明
选项	size	uint32_t	调用方填	sizeof(darra_session_options)
	intra_op_threads	int32_t	读写	0 = 自动，自动上限 min(硬件逻辑核, 4)；>0 照填给本会话线程池；<0 = DARRA_INTERNAL
	inter_op_threads	int32_t	读写	同上
	cpu_affinity_mask	uint64_t	读写	0 = 不设；非 0 = 本会话线程池 CPU 位图（bit0 = 逻辑核 0）。禁止改 ReservedCpuSets / PLC 隔离核

多会话各用各的线程池，互不抢同一把全局锁（darra_runtime_ensure 的进程内互斥除外）。

示例:

darra_session_options opt{};
opt.size = sizeof(opt);
opt.intra_op_threads = 2;
opt.inter_op_threads = 1;
opt.cpu_affinity_mask = 0;

图像

darra_image_format

每次调用处理一张图。相机 / 视频连续帧循环调用 darra_session_infer_image。

typedef enum darra_image_format {
    DARRA_IMAGE_AUTO     = 0,  // 按字节魔数自嗅探 JPG/PNG/BMP。裸缓冲禁止用 AUTO
    DARRA_IMAGE_ENCODED  = 1,  // 显式已编码字节流；行为同 AUTO
    DARRA_IMAGE_RGB888   = 2,  // 裸缓冲 RGB 8bit，须给宽高
    DARRA_IMAGE_BGR888   = 3,  // 裸缓冲 BGR 8bit，须给宽高
    DARRA_IMAGE_GRAY8    = 4,  // 裸缓冲灰度 8bit，须给宽高
    DARRA_IMAGE_RGBA8888 = 5   // 裸缓冲 RGBA 8bit，须给宽高
} darra_image_format;

darra_image_desc

图像描述。首字段 size 做版本扩展：调用方填 sizeof(darra_image_desc)。format = AUTO/ENCODED 时 width/height/stride 忽略（填 0）。裸缓冲时 width/height 必填（>0），缺宽高 = DARRA_INTERNAL。

typedef struct darra_image_desc {
    uint32_t           size;
    darra_image_format format;
    uint32_t           width;
    uint32_t           height;
    uint32_t           stride;
} darra_image_desc;

类别	属性	类型	访问	说明
描述	size	uint32_t	调用方填	sizeof(darra_image_desc)
	format	darra_image_format	读写	见 darra_image_format
	width	uint32_t	读写	AUTO/ENCODED 忽略填 0；裸缓冲必填 >0
	height	uint32_t	读写	同上
	stride	uint32_t	读写	每行字节数；0 = 紧凑：RGB/BGR=width*3，GRAY8=width，RGBA=width*4

示例:

darra_image_desc desc{};
desc.size = sizeof(desc);
desc.format = DARRA_IMAGE_BGR888;
desc.width = 1920;
desc.height = 1080;
desc.stride = 0;

回调

darra_progress_cb

typedef void (*darra_progress_cb)(float percent, const char* stage, void* user);

darra_runtime_ensure 进度回调。percent 0..100，每个 stage 内单调不降。stage：probe / manifest / download / verify / install / done。回调在 SDK 内部工作线程触发：回调里禁止调用任何 darra_* 函数。有捕获的 lambda 不能衰减为函数指针；有状态走 user 指针。

参数:

• percent (float) — 0..100，stage 内单调不降
• stage (const char*) — 短字符串，供 UI 显示 / 日志
• user (void*) — darra_runtime_ensure 原样透传

字符串

darra_string_free()

void darra_string_free(char* s);

释放 SDK 返回的堆字符串。nullptr 安全；重复释放 = 未定义行为。Windows 上 SDK 与调用方可能不是同一 CRT 堆，禁止 free() / delete[]。静态字符串（darra_version_string）不属于此列，禁止释放。

参数:

• s (char*) — SDK 分配的堆字符串；nullptr 为 no-op

示例:

char* json = nullptr;
if (darra_session_meta_json(session, &json) == DARRA_OK) {
    std::printf("%s\n", json);
    darra_string_free(json);
}

版本宏

#define DARRA_VERSION_MAJOR 1
#define DARRA_VERSION_MINOR 0
#define DARRA_VERSION_PATCH 0

#define DARRA_VERSION_ENCODE(major_, minor_, patch_) \
    (((uint32_t)(major_) << 16) | ((uint32_t)(minor_) << 8) | (uint32_t)(patch_))
#define DARRA_VERSION_DECODE_MAJOR(v_) (((v_) >> 16) & 0xFFu)
#define DARRA_VERSION_DECODE_MINOR(v_) (((v_) >> 8) & 0xFFu)
#define DARRA_VERSION_DECODE_PATCH(v_) ((v_) & 0xFFu)

#define DARRA_HEADER_VERSION \
    DARRA_VERSION_ENCODE(DARRA_VERSION_MAJOR, DARRA_VERSION_MINOR, DARRA_VERSION_PATCH)

运行时 major 必须 == DARRA_VERSION_MAJOR，否则 ABI 已破坏，禁止继续调用任何其它函数。

诊断 JSON

darra_diag_collect 输出：

{
  "schema": 1,
  "sdk": { "version": "1.0.0+runtime", "abi": 65536 },
  "os":   { "name": "windows", "version": "10.0.26100", "arch": "x64" },
  "cpu":  { "model": "AMD Ryzen 7 9800X3D", "cores": 16 },
  "gpus": [ { "model": "NVIDIA RTX 4070", "driver": "560.94", "cudaMax": "12.6" } ],
  "providers": [ { "id": "onnx-cpu", "version": "1.0.0", "path": "C:/.../Env/onnx-cpu/1.0.0" } ],
  "license": { "present": true, "mode": "trial", "trialRemaining": 12, "machineBound": false },
  "recentErrors": [ { "code": 11, "message": "...", "when": "2026-09-01T10:00:00+08:00" } ]
}

• schema 恒存在；其余字段采不到时为 null 或缺席，消费方必须容忍
• 去敏：永不出现密钥 / 密码 / token / 机器指纹原始字节；license 只有状态摘要
• gpus 无独显时为 []；providers 未装任何包时为 []

会话元信息 JSON

darra_session_meta_json 输出：

{
  "schema": 1,
  "task": "detect",
  "labels": ["scratch", "dent"],
  "input": { "width": 640, "height": 640, "channels": 3 },
  "payloadKind": "onnx",
  "provider": "onnx-cuda",
  "encrypted": true,
  "containerFormat": "DARM1",
  "license": { "mode": "trial", "trialRemaining": 12, "machineBound": true }
}

• task 派生短名随容器头；推理结果 results 元素结构以此为准。缺席不编 detect。头文件对结果形态的承诺：detect→box，classify→top-k，segment→掩码
• payloadKind：onnx / trt-engine / openvino / rknn / paddle。Paddle 是运行时载荷。Windows 上 rknn 打不开会话
• input.width / height / channels 来自容器头。缺则 null，不编 640/80/17
• provider 是实际选中的 Provider（不是 prefer 入参）
• encrypted=false 时无 containerFormat / license（明文会话）
• 标准字段表见 元数据

推理结果 JSON

darra_session_infer_image 输出：

{
  "schema": 1,
  "task": "detect",
  "provider": "onnx-cuda",
  "elapsedMs": 3.2,
  "image": { "width": 1920, "height": 1080 },
  "results": [ { "label": "scratch", "score": 0.93, "box": [120, 40, 36, 18] } ]
}

• envelope 字段（schema / task / provider / elapsedMs / image / results）恒定；results 元素随 task 而变：
  • detect：{label, score, box:[x,y,w,h]}
  • classify：{label, score} top-k 按分降序
  • segment：{label, score, maskRle}
  • 其余 task 的逐元素 schema 随对应 Provider 落地，本契约只承诺 envelope
• 结果坐标基于 image 字段（解码后、送入模型前的尺寸）；裸缓冲输入时等于 desc 的宽高
• 永不包含模型明文、密钥等任何敏感字节