本页覆盖 SDK 实例的创建销毁、频道进出,以及全部回调的注册接口。
所有接口都是线程安全的。
rtc_set_log_level
设置全局日志级别,进程级生效,建议在 rtc_create 之前调用。
实例生命周期
rtc_create
创建一个 SDK 实例,返回实例句柄。后续所有频道相关接口都要传这个句柄。
一个句柄对应一个频道连接。需要同时连多个频道时,创建多个实例即可。
rtc_destroy
销毁实例并释放资源。SDK 保证 rtc_destroy 返回后不会再触发任何回调,因此可以安全地在它之后释放你传给回调的 context。
必须调用 rtc_destroy,否则实例资源不会释放。销毁后该句柄不可再使用。
加入与离开频道
rtc_join_channel
异步加入频道,立即返回。真正的连接结果通过连接状态回调(rtc_set_connection_callback)通知。
返回值
rtc_join_channel_sync
同步加入频道,阻塞直到连接成功、失败或超时。
返回值
rtc_leave_channel
离开频道。离开后实例仍然有效,可以再次加入。彻底不用时还需调用 rtc_destroy。
返回值:RTC_OK / RTC_INVALID_PARAM(句柄无效)。
自动订阅
rtc_set_auto_subscribe
设置是否自动订阅远端轨道。开启后,频道内所有已发布和新发布的对应类型轨道都会被自动订上,数据统一走轨道数据回调。
必须在加入频道之前调用,入会后再设置不会对已有轨道生效。
参与者想”听全场”,正确做法是 rtc_set_auto_subscribe(rtc, 1, 0) 订阅所有人的音频后在业务侧自行混音,不要去订阅音频合成流 —— 合成流包含自己的声音,会产生回声。
回调注册
所有回调都通过 context 参数携带业务上下文,SDK 原样回传,不做任何解释。
回调执行在 SDK 内部线程上,注意三点:
- 不同回调可能并发触发,业务侧要自己做并发保护
- 回调里不要做耗时操作,否则会阻塞 SDK 事件循环;耗时处理请入队后交给自己的线程
- 回调参数中的指针(
data、props、content_json、speakers 等)只在回调期间有效,需要留存必须立即拷贝
rtc_set_connection_callback
连接状态变化。state:0=连接中,1=已连接,2=已断开,3=重连中。
rtc_set_user_event_callback
用户进出频道。event_type:0=加入,1=离开。
rtc_set_track_event_callback
远端轨道的增删改。event_type:0=新增,1=更新,2=移除。手动订阅时用这个回调发现可订阅的轨道。
rtc_set_track_sample_callback
已订阅轨道的媒体数据。所有订阅的轨道(含合成流)都从这一个回调出来,用 user_info->uid + track_info->track_id 区分来源。
data 是完整的编码帧(视频为一帧,音频为一个编码包),指针仅在回调期间有效:
rtc_set_custom_msg_callback
频道内自定义消息,详见 自定义消息。
SeaStart 专属回调
以下三个回调仅在频道使用 SeaStart 引擎时触发,其它引擎下不会回调。详见 SeaStart 进阶能力。
典型调用顺序