类型
darra_ai.h 导出的结构体、枚举、宏与所有权约定。ABI 纪律：只导出 C 函数 + 不透明句柄 + 定长结构体；永不导出 C++ 类型 / STL。字符串一律 UTF-8。函数条目见各功能页，本页只列类型。
版本宏
darra_version() 返回打包值：major*65536 + minor*256 + patch。绑定侧核对规则：运行时 major 必须 == 本头文件 DARRA_VERSION_MAJOR，否则 ABI 已破坏，禁止继续调用任何其它函数。函数见 版本与诊断。
| 宏 | 值 | 说明 |
|---|---|---|
| DARRA_VERSION_MAJOR | 1 | 头文件主版本 |
| DARRA_VERSION_MINOR | 0 | 头文件次版本 |
| DARRA_VERSION_PATCH | 0 | 头文件补丁版本 |
| DARRA_HEADER_VERSION | 打包值 | 本头打包值，供绑定与运行时比对 |
| DARRA_VERSION_ENCODE | 宏 | 打包宏 |
| DARRA_VERSION_DECODE_MAJOR | 宏 | 从打包值拆 major |
| DARRA_VERSION_DECODE_MINOR | 宏 | 从打包值拆 minor |
| DARRA_VERSION_DECODE_PATCH | 宏 | 从打包值拆 patch |
结构体 size
所有结构体首字段 uint32_t size，调用方填 sizeof(结构体)。SDK 只读写它认识的字段；旧头配新 dll/so 照常工作。新增函数只追加、不改旧签名；major 版本号变 = ABI 破坏。
darra_image_desc desc;
memset(&desc, 0, sizeof(desc));
desc.size = sizeof(darra_image_desc);
字符串所有权
所有 char** 出参返回的堆字符串都归 SDK 分配、调用方负责用 darra_string_free 释放；禁止 free() / delete[] / 跨堆释放（Windows 上 SDK 与调用方可能不是同一 CRT 堆）。
| 来源 | 释放 |
|---|---|
| char** 出参（diag / meta / infer 结果） | 必须 darra_string_free |
| darra_version_string() | 静态字符串，禁止释放 |
编码：UTF-8，SDK 保证 NUL 结尾。
类型索引
| 类型 | 说明 | 定义 |
|---|---|---|
| darra_session | 不透明会话句柄 | 会话 |
| darra_session_options | 打开选项（线程 / 亲和） | 打开 |
| darra_image_format | AUTO / ENCODED / RGB888 / BGR888 / GRAY8 / RGBA8888 | 推理 |
| darra_image_desc | 图像描述；调用方填 size | 推理 |
| darra_error_t | 线程局部错误槽 | 错误码 |
| darra_error_code | 错误码枚举 | 错误码 |
| darra_progress_cb | ensure 进度回调 | 运行时包 |
线程安全
| 函数 | 线程安全 | 备注 |
|---|---|---|
| darra_version / darra_version_string | 是 | 纯查询，不改错误槽 |
| darra_last_error / darra_clear_error | 是 | 只碰本线程槽 |
| darra_string_free | 是 | NULL 安全；重复释放 = 未定义行为 |
| darra_diag_collect | 是 | 耗时可到数百毫秒，禁止在 PLC 扫描周期调 |
| darra_runtime_ensure | 是 | 进程内互斥串行，重复 / 并发安全 |
| darra_runtime_ensure_cancel | 是 | 任意线程可调；进度回调内禁止 |
| darra_session_open / open_plain / open_ex / open_plain_ex | 是 | 各开各的会话可并发 |
| darra_session_meta_json | 是 | 只读会话内不可变数据 |
| darra_session_infer_image | 同会话可并发 | 吞吐扩展推荐每线程一个会话 |
| darra_session_close | 仅在不与其它调用并发时 | close 后句柄失效，再用 = 未定义行为 |
不同会话互不干扰，可并发。darra_session_close 禁止与任何在飞调用并发。