概述
本文档描述设备端公开 C API。接口线程安全（可任意线程调用），异步回调契约为：同步返回成功则一定回调，同步返回失败则一定不回调（个别接口另有说明）。推荐生命周期：tc_iot_init → tc_iot_login → 各业务模块 init → 业务运行 → 各业务模块 deinit → tc_iot_deinit。
SDK 模块一览：
API 索引：
核心生命周期（tc_iot.h）
函数列表 | 描述 |
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化） | |
反初始化 SDK；阻塞等待内部清理完成后返回 | |
使用三元组登录（异步 MQTT 连接，内部可重试） | |
登出并清除本地凭证（异步，无独立完成回调） | |
动态注册设备（同一时刻仅允许一路） | |
读取 NTP 同步后的 UTC 毫秒时间戳 |
物模型（tc_iot_data_model.h）
函数列表 | 描述 |
初始化物模型并订阅下行 topic | |
上报属性 | |
上报事件 | |
反初始化；同步清除单例后异步退订 |
音视频（tc_iot_av.h）
函数列表 | 描述 |
初始化 AV 模块并注册观察者（内部拷贝 observer） | |
反初始化 AV；同步清除单例后异步退订信令 | |
拉取联系人列表 | |
发起呼出 | |
接听呼入；仅在振铃态有效，否则回调 AV_ON_* | |
拒绝呼入；仅在振铃态有效 | |
创建视频推流通道 | |
创建全局唯一音频推流通道 | |
销毁视频通道 | |
销毁音频通道 | |
推送一帧视频（调用方线程同步） | |
推送一帧音频（调用方线程同步） |
AI 对话（tc_iot_aitalk.h）
函数列表 | 描述 |
初始化 AITalk | |
反初始化；阻塞等待内部 teardown 完成 | |
开始对话 | |
停止对话（异步投递，空闲时幂等成功） | |
发送一帧上行音频 | |
发送文本给 LLM | |
注册可供机器人呼叫的联系人 | |
打断机器人当前播报（连续模式下有效） |
核心生命周期（tc_iot.h）
核心生命周期（连接与设备身份）
线程模型
本头文件接口可在任意线程调用；内部序列化到名为 "iot" 的消息循环执行。
回调 / 通知模型
on_log：日志回调线程由内部日志模块决定，可能与调用方线程不同。
on_device_event：在 iot 消息循环侧触发；event_data 当前恒为 NULL； 回调内勿做耗时操作。ONLINE 仅表示 MQTT 已连，不携带校时， 壁钟请用 tc_iot_get_ntp_time（未就绪返回 NTP_TIME_NOT_READY）。
tc_iot_login_cb / tc_iot_dynamic_register_cb： 同步返回 SUCCESS 则一定会回调；同步失败则一定不回调。
生命周期
推荐顺序：tc_iot_init → tc_iot_login（等待回调成功）→ 各业务模块 init → 业务运行 → 各业务模块 deinit → tc_iot_deinit。 tc_iot_logout 可选；deinit 会断开 MQTT。
业务约束
重复 init 返回 ALREADY_INITIALIZED；未 init 调用业务接口返回 NOT_INITIALIZED。
tc_iot_init 同步 SUCCESS 仅表示任务已投递；异步初始化失败时后续 login 会以回调失败体现。
tc_iot_deinit 为阻塞接口；动态注册进行中时拒绝 deinit （DYNAMIC_REGISTER_BUSY）。
动态注册成功后的 device_key 须由调用方写入非易失存储， 再作为 device_secret 登录。
函数列表 | 描述 |
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化） | |
反初始化 SDK；阻塞等待内部清理完成后返回 | |
使用三元组登录（异步 MQTT 连接，内部可重试） | |
登出并清除本地凭证（异步，无独立完成回调） | |
动态注册设备（同一时刻仅允许一路） | |
读取 NTP 同步后的 UTC 毫秒时间戳 |
tc_iot_init
tc_iot_init
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化）
参数 | 描述 |
config | 初始化配置，不可为 NULL |
返回值 | 描述 |
任务已投递 | |
参数非法 | |
已初始化 | |
内存不足 |
tc_iot_deinit
tc_iot_deinit
(void) |
反初始化 SDK；阻塞等待内部清理完成后返回
返回值 | 描述 |
成功 | |
未初始化 | |
动态注册进行中 | |
内存不足 |
tc_iot_login
tc_iot_login
使用三元组登录（异步 MQTT 连接，内部可重试）
参数 | 描述 |
device_info | 设备三元组；product_id/device_id/device_secret 必填 |
callback | 登录结果回调；同步 SUCCESS 则一定回调，失败则不回调 |
返回值 | 描述 |
任务已投递 | |
参数非法 | |
未 init | |
内存不足 |
tc_iot_logout
tc_iot_logout
(void) |
登出并清除本地凭证（异步，无独立完成回调）
返回值 | 描述 |
任务已投递 | |
未 init | |
内存不足 |
tc_iot_dynamic_register
tc_iot_dynamic_register
动态注册设备（同一时刻仅允许一路）
成功后用回调中的 device_key 作为 device_secret 登录。
参数 | 描述 |
param | 注册参数 |
callback | 注册结果回调；同步 SUCCESS 则一定回调，失败则不回调 |
返回值 | 描述 |
任务已投递 | |
参数非法 | |
未 init | |
已有注册进行中 | |
内存不足 |
tc_iot_get_ntp_time
tc_iot_get_ntp_time
(uint64_t *utc_time_ms) |
读取 NTP 同步后的 UTC 毫秒时间戳
MQTT ONLINE 后异步触发同步；未完成前返回 NTP_TIME_NOT_READY。
参数 | 描述 |
utc_time_ms | 输出 UTC 毫秒时间戳，不可为 NULL |
返回值 | 描述 |
已同步并写入 | |
参数非法 | |
尚未同步完成 |
tc_iot_log_level_e
tc_iot_log_level_e
日志输出阈值（数值越大输出越详细）。 设置为某级别时，输出该级别及更严重的日志（不含更详细级别）。
枚举 | 取值 | 描述 |
TC_IOT_LOG_LEVEL_NONE | 0 | 关闭日志输出 |
TC_IOT_LOG_LEVEL_ERROR | 1 | 仅输出错误 |
TC_IOT_LOG_LEVEL_WARN | 2 | 输出警告与错误 |
TC_IOT_LOG_LEVEL_INFO | 3 | 输出信息、警告与错误 |
TC_IOT_LOG_LEVEL_DEBUG | 4 | 输出全部日志（含调试，最详细） |
tc_iot_device_event_type_e
tc_iot_device_event_type_e
设备在线状态事件（MQTT 连接态映射；不含墙钟时间）
枚举 | 取值 | 描述 |
TC_IOT_DEV_EVENT_ONLINE | 0 | MQTT 已连接（≠ NTP 已同步） |
TC_IOT_DEV_EVENT_OFFLINE | 1 | MQTT 已断开 |
TC_IOT_DEV_EVENT_RECONNECTING | 2 | MQTT 重连中 |
tc_iot_login_cb
tc_iot_login_cb
登录结果回调
参数 | 描述 |
error_code | |
error_message | 错误描述，可为 NULL |
tc_iot_dynamic_register_cb
tc_iot_dynamic_register_cb
动态注册结果回调
typedef void(* tc_iot_dynamic_register_cb) (tc_iot_error_e error_code, const char *error_message, const char *device_key)
参数 | 描述 |
error_code | |
error_message | 错误描述，可为 NULL |
device_key | 成功时为设备密钥；须在回调返回前拷贝并写入非易失存储， 再作为后续 login 的 device_secret |
物模型（tc_iot_data_model.h）
物模型（属性 / 事件 / 行为）
线程模型
本头文件接口可在任意线程调用；上报与下行处理在 iot 消息循环执行。
回调 / 通知模型
on_report_*_result_cb：上报结果（含超时）；user_data 为 report 传入值。
on_receive_property_changed_cb：云端属性控制。
on_receive_new_action_cb：收到行为调用；调用方填充 action_output_data_* 后返回 0 表示成功回复，非 0 表示失败回复； 回调返回后 action 对象即释放，禁止缓存指针。
生命周期
业务约束
标量类型用 data_value 对应字段；STRING 指针在构建 JSON 期间须有效。
可一次 report 多条；每条结果经 on_report_*_result_cb 返回。
OBJECT / ARRAY 枚举已预留，当前实现未支持，请勿使用。
函数列表 | 描述 |
初始化物模型并订阅下行 topic | |
上报属性 | |
上报事件 | |
反初始化；同步清除单例后异步退订 |
tc_iot_data_model_init
tc_iot_data_model_init
初始化物模型并订阅下行 topic
须 login 成功。
参数 | 描述 |
data_model_callback | 回调表 |
返回值 | 描述 |
成功 | |
重复初始化 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
投递到 iot 消息循环失败 | |
通用失败 |
tc_iot_data_model_report_property
tc_iot_data_model_report_property
上报属性
property_num > 0；同步 SUCCESS 表示发布任务已投递， 逐条结果经 on_report_property_result_cb 返回。
参数 | 描述 |
data_model_property | 属性数组 |
property_num | 数量 |
report_cb_user_data | 透传到结果回调 |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 | |
通用失败 |
tc_iot_data_model_report_event
tc_iot_data_model_report_event
上报事件
语义与 report_property 相同，结果经 on_report_event_result_cb。
参数 | 描述 |
data_model_event | 事件数组 |
event_num | 数量 |
event_cb_user_data | 透传到结果回调 |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 | |
通用失败 |
tc_iot_data_model_deinit
tc_iot_data_model_deinit
(void) |
反初始化；同步清除单例后异步退订
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 |
data_model_data_type_t
data_model_data_type_t
物模型数据类型
枚举 | 取值 | 描述 |
DATA_MODEL_DATA_TYPE_BOOL | 0 | 布尔 |
DATA_MODEL_DATA_TYPE_INT | 1 | 整数 |
DATA_MODEL_DATA_TYPE_FLOAT | 2 | 浮点 |
DATA_MODEL_DATA_TYPE_STRING | 3 | 字符串 |
DATA_MODEL_DATA_TYPE_ENUM | 4 | 枚举 |
DATA_MODEL_DATA_TYPE_TIME | 5 | 时间 |
DATA_MODEL_DATA_TYPE_OBJECT | 6 | 预留；当前实现未支持 |
DATA_MODEL_DATA_TYPE_ARRAY | 7 | 预留；当前实现未支持 |
data_model_event_type_t
data_model_event_type_t
事件类型
枚举 | 取值 | 描述 |
DATA_MODEL_EVENT_TYPE_INFO | 0 | 信息类事件 |
DATA_MODEL_EVENT_TYPE_ALERT | 1 | 告警类事件 |
DATA_MODEL_EVENT_TYPE_FAULT | 2 | 故障类事件 |
data_model_report_result_t
data_model_report_result_t
上报结果
枚举 | 取值 | 描述 |
DATA_MODEL_REPORT_SUCCESS | 0 | 云端接受 |
DATA_MODEL_REPORT_REJECTED | 1 | 云端拒绝 |
DATA_MODEL_REPORT_NO_RESPONSE | 2 | 无云端响应 |
DATA_MODEL_REPORT_LOCAL_TIMEOUT | 3 | 本地等待超时 |
data_model_bool_t
data_model_bool_t
布尔属性值类型
data_model_int_t
data_model_int_t
整型属性值类型
data_model_float_t
data_model_float_t
浮点属性值类型
data_model_string_t
data_model_string_t
字符串属性值类型（调用方持有指针）
data_model_enum_t
data_model_enum_t
枚举属性值类型
data_model_time_t
data_model_time_t
时间属性值类型（通常为 Unix 秒）
tc_iot_data_model_callback_t
tc_iot_data_model_callback_t
物模型回调表
音视频（tc_iot_av.h）
音视频通话 / IPC 监控
线程模型
本头文件接口可在任意线程调用；信令类操作投递到 iot 消息循环。 push_* 在调用方线程同步执行（写入 media_stream）。
回调 / 通知模型
tc_iot_av_observer_s：init 时拷贝；信令回调在 iot 消息循环触发； 音视频帧回调可能来自 TRTC 媒体线程；所有回调须尽快返回、勿阻塞。
tc_iot_av_operation_cb：call/accept/reject/hangup 的 MQTT 发布结果； 同步 SUCCESS 则一定回调，同步失败则一定不回调。
accept/reject/hangup 要求 callback 非 NULL；call 也应提供有效 callback。
生命周期
tc_iot_init + tc_iot_login 成功 → tc_iot_av_init → （可选提前）create_channel → 按会话推流 / 呼叫 API → destroy / hangup → tc_iot_av_deinit
推流时机
监控：收到 on_monitor_begin 后持续 push_*；on_monitor_end 后可停。 多路监控复用同一音频通道，每路视频会话期间仍须送音频。
VOIP：通话建立后再推（呼出等 on_call_accepted；呼入等 accept 成功）。
通道可预先 create；无活跃会话时 push 只写入 media_stream， 是否进房/上云由会话侧决定。
业务约束
视频通道槽位最多 4 个，channel_id 须唯一（可为任意正整数）。
音频通道全局仅 1 路；已存在时 create 返回 NULL，须复用指针。
push_audio_frame 仅接受 16-bit PCM；非 PCM 返回 INVALID_ARGUMENT。
视频 Annex-B；IDR 须含 SPS/PPS（H265 含 VPS）；不支持 B 帧。
监控与 VOIP 互斥由状态机约束（冲突时 AV_ON_*）。
tc_iot_av_get_contacts 当前为占位实现。
函数列表 | 描述 |
初始化 AV 模块并注册观察者（内部拷贝 observer） | |
反初始化 AV；同步清除单例后异步退订信令 | |
拉取联系人列表 | |
发起呼出 | |
接听呼入；仅在振铃态有效，否则回调 AV_ON_* | |
拒绝呼入；仅在振铃态有效 | |
创建视频推流通道 | |
创建全局唯一音频推流通道 | |
销毁视频通道 | |
销毁音频通道 | |
推送一帧视频（调用方线程同步） | |
推送一帧音频（调用方线程同步） |
tc_iot_av_init
tc_iot_av_init
初始化 AV 模块并注册观察者（内部拷贝 observer）
须在 login 成功且设备身份就绪后调用。
参数 | 描述 |
observer | 事件观察者，不可为 NULL |
返回值 | 描述 |
成功 | |
参数非法（空指针、非法取值等） | |
重复初始化 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
内存不足 | |
投递到 iot 消息循环失败 | |
通用失败 |
tc_iot_av_deinit
tc_iot_av_deinit
(void) |
反初始化 AV；同步清除单例后异步退订信令
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 |
tc_iot_av_get_contacts
tc_iot_av_get_contacts
拉取联系人列表
参数 | 描述 |
cursor | 分页游标；首页传 NULL 或空串 |
limit | 单页条数上限 |
callback | 结果回调；占位实现下不会触发 |
返回值 | 描述 |
占位实现固定返回成功 |
注意
当前为占位实现：同步返回 SUCCESS 且不触发 callback。
tc_iot_av_call
tc_iot_av_call
(const tc_iot_contact_s *contact, tc_iot_call_option_t option, tc_iot_av_operation_cb callback) |
发起呼出
参数 | 描述 |
contact | 被叫联系人 |
option | 媒体选项 |
callback | 操作结果回调 |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 |
tc_iot_av_accept
tc_iot_av_accept
接听呼入；仅在振铃态有效，否则回调 AV_ON_*
参数 | 描述 |
contact | 主叫联系人 |
callback | 操作结果回调，不可为 NULL |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 |
tc_iot_av_reject
tc_iot_av_reject
拒绝呼入；仅在振铃态有效
参数 | 描述 |
contact | 主叫联系人 |
callback | 操作结果回调，不可为 NULL |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 |
tc_iot_av_hangup
tc_iot_av_hangup
参数 | 描述 |
contact | 对端联系人 |
callback | 操作结果回调，不可为 NULL |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
投递到 iot 消息循环失败 |
tc_iot_create_video_channel
tc_iot_create_video_channel
创建视频推流通道
channel_id 全局唯一；同时最多 4 路。
参数 | 描述 |
channel_id | 通道 ID |
quality | 画质档位 |
返回值 | 描述 |
通道句柄；失败返回 NULL（未 init / id 冲突 / 已满 / OOM） |
tc_iot_create_audio_channel
tc_iot_create_audio_channel
() |
tc_iot_destroy_video_channel
tc_iot_destroy_video_channel
tc_iot_destroy_audio_channel
tc_iot_destroy_audio_channel
tc_iot_push_video_frame
tc_iot_push_video_frame
推送一帧视频（调用方线程同步）
须为视频通道。格式见 tc_iot_def.h（Annex-B；IDR 含参数集）。
参数 | 描述 |
av_channel | 视频通道 |
frame | 视频帧 |
返回值 | 描述 |
成功 | |
参数非法（空指针、非法取值等） |
tc_iot_push_audio_frame
tc_iot_push_audio_frame
推送一帧音频（调用方线程同步）
须为音频通道；仅接受 16-bit PCM。 同一通道生命周期内 sample_rate / channels 应保持稳定。
参数 | 描述 |
av_channel | 音频通道 |
frame | 音频帧 |
返回值 | 描述 |
成功 | |
参数非法（空指针、非法取值等） |
ptz_command_e
ptz_command_e
云台控制命令
枚举 | 取值 | 描述 |
PTZ_CMD_UP | 0 | 上仰 |
PTZ_CMD_DOWN | 1 | 下俯 |
PTZ_CMD_LEFT | 2 | 左转 |
PTZ_CMD_RIGHT | 3 | 右转 |
PTZ_CMD_ZOOM_IN | 4 | 放大 |
PTZ_CMD_ZOOM_OUT | 5 | 缩小 |
PTZ_CMD_STOP | 6 | 停止运动 |
tc_iot_av_channel_t
tc_iot_av_channel_t
不透明 AV 推流通道句柄
tc_iot_call_option_t
tc_iot_call_option_t
呼叫 / 监控媒体选项
tc_iot_av_operation_cb
tc_iot_av_operation_cb
呼叫操作完成回调（MQTT puback / 状态冲突结果）
参数 | 描述 |
error_code | 结果码 |
error_message | 错误描述，可为 NULL |
tc_iot_av_contacts_cb
tc_iot_av_contacts_cb
联系人列表回调（当前 get_contacts 为占位，不会触发）
typedef void(* tc_iot_av_contacts_cb) (tc_iot_error_e error_code, const char *error_message, const tc_iot_contact_s *contacts, uint32_t count, const char *next_cursor)
宏定义
宏 | 取值 | 描述 |
MAX_CUSTOM_DATA_LENGTH | 20 | call_option.custom_data 最大字节数（含结尾 '\\0' 由调用方自行保证） |
AI 对话（tc_iot_aitalk.h）
AI 对话（AITalk）
线程模型
回调 / 通知模型
observer：init 时保存；user_data 透传到各回调。
on_receive_bot_audio 等媒体/文本回调可能来自通道线程，须尽快返回。
on_error 尽量投递到 iot 消息循环。
tc_iot_aitalk_operation_cb（start_speak / register_contacts）： 同步 SUCCESS 则一定回调；同步失败则一定不回调 （非法 mode 例外：同步返回 INVALID_ARGUMENT 且同步调用 callback）。
生命周期
tc_iot_init → tc_iot_login → tc_iot_aitalk_init → （可选）register_contacts → start_speak → send_audio / send_text → stop_speak → tc_iot_aitalk_deinit
业务约束
当前仅支持 TC_IOT_AITALK_MODE_CONTINUOUS。
init 的 codec 须为 AAC / OPUS / G722。
send_audio：帧 codec 与 init 一致，或送 16-bit PCM（由 SDK 内部编码）。
推荐 16 kHz 单声道；frame_duration_ms 与 codec 匹配（如 20）。
下行 bot 音频格式由通道侧决定，以 on_receive_bot_audio 的 frame 字段为准（常见为 PCM）。
函数列表 | 描述 |
初始化 AITalk | |
反初始化；阻塞等待内部 teardown 完成 | |
开始对话 | |
停止对话（异步投递，空闲时幂等成功） | |
发送一帧上行音频 | |
发送文本给 LLM | |
注册可供机器人呼叫的联系人 | |
打断机器人当前播报（连续模式下有效） |
tc_iot_aitalk_init
tc_iot_aitalk_init
(const tc_iot_aitalk_init_params_s *init_params, const tc_iot_aitalk_observer_s *observer, void *user_data) |
初始化 AITalk
参数 | 描述 |
init_params | 初始化参数 |
observer | 事件观察者 |
user_data | 透传到各 observer 回调 |
返回值 | 描述 |
成功 | |
参数非法（空指针、非法取值等） | |
重复初始化 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
内存不足 |
tc_iot_aitalk_deinit
tc_iot_aitalk_deinit
(void) |
反初始化；阻塞等待内部 teardown 完成
若处于 Starting/Running，会先停止会话。
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 |
tc_iot_aitalk_start_speak
tc_iot_aitalk_start_speak
开始对话
仅支持 CONTINUOUS；会话已有效时立即成功回调。
参数 | 描述 |
mode | 对话模式 |
callback | 结果回调 |
返回值 | 描述 |
成功 | |
参数非法（空指针、非法取值等） | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
内存不足 | |
投递到 iot 消息循环失败 | |
通用失败 |
tc_iot_aitalk_stop_speak
tc_iot_aitalk_stop_speak
(void) |
停止对话（异步投递，空闲时幂等成功）
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
内存不足 | |
通用失败 |
tc_iot_aitalk_send_audio
tc_iot_aitalk_send_audio
发送一帧上行音频
同步 SUCCESS 表示任务已投递；未进房时内部可能丢弃。
参数 | 描述 |
frame | 音频帧 |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
通用失败 |
tc_iot_aitalk_send_text
tc_iot_aitalk_send_text
(const char *text) |
发送文本给 LLM
参数 | 描述 |
text | 文本；长度上限见实现（当前 1024） |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
通用失败 |
tc_iot_aitalk_register_contacts
tc_iot_aitalk_register_contacts
注册可供机器人呼叫的联系人
count ∈ [1, TC_IOT_AITALK_MAX_CONTACT_COUNT]。 结果缓存至下次会话；callback 报告缓存结果。
参数 | 描述 |
contacts | 联系人数组 |
contact_count | 数量 |
callback | 结果回调 |
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
参数非法（空指针、非法取值等） | |
内存不足 | |
通用失败 |
tc_iot_aitalk_interrupt
tc_iot_aitalk_interrupt
(void) |
打断机器人当前播报（连续模式下有效）
返回值 | 描述 |
成功 | |
核心或业务模块尚未 init / 内部 impl 未就绪 | |
通用失败 | |
TC_IOT_ERR_AITALK_* | TC_IOT_ERR_AITALK_NOT_SUPPORT：AITalk：能力或模式不支持（亦可经 on_error）； TC_IOT_ERR_AITALK_BOT_LEAVED：AITalk：机器人已离开会话； TC_IOT_ERR_AITALK_INVALID_PARAM：AITalk：参数非法； TC_IOT_ERR_AITALK_INTERNAL_ERROR：AITalk：内部错误； TC_IOT_ERR_AITALK_NOT_ACTIVATED：AITalk：服务未开通 / 未激活； TC_IOT_ERR_AITALK_SERVICE_EXPIRED：AITalk：服务已过期； TC_IOT_ERR_AITALK_ASR_ERROR：AITalk：ASR 错误； TC_IOT_ERR_AITALK_TTS_ERROR：AITalk：TTS 错误； TC_IOT_ERR_AITALK_LLM_ERROR：AITalk：LLM 错误 |
tc_iot_aitalk_mode_e
tc_iot_aitalk_mode_e
对话模式
枚举 | 取值 | 描述 |
TC_IOT_AITALK_MODE_CONTINUOUS | 0 | 连续对话（当前唯一可用模式） |
TC_IOT_AITALK_MODE_PUSH_TO_TALK | 1 | 按键说话；当前 start_speak 不接受该模式 |
tc_iot_aitalk_bot_state_e
tc_iot_aitalk_bot_state_e
机器人状态
枚举 | 取值 | 描述 |
TC_IOT_AITALK_BOT_STATE_LISTENING | 1 | 正在聆听用户语音 |
TC_IOT_AITALK_BOT_STATE_THINKING | 2 | 正在思考 / 推理 |
TC_IOT_AITALK_BOT_STATE_SPEAKING | 3 | 正在播报回复 |
TC_IOT_AITALK_BOT_STATE_INTERRUPTED | 4 | 播报被打断 |
TC_IOT_AITALK_BOT_STATE_FINISHED | 5 | 本轮对话结束 |
tc_iot_aitalk_operation_cb
tc_iot_aitalk_operation_cb
异步操作结果回调（start_speak / register_contacts）
宏定义
宏 | 取值 | 描述 |
TC_IOT_AITALK_BOT_ID_MAX_LEN | 16 | bot_id 最大长度（不含结尾 '\\0'） |
TC_IOT_AITALK_MAX_CONTACT_COUNT | 10 | register_contacts 单次最多联系人数 |
类型定义（tc_iot_def.h 及公共结构体）
音视频公共类型（AV / AITalk 共用）
帧所有权
tc_iot_*_frame 中的 data 由调用方持有。push / send 接口在返回前会拷贝 或同步消费完毕；回调中的 frame->data 仅在回调返回前有效，调用方如需 异步使用须自行拷贝。
格式约定
AV 上行音频：仅 PCM，16-bit 小端交错（单声道连续样本，立体声 LRLR…）；data_size 须与 sample_rate/channels/frame_duration_ms 一致（推荐 20ms）。SDK 内部可再编码为 AAC 供 TRTC。
AV 下行音频：observer 收到 PCM；sample_rate/channels 透传自解码帧 （由远端编码决定；当前未按进房 obtain 参数重采样）。
AV 上行视频：Annex-B 裸流（H264/H265）；不支持 B 帧。 type=IDR 时须将 SPS/PPS（H265 另含 VPS）与 IDR 放在同一缓冲； 先送 IDR 再送 P 帧，否则对端可能无法起播。
AITalk：init 指定编码格式；send_audio 可送同格式编码帧，或 PCM （init 为 AAC/OPUS/G722 时由 SDK 内部编码）。
tc_iot_audio_codec_e
tc_iot_audio_codec_e
音频编码类型
枚举 | 取值 | 描述 |
TC_IOT_AUDIO_CODEC_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_AUDIO_CODEC_PCM | 1 | PCM（AV push 仅接受此类型） |
TC_IOT_AUDIO_CODEC_AAC | 2 | AAC |
TC_IOT_AUDIO_CODEC_OPUS | 3 | Opus |
TC_IOT_AUDIO_CODEC_G722 | 4 | G.722 |
tc_iot_audio_sample_rate_e
tc_iot_audio_sample_rate_e
音频采样率（Hz）
枚举 | 取值 | 描述 |
TC_IOT_AUDIO_SAMPLE_RATE_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_AUDIO_SAMPLE_RATE_8000 | 8000 | 8 kHz |
TC_IOT_AUDIO_SAMPLE_RATE_16000 | 16000 | 16 kHz（推荐） |
TC_IOT_AUDIO_SAMPLE_RATE_32000 | 32000 | 32 kHz |
TC_IOT_AUDIO_SAMPLE_RATE_48000 | 48000 | 48 kHz |
tc_iot_audio_channel_e
tc_iot_audio_channel_e
音频声道数
枚举 | 取值 | 描述 |
TC_IOT_AUDIO_CHANNEL_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_AUDIO_CHANNEL_MONO | 1 | 单声道 |
TC_IOT_AUDIO_CHANNEL_STEREO | 2 | 立体声（样本交错 LRLR…） |
tc_iot_video_codec_e
tc_iot_video_codec_e
视频编码类型
枚举 | 取值 | 描述 |
TC_IOT_VIDEO_CODEC_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_VIDEO_CODEC_H264 | 1 | H.264 / AVC |
TC_IOT_VIDEO_CODEC_H265 | 2 | H.265 / HEVC |
TC_IOT_VIDEO_CODEC_MJPEG | 3 | Motion JPEG |
tc_iot_video_frame_type_e
tc_iot_video_frame_type_e
视频帧类型
枚举 | 取值 | 描述 |
TC_IOT_VIDEO_FRAME_TYPE_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_VIDEO_FRAME_TYPE_IDR | 1 | 关键帧 / IDR（缓冲须含 SPS/PPS，H265 另含 VPS） |
TC_IOT_VIDEO_FRAME_TYPE_P | 2 | P 帧（预测帧） |
tc_iot_video_rotation_e
tc_iot_video_rotation_e
视频旋转角度（度）
枚举 | 取值 | 描述 |
TC_IOT_VIDEO_ROTATION_0 | 0 | 不旋转 |
TC_IOT_VIDEO_ROTATION_90 | 90 | 顺时针 90° |
TC_IOT_VIDEO_ROTATION_180 | 180 | 180° |
TC_IOT_VIDEO_ROTATION_270 | 270 | 顺时针 270° |
tc_iot_video_quality_e
tc_iot_video_quality_e
视频画质档位（呼叫 option / 监控切换 / 建视频通道时使用）
枚举 | 取值 | 描述 |
TC_IOT_VIDEO_QUALITY_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_VIDEO_QUALITY_LD | 1 | 流畅（LD） |
TC_IOT_VIDEO_QUALITY_SD | 2 | 标清（SD） |
TC_IOT_VIDEO_QUALITY_HD | 3 | 高清（HD） |
TC_IOT_VIDEO_QUALITY_FHD | 4 | 超清（FHD） |
tc_iot_media_content_e
tc_iot_media_content_e
会话媒体内容类型
枚举 | 取值 | 描述 |
TC_IOT_MEDIA_CONTENT_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_MEDIA_CONTENT_AUDIO | 1 | 仅音频 |
TC_IOT_MEDIA_CONTENT_VIDEO | 2 | 仅视频 |
TC_IOT_MEDIA_CONTENT_AUDIO_VIDEO | 3 | 音视频 |
结构体与联合体
data_model_data_item_t
data_model_data_item_t
物模型数据项
字段 | 类型 | 描述 |
data_id | char * | 标识符（属性 / 事件参数 / 行为参数 ID） |
data_type | 数据类型 | |
data_value | 数据值；按 data_type 选用联合体字段 |
data_model_data_value_t
data_model_data_value_t
物模型数据值联合体（按 data_type 选用对应字段）
字段 | 类型 | 描述 |
value_bool | ||
value_int | ||
value_float | ||
value_string | ||
value_enum | ||
value_time |
tc_iot_aitalk_audio_option_s
tc_iot_aitalk_audio_option_s
会话音频参数
字段 | 类型 | 描述 |
codec | 会话编码；须为 AAC / OPUS / G722 | |
sample_rate | 采样率；推荐 16000 | |
frame_duration_ms | uint32_t | 单帧时长（毫秒）；须与 codec 匹配，推荐 20 |
tc_iot_aitalk_init_params_s
tc_iot_aitalk_init_params_s
AITalk 初始化参数
字段 | 类型 | 描述 |
bot_id | char | 机器人 ID；长度 ≤ TC_IOT_AITALK_BOT_ID_MAX_LEN |
audio_option | 会话音频参数 | |
prompt_variables_json | const char * | 可选；prompt 变量 JSON 字符串，生命周期须覆盖 init 异步过程 |
tc_iot_aitalk_observer_s
tc_iot_aitalk_observer_s
AITalk 事件观察者
字段 | 类型 | 描述 |
on_receive_bot_audio | 机器人下行音频；frame 仅在回调内有效 | |
on_receive_bot_text | void(* on_receive_bot_text) (const char *text, void *user_data) | 机器人下行文本 |
on_receive_asr_text | void(* on_receive_asr_text) (const char *text, void *user_data) | ASR 文本；仅最终结果（is_final）会回调 |
on_bot_state_changed | void(* on_bot_state_changed) (tc_iot_aitalk_bot_state_e old_state, tc_iot_aitalk_bot_state_e new_state, void *user_data) | 机器人状态变化 |
on_launch_call | 机器人发起呼叫联系人（需配合 register_contacts） | |
on_error | 会话或通道错误（含 AITALK_*） |
tc_iot_audio_frame
tc_iot_audio_frame
音频帧
字段 | 类型 | 描述 |
codec | 音频编码类型 | |
sample_rate | 采样率（Hz） | |
channels | 声道数 | |
frame_duration_ms | uint32_t | 单帧时长（毫秒）；须与 data_size 匹配；推荐 20 |
data | uint8_t * | PCM 时为 16-bit 小端样本；调用方持有 |
data_size | size_t | data 字节数 |
pts_ms | uint64_t | 呈现时间戳，毫秒；调用方保证单调 |
tc_iot_av_observer_s
tc_iot_av_observer_s
AV 事件观察者；字段可为 NULL 表示不关心该事件
字段 | 类型 | 描述 |
on_call_requested | App 呼入邀请 | |
on_call_accepted | 对端接听（呼出场景） | |
on_call_rejected | 对端拒绝 | |
on_call_timeout | 呼叫超时 | |
on_call_hangup | 对端挂断或会话中止 | |
on_monitor_begin | IPC 监控：App 开始拉流 | |
on_monitor_switch | IPC 监控：切换画质 | |
on_monitor_end | void(* on_monitor_end) (int channel_id) | IPC 监控：结束拉流 |
on_ptz_command_received | 收到云台控制命令；speed 为速度档位 | |
on_audio_frame_received | 远端音频：PCM；sample_rate/channels 透传自解码帧（随远端编码， 未按进房 obtain 重采样）；frame 仅回调内有效 | |
on_video_frame_received | 远端视频；frame 仅回调内有效 |
tc_iot_call_option_s
tc_iot_call_option_s
呼叫 / 监控媒体选项
字段 | 类型 | 描述 |
media_content | 媒体内容类型（音频 / 视频 / 音视频） | |
video_quality | 视频画质档位 | |
custom_data | char | 自定义附带数据；长度受 MAX_CUSTOM_DATA_LENGTH 约束 |
tc_iot_config_s
tc_iot_config_s
SDK 初始化配置
字段 | 类型 | 描述 |
storage_path | const char * | 本地持久化目录；可为 NULL；非空时长度须合法（实现侧上限约 256） |
log_level | ||
on_log | 可选；为 NULL 时不向外抛日志文本 | |
on_device_event | 可选；为 NULL 时不通知在线状态 |
tc_iot_contact_s
tc_iot_contact_s
联系人；呼叫相关 API 至少需要 user_id
字段 | 类型 | 描述 |
user_id | const char * | 用户 ID，必填 |
user_name | const char * | 显示名，可选 |
avatar_url | const char * | 头像 URL，可选 |
tc_iot_data_model_action_t
tc_iot_data_model_action_t
行为（下行调用 + 上行输出）
字段 | 类型 | 描述 |
action_id | char * | 行为 ID |
token | char * | 云端下发的请求 token，回复时须原样带回 |
timestamp | uint32_t | 时间戳 |
action_input_data_num | int | 输入参数个数 |
action_input_data_list | 输入参数列表 | |
action_output_data_num | int | 输出参数个数；在 on_receive_new_action_cb 内填写 |
action_output_data_list | 输出参数列表；在 on_receive_new_action_cb 内填写后由 SDK 回复云端 |
tc_iot_data_model_callback
tc_iot_data_model_callback
物模型回调表
字段 | 类型 | 描述 |
on_report_property_result_cb | void(* on_report_property_result_cb) (char *property_id, void *user_data, data_model_report_result_t result_code) | 属性上报结果（含超时）；user_data 为 report_property 传入值 |
on_receive_property_changed_cb | void(* on_receive_property_changed_cb) (char *property_id, tc_iot_data_model_property_t *data_model_property) | 云端下发属性变更 |
on_report_event_result_cb | void(* on_report_event_result_cb) (char *event_id, void *user_data, data_model_report_result_t result_code) | 事件上报结果（含超时）；user_data 为 report_event 传入值 |
on_receive_new_action_cb | 收到行为调用。 |
tc_iot_data_model_event_t
tc_iot_data_model_event_t
事件
字段 | 类型 | 描述 |
event_id | char * | 事件 ID |
event_type | 事件类型 | |
event_data_num | int | event_data_list 元素个数 |
event_data_list | 事件参数列表 |
tc_iot_data_model_property_t
tc_iot_data_model_property_t
属性
字段 | 类型 | 描述 |
property | 属性数据项 |
tc_iot_device_info_s
tc_iot_device_info_s
设备三元组（login 用）
字段 | 类型 | 描述 |
product_id | const char * | 产品 ID，必填 |
device_id | const char * | 设备名 / 设备 ID，必填 |
device_secret | const char * | 设备密钥，必填 |
region | const char * | 地域字符串（如 "ap-guangzhou"）；校验存在，当前登录链路未使用 |
tc_iot_dynamic_register_param_s
tc_iot_dynamic_register_param_s
动态注册参数
字段 | 类型 | 描述 |
product_id | const char * | 产品 ID，必填 |
device_id | const char * | 设备名 / 设备 ID，必填 |
product_secret | const char * | 产品密钥；长度须满足 [16, 64) |
tc_iot_video_frame
tc_iot_video_frame
视频帧（Annex-B 裸流）
字段 | 类型 | 描述 |
codec | 视频编码类型 | |
type | IDR 缓冲须含 SPS/PPS（H265 含 VPS）；P 帧不含参数集即可 | |
rotation | 画面旋转角度 | |
width | uint32_t | 像素宽度 |
height | uint32_t | 像素高度 |
data | uint8_t * | Annex-B 裸流；调用方持有；不可为 NULL，data_size > 0 |
data_size | size_t | data 字节数 |
pts_ms | uint64_t | 呈现时间戳，毫秒；调用方保证单调（热路径不做校验） |
错误码（tc_iot_err.h）
SDK 统一错误码
0 为成功，负数为失败。各模块返回值子集以对应头文件函数注释为准； 此处给出全量枚举含义。
tc_iot_error_e
tc_iot_error_e
SDK 统一错误码
枚举 | 取值 | 描述 |
TC_IOT_ERR_SUCCESS | 0 | 成功 |
TC_IOT_ERR_FAILURE | -1 | 通用失败 |
TC_IOT_ERR_OUT_OF_MEMORY | -2 | 内存不足 |
TC_IOT_ERR_INVALID_ARGUMENT | -3 | 参数非法（空指针、非法取值等） |
TC_IOT_ERR_NOT_INITIALIZED | -4 | 核心或业务模块尚未 init / 内部 impl 未就绪 |
TC_IOT_ERR_ALREADY_INITIALIZED | -5 | 重复初始化 |
TC_IOT_ERR_NOT_CONNECTED | -6 | MQTT 未连接，或操作因登出被取消 |
TC_IOT_ERR_ALREADY_CONNECTED | -7 | 已处于已连接状态（如重复 login） |
TC_IOT_ERR_CONNECT_FAILED | -8 | MQTT / 网络连接失败（非 CONNACK 细分码） |
TC_IOT_ERR_POST_TASK_FAILED | -9 | 投递到 iot 消息循环失败 |
TC_IOT_ERR_AV_ON_IDLE | -10 | AV：空闲，无对应会话（操作与状态机冲突） |
TC_IOT_ERR_AV_ON_OUTGOING | -11 | AV：正在呼出 |
TC_IOT_ERR_AV_ON_RINGING | -12 | AV：正在振铃（呼入） |
TC_IOT_ERR_AV_ON_CALLING | -13 | AV：已在通话中 |
TC_IOT_ERR_AV_ON_IPC_MONITOR | -14 | AV：处于 IPC 监控会话 |
TC_IOT_ERR_DYNAMIC_REGISTER_BUSY | -20 | 动态注册：已有注册进行中（含阻塞 deinit） |
TC_IOT_ERR_DYNAMIC_REGISTER_REQUEST_FAILED | -21 | 动态注册：请求发送或网络失败 |
TC_IOT_ERR_DYNAMIC_REGISTER_RESPONSE_INVALID | -22 | 动态注册：响应解析失败或内容非法 |
TC_IOT_ERR_NTP_TIME_NOT_READY | -30 | NTP 尚未同步完成（ONLINE 之后仍可能短暂返回此值） |
TC_IOT_ERR_AITALK_NOT_SUPPORT | -200 | AITalk：能力或模式不支持（亦可经 on_error） |
TC_IOT_ERR_AITALK_BOT_LEAVED | -201 | AITalk：机器人已离开会话 |
TC_IOT_ERR_AITALK_INVALID_PARAM | -202 | AITalk：参数非法 |
TC_IOT_ERR_AITALK_INTERNAL_ERROR | -203 | AITalk：内部错误 |
TC_IOT_ERR_AITALK_NOT_ACTIVATED | -204 | AITalk：服务未开通 / 未激活 |
TC_IOT_ERR_AITALK_SERVICE_EXPIRED | -205 | AITalk：服务已过期 |
TC_IOT_ERR_AITALK_ASR_ERROR | -206 | AITalk：ASR 错误 |
TC_IOT_ERR_AITALK_TTS_ERROR | -207 | AITalk：TTS 错误 |
TC_IOT_ERR_AITALK_LLM_ERROR | -208 | AITalk：LLM 错误 |
TC_IOT_ERR_CONNECT_UNACCEPTABLE_PROTOCOL_VERSION | -301 | MQTT CONNACK：不接受的协议版本 |
TC_IOT_ERR_CONNECT_IDENTIFIER_REJECTED | -302 | MQTT CONNACK：客户端标识被拒绝 |
TC_IOT_ERR_CONNECT_SERVER_UNAVAILABLE | -303 | MQTT CONNACK：服务端不可用 |
TC_IOT_ERR_CONNECT_BAD_USERNAME_OR_PASSWORD | -304 | MQTT CONNACK：用户名或密码错误 |
TC_IOT_ERR_CONNECT_NOT_AUTHORIZED | -305 | MQTT CONNACK：未授权 |
