AI 检测接口说明文档

文档版本	V1.0
修订日期	2026-08-20
对应头文件	`components/media/framework/api/include/api_aidetect.h`
类型定义	`components/media/framework/api/include/api_aidetect.h`、`components/media/framework/component_adapter/aidetect/include/fw_aidetect.h`
适用模块	AI 目标检测（AIDetect / AIDETECT）

1 概述

本模块对外提供 hi_fw_aidetect_* 系列接口，封装 AI 目标检测能力：应用指定 VPSS 图像源与模型路径创建检测任务，框架内部创建 SVP/MPI 检测通道（ss_mpi_aidetect_*）、加载模型并启动检测线程，按固定间隔从 VPSS 取帧推理，检测结果经回调异步上报，支持 4 类目标（人脸、人形、宠物、包裹）。此外支持任务运行状态查询（get_status），跨进程模式下还支持多客户端订阅同一任务的结果与状态推送。

支持两种运行模式：

直连模式（Direct）：应用与检测服务同进程，通过 hi_fw_aidetect_direct_init() 启动，检测结果由检测线程同步派发；
跨进程模式（IPC / Client）：应用与检测服务分进程，通过 hi_fw_aidetect_client_init() 建立客户端，检测结果与任务状态由服务端异步推送。

模型层次：

AI 检测模块
  └─ 检测任务（hi_fw_aidetect_handle = 任务槽下标，共 8 个槽位）
       ├─ 模型（model_path，12 类目标检测模型）
       ├─ 数据源（VPSS 组 / 通道）
       ├─ 检测线程（按 interval_ms 取帧 → 推理 → 回调上报结果）
       └─ 订阅（IPC：多客户端可订阅同一任务的 结果/状态 推送）

2 接口总览

编号	接口	模块	功能概述
1	`hi_fw_aidetect_direct_init`	模式管理	初始化直连模式检测模块
2	`hi_fw_aidetect_direct_deinit`	模式管理	反初始化直连模式检测模块
3	`hi_fw_aidetect_client_init`	模式管理	初始化跨进程模式检测客户端
4	`hi_fw_aidetect_client_deinit`	模式管理	反初始化跨进程模式检测客户端
5	`hi_fw_aidetect_create_task`	任务管理	创建检测任务
6	`hi_fw_aidetect_destroy_task`	任务管理	销毁检测任务
7	`hi_fw_aidetect_start_task`	任务管理	启动检测任务
8	`hi_fw_aidetect_stop_task`	任务管理	停止检测任务
9	`hi_fw_aidetect_set_interval`	任务属性	设置检测间隔
10	`hi_fw_aidetect_get_interval`	任务属性	获取检测间隔
11	`hi_fw_aidetect_get_status`	任务属性	查询任务是否在运行
12	`hi_fw_aidetect_register_task`	订阅	本地绑定已有任务的回调（IPC）
13	`hi_fw_aidetect_subscribe`	订阅	订阅任务的结果 / 状态推送（IPC）
14	`hi_fw_aidetect_unsubscribe`	订阅	取消订阅任务推送（IPC）

3 API 参考

3.1 hi_fw_aidetect_direct_init

【描述】

初始化直连模式 AI 检测模块，创建检测服务实现（aidetect_impl）并初始化 light_msg 消息通道。仅在直连模式下调用。

【语法】

td_s32 hi_fw_aidetect_direct_init(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	初始化成功。
`非0`	初始化失败，返回 light_msg 通道错误码（见 5.3）。

【注意】

仅在直连模式下调用；跨进程模式应调用 hi_fw_aidetect_client_init()；
需在 hi_fw_aidetect_create_task() 之前调用；
幂等：已初始化时重复调用返回成功。

【举例】

td_s32 ret = hi_fw_aidetect_direct_init();
if (ret != 0) {
    /* 处理失败 */
}

3.2 hi_fw_aidetect_direct_deinit

【描述】

反初始化直连模式 AI 检测模块，销毁消息通道与检测服务实现。

【语法】

td_void hi_fw_aidetect_direct_deinit(td_void);

【参数】

无。

【返回值】

无。

【注意】

与 hi_fw_aidetect_direct_init() 成对调用；
调用前应先销毁所有任务（hi_fw_aidetect_destroy_task()），否则已创建的任务由反初始化兜底清理。

【举例】

hi_fw_aidetect_direct_deinit();

3.3 hi_fw_aidetect_client_init

【描述】

初始化跨进程模式 AI 检测客户端，建立应用进程到检测服务进程的 channel 通道，并注册结果 / 状态异步推送回调分发。仅在跨进程模式下调用。

【语法】

td_s32 hi_fw_aidetect_client_init(const td_char *endpoint);

【参数】

参数名称	输入/输出	类型	描述
`endpoint`	输入	`const td_char *`	端点地址（服务端 channel 端点标识）。为 `NULL` 或空串时使用默认端点 `/tmp/ipc_aidetect_test.sock`。

【返回值】

返回值	描述
`0`	初始化成功。
`-1`	初始化失败（`TD_FAILURE`）。

【注意】

仅在跨进程（IPC）模式下调用；直连模式应调用 hi_fw_aidetect_direct_init()；
重复调用（已初始化状态）返回成功，不重复创建通道；
若推送回调注册失败，仅记录警告，任务接口仍可用但无法收到异步推送。

【举例】

td_s32 ret = hi_fw_aidetect_client_init("/tmp/ipc_aidetect_test.sock");
if (ret != 0) {
    /* 处理失败 */
}

3.4 hi_fw_aidetect_client_deinit

【描述】

反初始化跨进程模式 AI 检测客户端：使所有本地任务失效并等待回调退出，释放本地资源并销毁 channel 通道。

【语法】

td_s32 hi_fw_aidetect_client_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
`0`	反初始化成功。
`-1`	反初始化失败（`TD_FAILURE`）。

【注意】

与 hi_fw_aidetect_client_init() 成对调用；
未初始化状态下调用返回成功（幂等）；
仅释放本地资源：服务端任务需在反初始化前显式 hi_fw_aidetect_destroy_task()，否则服务端任务持续存在；
内部会等待进行中的回调结束后再释放资源，不会出现回调悬挂。

【举例】

hi_fw_aidetect_client_deinit();

3.5 hi_fw_aidetect_create_task

【描述】

创建一路检测任务：加载模型、创建 SVP 检测通道与检测线程（线程处于就绪态，需 start 后开始推理），绑定数据源与结果 / 状态回调。创建成功后经 handle 返回任务句柄（0 ~ 7 的任务槽下标）。

【语法】

td_s32 hi_fw_aidetect_create_task(const hi_fw_aidetect_task_attr *attr,
                                  hi_fw_aidetect_handle *handle);

【参数】

参数名称	输入/输出	类型	描述
`attr`	输入	`const hi_fw_aidetect_task_attr *`	任务属性（模型路径、回调、间隔、数据源），不能为 `NULL`。
`handle`	输入/输出	`hi_fw_aidetect_handle *`	输出任务句柄（任务槽下标），不能为 `NULL`；失败时置为 `HI_FW_AIDETECT_INVALID_HANDLE`（-1）。

【返回值】

返回值	描述
`0`	创建成功，`handle` 为有效任务槽下标（0 ~ 7）。
`非0`	创建失败。API 层参数错误、槽位已满返回 `-1`（`TD_FAILURE`）；直连模式下底层错误码透传（见 5.2），如模型路径为空、回调不完整等。

【注意】

前置条件：已完成模式初始化（direct_init / client_init）；
attr->model_path 必须非空，指向可加载的检测模型文件；
attr->on_result 回调必须注册（未注册将无结果上报）；
数据源仅支持 VPSS 类型（HI_FW_AIDETECT_SOURCE_VPSS），跨进程模式下仅接受 VPSS 源，其他类型返回 -1；
最多同时 8 路任务（HI_FW_AIDETECT_MAX_TASK），槽位用尽返回 -1；
interval_ms 为 0 时使用默认值 100 ms（直连 / 跨进程模式行为一致）；
跨进程模式下 model_path 最长 255 字节（超出截断），直连模式无此限制；
跨进程模式创建者自动订阅：创建任务的客户端自动订阅该任务的结果 / 状态推送，无需再调用 hi_fw_aidetect_subscribe()。

【举例】

static void on_detect_result(hi_fw_aidetect_handle handle,
                             const hi_fw_aidetect_result *result)
{
    printf("task[%d] detect %u objects\n", handle, result->count);
    for (td_u32 i = 0; i < result->count; i++) {
        printf("  cls=%d conf=%.2f [%d,%d %ux%u]\n",
               result->objs[i].type, result->objs[i].confidence,
               result->objs[i].rect.x, result->objs[i].rect.y,
               result->objs[i].rect.width, result->objs[i].rect.height);
    }
}

static void on_detect_state(hi_fw_aidetect_handle handle,
                            hi_fw_aidetect_task_state state)
{
    printf("task[%d] state=%d\n", handle, state);
}

hi_fw_aidetect_task_attr attr = {0};
hi_fw_aidetect_handle handle = HI_FW_AIDETECT_INVALID_HANDLE;

attr.model_path  = "/customer/models/aidetect.om";
attr.on_result   = on_detect_result;
attr.on_state    = on_detect_state;
attr.interval_ms = 200;
attr.src.type     = HI_FW_AIDETECT_SOURCE_VPSS;
attr.src.vpss.vpss_grp = 0;
attr.src.vpss.vpss_chn = 0;

td_s32 ret = hi_fw_aidetect_create_task(&attr, &handle);
if (ret != 0) {
    /* 处理失败 */
}

3.6 hi_fw_aidetect_destroy_task

【描述】

销毁检测任务：停止检测线程、释放 SVP 检测通道与模型资源，释放任务槽位。销毁后句柄失效，不可再使用。

【语法】

td_s32 hi_fw_aidetect_destroy_task(hi_fw_aidetect_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄（0 ~ 7），不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。

【返回值】

返回值	描述
`0`	销毁成功。
`非0`	销毁失败。句柄越界、任务不可用返回 `-1`；直连模式下底层错误码透传（如任务已销毁）。

【注意】

与 hi_fw_aidetect_create_task() 成对调用；
建议先 hi_fw_aidetect_stop_task() 再销毁；未停止时销毁会直接终止检测线程；
跨进程模式下，销毁会同步通知服务端释放资源并清除订阅，随后等待回调退出；
销毁后任务槽可被后续 create_task 复用。

【举例】

hi_fw_aidetect_destroy_task(handle);
handle = HI_FW_AIDETECT_INVALID_HANDLE;

3.7 hi_fw_aidetect_start_task

【描述】

启动检测任务：检测线程开始按间隔从数据源取帧推理，结果经回调上报。

【语法】

td_s32 hi_fw_aidetect_start_task(hi_fw_aidetect_handle handle, td_s32 count);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄，不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。
`count`	输入	`td_s32`	检测帧数：`-1` 表示不限帧数持续检测（直到 `stop`）；`>= 0` 表示检测 `count` 帧后自动暂停（回到就绪态，可再次 `start`）。

【返回值】

返回值	描述
`0`	启动成功。
`非0`	启动失败。句柄越界、任务不可用返回 `-1`；直连模式下底层错误码透传，如任务已在运行返回 `OT_ERR_AIDETECT_EXIST`。

【注意】

需在 hi_fw_aidetect_create_task() 成功之后调用；
运行中重复 start 返回资源已存在错误（直连模式）；
达到 count 帧后任务自动暂停，再次 start 可重新开始（计数清零）。

【举例】

td_s32 ret = hi_fw_aidetect_start_task(handle, -1);  /* 持续检测 */
if (ret != 0) {
    /* 处理失败 */
}

3.8 hi_fw_aidetect_stop_task

【描述】

停止检测任务：检测线程停止取帧推理，任务回到就绪态。

【语法】

td_s32 hi_fw_aidetect_stop_task(hi_fw_aidetect_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄，不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。

【返回值】

返回值	描述
`0`	停止成功。
`非0`	停止失败。句柄越界、任务不可用返回 `-1`；直连模式下底层错误码透传。

【注意】

未启动状态下调用返回成功（幂等）；
与 hi_fw_aidetect_start_task() 成对调用；
跨进程模式：停止成功后服务端向该任务所有订阅者推送状态事件（HI_FW_AIDETECT_STATE_STOPPED），触发各客户端的 on_state 回调。

【举例】

hi_fw_aidetect_stop_task(handle);

3.9 hi_fw_aidetect_set_interval

【描述】

设置检测间隔（两次取帧推理的间隔毫秒数），可运行中动态调整，下一轮检测即生效。

【语法】

td_s32 hi_fw_aidetect_set_interval(hi_fw_aidetect_handle handle, td_u32 interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄，不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。
`interval_ms`	输入	`td_u32`	检测间隔（毫秒），不能为 `0`；为 `0` 时 API 层直接返回 `-1`。

【返回值】

返回值	描述
`0`	设置成功。
`非0`	设置失败。参数非法返回 `-1`；直连模式下底层错误码透传。

【注意】

间隔越短，CPU / NPU 占用越高，需结合实际场景选择；
跨进程模式下设置成功后会同步更新本地缓存，hi_fw_aidetect_get_interval() 返回最新值。

【举例】

td_s32 ret = hi_fw_aidetect_set_interval(handle, 500);
if (ret != 0) {
    /* 处理失败 */
}

3.10 hi_fw_aidetect_get_interval

【描述】

获取当前检测间隔（毫秒）。

【语法】

td_s32 hi_fw_aidetect_get_interval(hi_fw_aidetect_handle handle, td_u32 *interval_ms);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄，不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。
`interval_ms`	输出	`td_u32 *`	输出当前间隔（毫秒），不能为 `NULL`。

【返回值】

返回值	描述
`0`	获取成功，`interval_ms` 有效。
`非0`	获取失败。参数非法返回 `-1`；直连模式下底层错误码透传。

【注意】

interval_ms 为 NULL 时返回 -1；
未设置过间隔时返回创建时的默认值（100 ms）。

【举例】

td_u32 interval = 0;
td_s32 ret = hi_fw_aidetect_get_interval(handle, &interval);
if (ret != 0) {
    /* 处理失败 */
}

3.11 hi_fw_aidetect_get_status

【描述】

查询任务是否正在运行。直连模式经消息通道查询适配层任务状态；跨进程模式由服务端返回。

【语法】

td_s32 hi_fw_aidetect_get_status(hi_fw_aidetect_handle handle, td_bool *running);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄，不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。
`running`	输出	`td_bool *`	输出运行状态：`TD_TRUE` = 运行中，`TD_FALSE` = 未运行。不能为 `NULL`。

【返回值】

返回值	描述
`0`	获取成功，`running` 有效。
`非0`	获取失败。参数非法、任务不可用返回 `-1`；直连模式下底层错误码透传。

【注意】

running 为 NULL 或句柄无效时返回 -1，并先将 *running 置为 TD_FALSE；
与 on_state 状态回调互补：回调用于事件通知，本接口用于主动查询。

【举例】

td_bool running = TD_FALSE;
td_s32 ret = hi_fw_aidetect_get_status(handle, &running);
if (ret == 0 && running) {
    /* 任务运行中 */
}

3.12 hi_fw_aidetect_register_task

【描述】

本地绑定一个已有任务的回调（结果 / 状态），不通知服务端。用于跨进程模式下订阅其他进程创建的任务：先 register_task 绑定回调，再 subscribe 接收服务端推送。直连模式下为占位实现，直接返回成功。

【语法】

td_s32 hi_fw_aidetect_register_task(hi_fw_aidetect_handle handle,
                                    const hi_fw_aidetect_task_attr *attr);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	待绑定任务句柄（0 ~ 7），不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。
`attr`	输入	`const hi_fw_aidetect_task_attr *`	任务属性，用于取 `on_result` / `on_state` 回调与默认间隔，不能为 `NULL`。

【返回值】

返回值	描述
`0`	注册成功。
`非0`	注册失败。参数非法或该槽位已被本进程注册返回 `-1`。

【注意】

仅在跨进程模式有实际意义；直连模式恒返回成功；
同一进程对同一句柄只能注册一次，重复注册（槽位已占用）返回 -1；
注册时不会校验服务端任务是否存在，任务有效性在 subscribe 时校验；
attr 中仅 on_result / on_state / interval_ms 生效，model_path、src 被忽略。

【举例】

hi_fw_aidetect_task_attr attr = {0};
attr.on_result = on_detect_result;
attr.on_state  = on_detect_state;

td_s32 ret = hi_fw_aidetect_register_task(handle, &attr);
if (ret == 0) {
    (void)hi_fw_aidetect_subscribe(handle);
}

3.13 hi_fw_aidetect_subscribe

【描述】

订阅任务的结果 / 状态推送。跨进程模式下通知服务端将本客户端加入该任务的订阅列表，此后该任务的结果与状态事件会推送给本客户端。直连模式下为占位实现，直接返回成功。

【语法】

td_s32 hi_fw_aidetect_subscribe(hi_fw_aidetect_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄（0 ~ 7），不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。

【返回值】

返回值	描述
`0`	订阅成功。
`非0`	订阅失败。句柄非法返回 `-1`；服务端校验任务不存在时返回失败。

【注意】

仅在跨进程模式有实际意义；直连模式恒返回成功；
创建者无需调用：create_task 时服务端已自动将创建客户端加入订阅列表；
服务端校验任务存在（内部调用 get_status），任务不存在时订阅失败；
每个任务每客户端最多订阅一次，重复订阅返回成功（不重复加入）。

【举例】

td_s32 ret = hi_fw_aidetect_subscribe(handle);
if (ret != 0) {
    /* 处理失败 */
}

3.14 hi_fw_aidetect_unsubscribe

【描述】

取消订阅任务的结果 / 状态推送。跨进程模式下通知服务端将本客户端从该任务的订阅列表移除。直连模式下为占位实现，直接返回成功。

【语法】

td_s32 hi_fw_aidetect_unsubscribe(hi_fw_aidetect_handle handle);

【参数】

参数名称	输入/输出	类型	描述
`handle`	输入	`hi_fw_aidetect_handle`	任务句柄（0 ~ 7），不能为 `HI_FW_AIDETECT_INVALID_HANDLE`。

【返回值】

返回值	描述
`0`	取消订阅成功。
`非0`	取消订阅失败。句柄非法返回 `-1`。

【注意】

仅在跨进程模式有实际意义；直连模式恒返回成功；
客户端断开连接时，服务端自动清理其订阅记录，无需显式调用。

【举例】

hi_fw_aidetect_unsubscribe(handle);

4 数据类型

4.1 hi_fw_aidetect_handle（检测任务句柄）

【说明】

检测任务句柄，值为任务槽下标（整数索引），由 hi_fw_aidetect_create_task() 创建、hi_fw_aidetect_destroy_task() 释放。

【定义】

#define HI_FW_AIDETECT_MAX_TASK       8
#define HI_FW_AIDETECT_INVALID_HANDLE (-1)

typedef td_s32 hi_fw_aidetect_handle;

【成员】

常量	值	描述
`HI_FW_AIDETECT_MAX_TASK`	8	最大任务数（任务槽数量）。
`HI_FW_AIDETECT_INVALID_HANDLE`	-1	无效句柄，失败返回值 / 初始化值。

【注意事项】

有效句柄范围为 [0, HI_FW_AIDETECT_MAX_TASK)，其余值均为非法；
任务销毁后槽位可被后续任务复用，注意持有旧句柄的并发访问需自行加锁保护；
各接口对越界句柄返回 TD_FAILURE。

【相关数据类型及接口】

接口：hi_fw_aidetect_create_task、hi_fw_aidetect_destroy_task

4.2 hi_fw_aidetect_class（检测类别枚举）

【说明】

检测目标的类别。

【定义】

typedef enum {
    HI_FW_AIDETECT_CLASS_FACE          = 0,
    HI_FW_AIDETECT_CLASS_HUMAN         = 1,
    HI_FW_AIDETECT_CLASS_VEHICLE       = 2,
    HI_FW_AIDETECT_CLASS_PET           = 3,
    HI_FW_AIDETECT_CLASS_GARBAGE       = 4,
    HI_FW_AIDETECT_CLASS_BAG           = 5,
    HI_FW_AIDETECT_CLASS_WALLET        = 6,
    HI_FW_AIDETECT_CLASS_PHONE         = 7,
    HI_FW_AIDETECT_CLASS_HEAD_SHOULDER = 8,
    HI_FW_AIDETECT_CLASS_BICYCLE       = 9,
    HI_FW_AIDETECT_CLASS_MOTORCYCLE    = 10,
    HI_FW_AIDETECT_CLASS_PACKAGE       = 11,
    HI_FW_AIDETECT_CLASS_BUTT          = 12,
} hi_fw_aidetect_class;

【成员】

成员名称	值	描述
`HI_FW_AIDETECT_CLASS_FACE`	0	人脸。
`HI_FW_AIDETECT_CLASS_HUMAN`	1	人体。
`HI_FW_AIDETECT_CLASS_VEHICLE`	2	车辆。
`HI_FW_AIDETECT_CLASS_PET`	3	宠物。
`HI_FW_AIDETECT_CLASS_GARBAGE`	4	垃圾。
`HI_FW_AIDETECT_CLASS_BAG`	5	包。
`HI_FW_AIDETECT_CLASS_WALLET`	6	钱包。
`HI_FW_AIDETECT_CLASS_PHONE`	7	手机。
`HI_FW_AIDETECT_CLASS_HEAD_SHOULDER`	8	头肩。
`HI_FW_AIDETECT_CLASS_BICYCLE`	9	自行车。
`HI_FW_AIDETECT_CLASS_MOTORCYCLE`	10	摩托车。
`HI_FW_AIDETECT_CLASS_PACKAGE`	11	包裹。
`HI_FW_AIDETECT_CLASS_BUTT`	12	枚举结束标志（非法类别）。

【注意事项】

模型需支持对应类别才会输出该类目标；类别数值与底层 OT_AIDETECT_CLASS_* 一致。

【相关数据类型及接口】

类型：hi_fw_aidetect_object
接口：hi_fw_aidetect_create_task

4.3 hi_fw_aidetect_rect（检测框）

【说明】

检测目标在图像中的矩形框（像素坐标）。

【定义】

typedef struct {
    td_s32  x;
    td_s32  y;
    td_u32  width;
    td_u32  height;
} hi_fw_aidetect_rect;

【成员】

成员名称	描述
`x`	框左上角横坐标（像素）。
`y`	框左上角纵坐标（像素）。
`width`	框宽度（像素）。
`height`	框高度（像素）。

【注意事项】

坐标基于输入 VPSS 图像分辨率。

【相关数据类型及接口】

类型：hi_fw_aidetect_object

4.4 hi_fw_aidetect_object（检测目标）

【说明】

单个检测目标的框、置信度与类别。

【定义】

typedef struct {
    hi_fw_aidetect_rect  rect;
    td_float             confidence;
    hi_fw_aidetect_class type;
} hi_fw_aidetect_object;

【成员】

成员名称	描述
`rect`	检测框（像素坐标）。
`confidence`	置信度，取值 `[0, 1]`，越接近 1 越可信。
`type`	目标类别（见 `hi_fw_aidetect_class`）。

【注意事项】

无。

【相关数据类型及接口】

类型：hi_fw_aidetect_rect、hi_fw_aidetect_class、hi_fw_aidetect_result

4.5 hi_fw_aidetect_result（检测结果）

【说明】

一次检测的结果：目标数量与目标数组。

【定义】

typedef struct {
    td_u32                         count;
    const hi_fw_aidetect_object   *objs;
} hi_fw_aidetect_result;

【成员】

成员名称	描述
`count`	检测到的目标数量。
`objs`	目标数组首指针，`count == 0` 时可能为 `NULL`。

【注意事项】

objs 指向框架内部缓冲（直连模式为栈上数组、跨进程模式为推送报文），仅在结果回调执行期间有效；需要保存时必须在回调内完成拷贝；
直连模式单次最多上报 192 个目标（16 × 12 类），跨进程模式单次最多 32 个目标（超出部分丢弃并记录日志）。

【相关数据类型及接口】

类型：hi_fw_aidetect_object
回调：hi_fw_aidetect_result_cb

4.6 hi_fw_aidetect_task_state（任务状态枚举）

【说明】

任务状态，经 on_state 回调上报（当前跨进程模式下任务停止时上报 HI_FW_AIDETECT_STATE_STOPPED）。

【定义】

typedef enum {
    HI_FW_AIDETECT_STATE_RUNNING = 0,
    HI_FW_AIDETECT_STATE_STOPPED = 1,
} hi_fw_aidetect_task_state;

【成员】

成员名称	值	描述
`HI_FW_AIDETECT_STATE_RUNNING`	0	任务运行中。
`HI_FW_AIDETECT_STATE_STOPPED`	1	任务已停止。

【注意事项】

该枚举为对外状态集合（精简版）；底层适配层内部状态更细（IDLE / CREATED / RUNNING / STOPPING），不对外暴露；
直连模式下 on_state 当前不会触发，任务状态通过 hi_fw_aidetect_get_status() 主动查询。

【相关数据类型及接口】

回调：hi_fw_aidetect_state_cb
接口：hi_fw_aidetect_get_status、hi_fw_aidetect_stop_task

4.7 hi_fw_aidetect_state_cb（状态回调）

【说明】

任务状态变化上报回调，由服务端推送线程（跨进程模式）异步调用。

【定义】

typedef td_void (*hi_fw_aidetect_state_cb)(hi_fw_aidetect_handle handle,
                                           hi_fw_aidetect_task_state state);

【成员】

参数名称	描述
`handle`	触发回调的任务句柄。
`state`	任务状态（见 `hi_fw_aidetect_task_state`）。

【注意事项】

当前仅在跨进程模式下由服务端 stop_task 成功后推送触发（HI_FW_AIDETECT_STATE_STOPPED）；
回调在推送线程上下文中执行，回调内应避免长时间阻塞。

【相关数据类型及接口】

类型：hi_fw_aidetect_task_state
接口：hi_fw_aidetect_create_task、hi_fw_aidetect_register_task

4.8 hi_fw_aidetect_result_cb（结果回调）

【说明】

检测结果上报回调，由检测线程（直连）/ 服务端推送线程（跨进程）异步调用。

【定义】

typedef td_void (*hi_fw_aidetect_result_cb)(hi_fw_aidetect_handle handle,
                                            const hi_fw_aidetect_result *result);

【成员】

参数名称	描述
`handle`	触发回调的任务句柄。
`result`	检测结果（见 `hi_fw_aidetect_result`），仅回调期间有效。

【注意事项】

回调在检测 / 推送线程上下文中执行，回调内应避免长时间阻塞；
result->objs 仅回调期间有效，需保留数据须在回调内拷贝。

【相关数据类型及接口】

类型：hi_fw_aidetect_result
接口：hi_fw_aidetect_create_task

4.9 hi_fw_aidetect_source_type（数据源类型枚举）

【说明】

检测任务的数据源类型。

【定义】

typedef enum {
    HI_FW_AIDETECT_SOURCE_VPSS = 0,
    HI_FW_AIDETECT_SOURCE_BUTT
} hi_fw_aidetect_source_type;

【成员】

成员名称	值	描述
`HI_FW_AIDETECT_SOURCE_VPSS`	0	VPSS 通道图像源（当前唯一支持的数据源）。
`HI_FW_AIDETECT_SOURCE_BUTT`	1	枚举结束标志（非法类型）。

【注意事项】

跨进程模式下仅接受 HI_FW_AIDETECT_SOURCE_VPSS，其他类型创建任务直接失败。

【相关数据类型及接口】

类型：hi_fw_aidetect_source

4.10 hi_fw_aidetect_source_vpss（VPSS 数据源）

【说明】

VPSS 图像源标识：组号 + 通道号。

【定义】

typedef struct {
    td_u32 vpss_grp;
    td_u32 vpss_chn;
} hi_fw_aidetect_source_vpss;

【成员】

成员名称	描述
`vpss_grp`	VPSS 组号（0 起）。
`vpss_chn`	VPSS 通道号（0 起）。

【注意事项】

组号 / 通道号需与已建立的 VPSS 通路一致，否则取帧失败；
任务运行期间源通道应保持开启（start_task 时取帧）。

【相关数据类型及接口】

类型：hi_fw_aidetect_source

4.11 hi_fw_aidetect_source（数据源）

【说明】

数据源的统一描述：类型 + 联合体（当前仅 VPSS）。

【定义】

typedef struct {
    hi_fw_aidetect_source_type type;
    union {
        hi_fw_aidetect_source_vpss vpss;
    };
} hi_fw_aidetect_source;

【成员】

成员名称	描述
`type`	数据源类型（见 `hi_fw_aidetect_source_type`）。
`vpss`	VPSS 源（`type` 为 `HI_FW_AIDETECT_SOURCE_VPSS` 时有效）。

【注意事项】

创建任务前需先填充 type，再按类型填充对应联合体成员。

【相关数据类型及接口】

类型：hi_fw_aidetect_source_type、hi_fw_aidetect_source_vpss
接口：hi_fw_aidetect_create_task

4.12 hi_fw_aidetect_task_attr（任务属性）

【说明】

创建 / 绑定检测任务所需的属性：模型路径、结果 / 状态回调、检测间隔与数据源。

【定义】

typedef struct {
    const td_char            *model_path;
    hi_fw_aidetect_result_cb  on_result;
    hi_fw_aidetect_state_cb   on_state;
    td_u32                    interval_ms;
    hi_fw_aidetect_source     src;
} hi_fw_aidetect_task_attr;

【成员】

成员名称	描述
`model_path`	检测模型文件路径（非空；跨进程模式最长 255 字节）。
`on_result`	结果回调（建议注册，否则无结果上报）。
`on_state`	状态回调（可选，当前跨进程模式下任务停止时触发）。
`interval_ms`	检测间隔（毫秒），`0` 时使用默认值 100 ms。
`src`	数据源（类型 + VPSS 组 / 通道）。

【注意事项】

model_path 必须非空且可加载；创建失败（模型不存在 / 类别不支持）时返回错误；
任务属性在创建时一次性生效，运行中仅支持修改检测间隔（hi_fw_aidetect_set_interval）；
用于 hi_fw_aidetect_register_task() 时仅 on_result / on_state / interval_ms 生效。

【相关数据类型及接口】

类型：hi_fw_aidetect_source、hi_fw_aidetect_result_cb、hi_fw_aidetect_state_cb
接口：hi_fw_aidetect_create_task、hi_fw_aidetect_register_task

5 错误码

本模块接口统一返回 0（TD_SUCCESS）表示成功，非 0 表示失败。失败时的返回值来源有三类。

5.1 API 层参数校验错误（TD_FAILURE）

API 层对入参做前置校验，不合法直接返回 -1（TD_FAILURE），不进入消息通道：

错误码	触发场景
`-1`（`TD_FAILURE`）	句柄越界（`< 0` 或 `>= HI_FW_AIDETECT_MAX_TASK`）或任务不可用；`attr` / `handle` / `interval_ms` / `running` 指针为 `NULL`；`interval_ms == 0`；模式未初始化即调用；跨进程模式下调用 `direct_init`、使用非 VPSS 数据源、任务槽已满、`register_task` 槽位已占用；跨进程模式下 IPC 调用失败或服务端返回非成功。

5.2 底层错误码（OT_ERR_AIDETECT_*）

直连模式下，aidetect_impl 消息处理函数把 fw_aidetect_* 的返回值原样带回调用侧。底层错误码定义于 SDK 头文件 ot_common_aidetect.h，格式为 OT_DEFINE_ERR(OT_AIDETECT_MODULE_ID, OT_ERR_LEVEL_ERROR, errid)：

错误码宏	描述
`OT_ERR_AIDETECT_NULL_PTR`	输入参数空指针。
`OT_ERR_AIDETECT_ILLEGAL_PARAM`	输入参数非法（模型路径为空、回调不完整）。
`OT_ERR_AIDETECT_EXIST`	资源已存在（如运行中重复 `start_task`）。
`OT_ERR_AIDETECT_UNEXIST`	资源不存在（如任务已销毁、检测通道已满）。
`OT_ERR_AIDETECT_NOT_PERM`	操作不被允许（任务状态不允许当前操作）。

此外，底层 ss_mpi_aidetect_*（加载模型、创建 / 销毁通道等）失败时也会返回 MPP 错误码透传。错误码实际数值由 OT_DEFINE_ERR 宏展开，因模块 ID 而定。

5.3 通信 / 通道错误

直连模式（Direct）：light_msg 自身错误码可能作为返回值出现（如消息超时 LIGHT_MSG_EMSG_SYNC_MSG_TIMEOUT = 0x80002005、参数非法 LIGHT_MSG_EINVALARG = 0x80000003 等），数值远大于框架错误，可据此区分。
跨进程模式（IPC / Client）：channel_client 通信失败统一返回 TD_FAILURE（-1），无法区分具体原因，需结合服务端日志（HI_LOGE，模块名为 aidetect / aidetect_svr）定位。

说明：跨进程模式下所有失败统一收敛为 TD_FAILURE（-1）；由于 TD_FAILURE 与部分底层错误码数值相同，调用方应只依赖"0 = 成功、非 0 = 失败"的语义，不要依赖具体错误码数值。

6 使用注意事项

句柄范围：句柄为任务槽下标（0 ~ HI_FW_AIDETECT_MAX_TASK-1），无效值 HI_FW_AIDETECT_INVALID_HANDLE（-1）。任务销毁后槽位可复用，跨线程同时使用同一句柄需自行加锁；各接口对越界句柄返回 TD_FAILURE。

时序依赖：遵循以下启停顺序（停止为逆序）：

direct_init / client_init              // 模式初始化
  → create_task(attr, &handle)         // 创建任务（加载模型 + 创建通道 + 起线程）
    → set_interval(handle, ms)         // 设置间隔（可选）
    → start_task(handle, -1)           // 启动检测（count=-1 持续检测）
    → [回调] on_result(...)            // 结果异步上报
    → [查询] get_status(handle, &run)  // 主动查询运行状态

停止（逆序）：

stop_task(handle)
  → destroy_task(handle)
  → direct_deinit / client_deinit

资源配对：
- hi_fw_aidetect_direct_init() / hi_fw_aidetect_direct_deinit() 成对调用（直连模式）；
- hi_fw_aidetect_client_init() / hi_fw_aidetect_client_deinit() 成对调用（跨进程模式）；
- hi_fw_aidetect_create_task() / hi_fw_aidetect_destroy_task() 成对调用（跨进程模式销毁需显式调用，client_deinit 只释放本地资源）；
- hi_fw_aidetect_start_task() / hi_fw_aidetect_stop_task() 成对调用（count 限定帧数时任务会自动暂停，无需 stop）。
count 语义：start_task 的 count 参数：-1 持续检测直到 stop；>= 0 检测指定帧数后自动暂停（可再次 start 重新计数）。
结果回调有效性：result->objs 仅在回调执行期间有效（直连模式为栈上数组、跨进程模式为推送报文），需保留数据必须在回调内拷贝；单次最多目标数：直连 192 个、跨进程 32 个。
状态查询与回调：hi_fw_aidetect_get_status() 两个模式均可用；on_state 状态回调当前仅在跨进程模式下由服务端在 stop_task 成功后推送触发，直连模式下不触发。
订阅机制（IPC）：
- 创建者自动订阅（create_task 即订阅），无需手动 subscribe；
- 其他客户端订阅同一任务：register_task（本地绑定回调）→ subscribe（服务端登记推送）→ 接收结果 / 状态推送；unsubscribe 取消订阅，客户端断开时服务端自动清理订阅。
模式差异：
- 直连模式（Direct）：direct_init 启动，结果回调由检测 worker 线程同步派发；register_task / subscribe / unsubscribe 为占位实现恒返回成功，on_state 不触发；
- 跨进程模式（IPC）：client_init(endpoint) 启动，结果 / 状态由服务端异步推送，所有错误统一收敛为 TD_FAILURE；direct_init 在 IPC 模式不可用。
性能与资源：检测间隔 interval_ms 越短，CPU / NPU 占用越高；最多 8 路任务并发；任务运行期间 VPSS 源通道需保持开启。
回调线程：结果 / 状态回调在检测 / 推送线程上下文中执行，回调内应避免长时间阻塞或调用可能导致死锁的接口。

7 附注 / 关联文档

直连实现：components/media/framework/api/direct/aidetect/api_aidetect.c、aidetect_impl.c
跨进程客户端：components/media/framework/api/client/aidetect/api_aidetect.c
跨进程桥接：components/media/framework/api/ipc_bridge/aidetect/（aidetect_msg.c、aidetect_payload.h、aidetect_msg_id.h）
组件适配层：components/media/framework/component_adapter/aidetect/（fw_aidetect.h / fw_aidetect.c）
底层 SDK：sdk/AIComponent/Hi3516CV610_AIComponent_SDK_*/smp/a7_linux/source/out/include/ot_common_aidetect.h
关联接口：媒体框架 hi_fw_media_*（VPSS 通路建立，见 api_media.md）。