TiRTC Nano SDK API 参考

错误码

常量	值	含义
`TIRTC_E_INVALID_HANDLE`	-40001	连接句柄无效
`TIRTC_E_INVALID_PARAMETER`	-40002	参数错误
`TIRTC_E_INVALID_LICENSE`	-40003	License 格式错误
`TIRTC_E_TIMEOUTED`	-40004	操作超时
`TIRTC_E_BUSY`	-40005	发送缓冲区已满，视频帧被丢弃
`TIRTC_E_CONN_HAS_ERROR`	-40006	连接已出错，拒绝继续发送

类型

tirtc_conn_t

typedef struct _tirtc_conn *tirtc_conn_t;

表示一个点对点连接的不透明句柄。由 on_conn_accepted 或 TIRTCCONNECTCALLBACK 回调传出，生命周期到 on_disconnected 回调触发后结束（SDK 自动释放）。

TIRTCOPTION

通过 TiRtcSetOpt() 设置的配置项。

枚举值	data 类型	说明
`TIRTC_OPT_SERVICE_ENTRY`	`const char *`	服务入口地址，不设置则使用探鸽默认入口
`TIRTC_OPT_DEVICE_LICENSE`	—	设备 License（暂留）
`TIRTC_OPT_MAX_CONNECTIONS`	`int *`	最大连接数，用于受限设备资源规划
`TIRTC_OPT_NETWORK_TYPE`	`const char *`	联网方式：`"wifi"` 或 `"4g"`，默认 `"wifi"`
`TIRTC_OPT_ICCID`	`const char *`	4G SIM 卡 ICCID，`network=4g` 时必填
`TIRTC_OPT_WAKEUP`	`int *`	是否支持休眠唤醒：0 或 1，默认 0
`TIRTC_OPT_RESTRICTED_NETWORK`	`int *`	是否受限网络：0 或 1，默认 0
`TIRTC_OPT_MAX_SEND_BUFFER`	`uint32_t *`	发送缓冲区大小（字节），须在 `TiRtcInit()` 前设置。默认 512 KB；`CONFIG_SMALL_MEMORY` 下 100 KB

TIRTCMEDIA

媒体类型，填入 TIRTCFRAMEINFO.media。

枚举值	值	说明
`TIRTC_MEDIA_MESSAGE`	0	在媒体流内插入的消息帧
`TIRTC_AUDIO_PCM`	1	PCM 原始音频
`TIRTC_AUDIO_ALAW`	2	G.711 A-law
`TIRTC_AUDIO_AAC`	3	AAC 压缩音频
`TIRTC_AUDIO_OPUS`	4	Opus 压缩音频
`TIRTC_VIDEO_JPEG`	65	JPEG 图像帧
`TIRTC_VIDEO_H264`	66	H.264 视频帧
`TIRTC_VIDEO_H265`	67	H.265 视频帧

判断宏：

TIRTC_IS_AUDIO(mt)   // media 值属于音频范围 [1, 64]
TIRTC_IS_VIDEO(mt)   // media 值属于视频范围 [65, 127]

TIRTCAUDIOSAMPLE

音频采样规格，填入音频帧的 TIRTCFRAMEINFO.flags。

枚举值	说明
`TIRTC_AUDIOSAMPLE_8K16B1C`	8 kHz，16 bit，单声道
`TIRTC_AUDIOSAMPLE_16K16B1C`	16 kHz，16 bit，单声道
`TIRTC_AUDIOSAMPLE_8K16B2C`	8 kHz，16 bit，双声道
`TIRTC_AUDIOSAMPLE_16K16B2C`	16 kHz，16 bit，双声道

TIRTCFRAMEINFO

媒体帧头，紧随其后的是 payload 数据。

typedef struct TIRTCFRAMEINFO {
    uint8_t  stream_id;  // 流标识，取值 0~15，全局唯一（音频和视频不能共用同一个 stream_id）
    uint8_t  media;      // 媒体类型，取值见 TIRTCMEDIA
    uint8_t  flags;      // 视频：最低位为关键帧标志（TIRTC_FRAME_FLAG_KEY_FRAME）
                         // 音频：取值见 TIRTCAUDIOSAMPLE
    uint8_t  dummy;      // 预留，填 0
    uint32_t ts;         // 主机序时间戳，精度 ms
    uint32_t length;     // payload 字节长度，不含帧头自身
} TIRTCFRAMEINFO;

视频关键帧相关宏：

#define TIRTC_FRAME_FLAG_KEY_FRAME  0x01
#define TIRTC_IS_KEY_FRAME(flags)   ((flags) & TIRTC_FRAME_FLAG_KEY_FRAME)

注意： 每路视频流的第一帧必须是关键帧，否则该帧将被丢弃，直到收到关键帧为止。

TIRTCSYSEVENT

SDK 内部系统事件，通过 TIRTCCALLBACKS.on_event 回调通知。

枚举值	说明
`TiEVENT_SYS_STARTED`	SDK 已成功启动
`TiEVENT_SYS_STOPPED`	SDK 已停止
`TiEVENT_ACCESS_HIJACKING`	HTTP 请求被重定向（可能遭受中间人攻击）

TIRTCCALLBACKS

SDK 回调函数集合，传入 TiRtcStart()，不能指向临时变量。

typedef struct TIRTCCALLBACKS {
    void (*on_event)(int event, const void *data, int len);
    void (*on_conn_accepted)(tirtc_conn_t hconn);
    void (*on_conn_error)(tirtc_conn_t hconn, int error);
    void (*on_disconnected)(tirtc_conn_t hconn);
    void (*on_audio)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_video)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_message)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_data)(tirtc_conn_t hconn, uint32_t cmd, const void *data, uint32_t len);
    void (*on_request_iframe)(tirtc_conn_t hconn, uint8_t stream_id);
    int  (*on_request_video)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_release_video)(tirtc_conn_t hconn, uint8_t stream_id);
    int  (*on_request_audio)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_release_audio)(tirtc_conn_t hconn, uint8_t stream_id);
} TIRTCCALLBACKS;

回调	触发时机	说明
`on_event`	系统事件	`event` 取值见 `TIRTCSYSEVENT`
`on_conn_accepted`	设备端收到新的入站连接	`hconn` 为新连接句柄
`on_conn_error`	连接发生错误	之后在该连接上的发送操作将返回 `TIRTC_E_CONN_HAS_ERROR`
`on_disconnected`	连接完全关闭	此后 `hconn` 不再有效，SDK 自动释放；可在此回调内调用 `TiRtcConnGetUserData`
`on_audio`	收到对端音频帧
`on_video`	收到对端视频帧
`on_message`	收到对端流内消息（`media == 0`）
`on_data`	收到对端命令通道数据	`cmd` 的命令字格式见命令通道
`on_request_iframe`	对端请求立即发送关键帧
`on_request_video`	对端请求开始发送视频	返回 0 表示接受
`on_release_video`	对端请求停止发送视频
`on_request_audio`	对端请求开始发送音频	返回 0 表示接受
`on_release_audio`	对端请求停止发送音频

TIRTCCONNECTCALLBACK

typedef void (*TIRTCCONNECTCALLBACK)(int error, tirtc_conn_t hconn, void *user_data);

TiRtcConnect() 的结果回调。user_data 为调用时传入的上下文指针。error 为 0 时 hconn 有效。

TIRTCLOGCALLBACK

typedef void (*TIRTCLOGCALLBACK)(const char *log, uint32_t length);

日志输出回调，通过 TiRtcLogSetCallback() 设置。设置后 SDK 不再向控制台或文件输出日志。

生命周期

TiRtcGetVersion

const char *TiRtcGetVersion(void);

返回 SDK 版本字符串。

TiRtcInit

int TiRtcInit(void);

初始化 SDK 运行时。必须在 TiRtcStart() 之前调用。TIRTC_OPT_MAX_SEND_BUFFER 须在此函数之前设置才能生效。

TiRtcUninit

void TiRtcUninit(void);

释放 SDK 运行时资源。

TiRtcSetOpt

int TiRtcSetOpt(TIRTCOPTION opt, const void *data, uint32_t len);

设置全局配置项。配置调用时机与具体选项有关，详见 TIRTCOPTION。

返回值： 0 成功，TIRTC_E_INVALID_PARAMETER 表示 opt 或 data 非法。

TiRtcStart

int TiRtcStart(const char *license, const TIRTCCALLBACKS *cbs);

启动 SDK。

license：设备端 License，格式为 "<uuid>,<key>"。传 NULL 仅启动客户端功能（等同于 TiRtcStartClientOnly(cbs)）。
cbs：回调结构指针，不能指向临时变量。

返回值： 0 仅表示参数通过初步检查；实际启动结果通过 on_event(TiEVENT_SYS_STARTED, ...) 通知。

// 仅作为客户端使用的快捷宏
#define TiRtcStartClientOnly(cbs)  TiRtcStart(NULL, cbs)

TiRtcStop

int TiRtcStop(void);

停止 SDK。完成后通过 on_event(TiEVENT_SYS_STOPPED, ...) 通知。

连接管理

TiRtcConnect

int TiRtcConnect(const char *peer_id,
                 const char *token,
                 TIRTCCONNECTCALLBACK cb,
                 void *user_data);

发起 P2P 连接。

peer_id：目标设备的公开标识。
token：连接凭证，由业务服务器签发，SDK 透明使用不解析内容。
cb：连接结果回调，不能为 NULL。
user_data：透传给回调的用户上下文。

返回值： 0 表示发起成功，最终结果由 cb 通知。

TiRtcDisconnect

int TiRtcDisconnect(tirtc_conn_t hconn);

主动断开连接。断开完成后会收到 on_disconnected 回调，hconn 在回调触发后由 SDK 自动释放，调用方不需手动释放。

TiRtcConnSetUserData

int TiRtcConnSetUserData(tirtc_conn_t hconn, void *user_data);

将用户数据指针关联到连接，可通过 TiRtcConnGetUserData() 取回。

返回值： 0 成功，TIRTC_E_INVALID_HANDLE 表示 hconn 无效。

TiRtcConnGetUserData

void *TiRtcConnGetUserData(tirtc_conn_t hconn);

取回由 TiRtcConnSetUserData() 设置的用户数据指针。hconn 无效时返回 NULL。

TiRtcGetSendBufferUsed

size_t TiRtcGetSendBufferUsed(tirtc_conn_t hconn);

返回连接当前发送缓冲区已使用的字节数。可与 TIRTC_OPT_MAX_SEND_BUFFER 设置的上限对比，判断是否需要丢帧或限流。hconn 无效时返回 0。

媒体发送

TiRtcSendMedia

int TiRtcSendMedia(tirtc_conn_t hconn,
                   const TIRTCFRAMEINFO *pFi,
                   const void *frame);

发送媒体帧，线程安全，支持多线程并发调用。

传输策略：

视频： 每路视频流的第一帧必须是关键帧（TIRTC_FRAME_FLAG_KEY_FRAME）。缓冲区满时设置跳帧标志，丢弃后续非关键帧直到下一个关键帧到来。
音频： 直接入队，不设跳帧逻辑。
发送操作仅根据 pFi->media 选择传输策略，不检查 payload 内容。
stream_id 全局唯一，同一连接内音频和视频不能使用相同的 stream_id。
可在任意 stream 中传入 media == TIRTC_MEDIA_MESSAGE 的帧，帧头其余字段由开发者自行解释。

返回值：

返回值	含义
0	成功入队
`TIRTC_E_INVALID_HANDLE`	`hconn` 无效
`TIRTC_E_INVALID_PARAMETER`	`pFi` 为 NULL 或 media 类型非法
`TIRTC_E_CONN_HAS_ERROR`	连接已出错
`TIRTC_E_BUSY`	发送缓冲区已满，视频帧被丢弃

TciRtcSendVideo

inline int TciRtcSendVideo(tirtc_conn_t hconn,
                            const TIRTCFRAMEINFO *pFi,
                            const void *frame);

TiRtcSendMedia 的视频类型校验封装。若 pFi->media 不是视频类型则直接返回 TIRTC_E_INVALID_PARAMETER。

TciRtcSendAudio

inline int TciRtcSendAudio(tirtc_conn_t hconn,
                            const TIRTCFRAMEINFO *pFi,
                            const void *frame);

TiRtcSendMedia 的音频类型校验封装。若 pFi->media 不是音频类型则直接返回 TIRTC_E_INVALID_PARAMETER。

命令通道

SDK 在独立的 P2P 通道上提供基于命令字的双向数据传输，支持异步请求和乱序应答。

命令字格式

bit[31:16]  命令序号（SN），用于匹配请求与应答
bit[15]     请求/应答标志：0 = 新请求，1 = 应答
bit[14:0]   命令标识（cmd_id），0x1000 以下保留给 SDK 内部使用

TiRtcSendCommand

int TiRtcSendCommand(tirtc_conn_t hconn,
                     uint32_t cmd,
                     const void *data,
                     uint32_t length);

在命令通道上发送数据。cmd_id（低 15 位）须 ≥ 0x1000，否则返回 TIRTC_E_INVALID_PARAMETER。

TiRtcSendReq / TiRtcSendResp

// 发送请求（清除 bit15）
#define TiRtcSendReq(hconn, cmd, data, length) \
    TiRtcSendCommand(hconn, (cmd) & ~0x00008000, data, length)

// 发送应答（置位 bit15）
#define TiRtcSendResp(hconn, cmd, data, length) \
    TiRtcSendCommand(hconn, (cmd) | 0x00008000, data, length)

发送方收到应答时，应答的命令字中序号和 cmd_id 与请求相同，仅 bit15 置 1。

atomic_get_cmd_sn

uint32_t atomic_get_cmd_sn(void);

原子地返回下一个命令序号并自增（16 位循环）。SDK 内部命令与应用共享同一计数器。

正确的发送流程：

调用 atomic_get_cmd_sn() 获取序号
将带有该序号的命令处理器挂入等待队列
发送命令

必须先挂队列再发送，否则应答可能在处理器挂入前就已到达。

TiRtcRequestIFrame

int TiRtcRequestIFrame(tirtc_conn_t hconn, uint8_t stream_id);

请求对端在指定流上立即输出一个关键帧。触发对端 on_request_iframe() 回调。

TiRtcRequestVideo / TiRtcReleaseVideo

int TiRtcRequestVideo(tirtc_conn_t hconn, uint8_t stream_id);
int TiRtcReleaseVideo(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始／停止发送指定视频流。分别触发对端 on_request_video() / on_release_video() 回调。

TiRtcRequestAudio / TiRtcReleaseAudio

int TiRtcRequestAudio(tirtc_conn_t hconn, uint8_t stream_id);
int TiRtcReleaseAudio(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始／停止发送指定音频流。分别触发对端 on_request_audio() / on_release_audio() 回调。

日志

TiRtcLogConfig

void TiRtcLogConfig(int bOutputToConsole, const char *path, uint32_t size);

配置 SDK 内置日志（仅 Linux 平台有效）。

bOutputToConsole：非 0 时同时输出到 stdout。
path：日志文件路径，建议设在 tmpfs 中；传 NULL 不输出到文件。
size：日志文件最大字节数，超出后滚动覆盖。

TiRtcLogSetLevel

void TiRtcLogSetLevel(int level);

设置日志详细程度。level > 10 时同时将底层 WebRTC 库的日志级别设为 level - 10。

TiRtcLogSetCallback

void TiRtcLogSetCallback(TIRTCLOGCALLBACK cb);

设置日志输出回调。设置后 SDK 将所有日志内容通过回调传给应用，不再自行输出。传 NULL 可清除回调。通常用于无文件系统的小系统。

TiRTC Nano SDK API 参考 ​

错误码 ​

类型 ​

tirtc_conn_t ​

TIRTCOPTION ​

TIRTCMEDIA ​

TIRTCAUDIOSAMPLE ​

TIRTCFRAMEINFO ​

TIRTCSYSEVENT ​

TIRTCCALLBACKS ​

TIRTCCONNECTCALLBACK ​

TIRTCLOGCALLBACK ​

生命周期 ​

TiRtcGetVersion ​

TiRtcInit ​

TiRtcUninit ​

TiRtcSetOpt ​

TiRtcStart ​

TiRtcStop ​

连接管理 ​

TiRtcConnect ​

TiRtcDisconnect ​

TiRtcConnSetUserData ​

TiRtcConnGetUserData ​

TiRtcGetSendBufferUsed ​

媒体发送 ​

TiRtcSendMedia ​

TciRtcSendVideo ​

TciRtcSendAudio ​

命令通道 ​

命令字格式 ​

TiRtcSendCommand ​

TiRtcSendReq / TiRtcSendResp ​

atomic_get_cmd_sn ​

TiRtcRequestIFrame ​

TiRtcRequestVideo / TiRtcReleaseVideo ​

TiRtcRequestAudio / TiRtcReleaseAudio ​

日志 ​

TiRtcLogConfig ​

TiRtcLogSetLevel ​

TiRtcLogSetCallback ​