跳转到主要内容
本页覆盖 SDK 实例的创建销毁、频道进出,以及全部回调的注册接口。 所有接口都是线程安全的。

日志

rtc_set_log_level

设置全局日志级别,进程级生效,建议在 rtc_create 之前调用。

语言

rtc_set_language

设置语言(0.1.0 起),进程级生效,随时可调,调用后发出的请求即按新语言。 它决定服务端业务错误(错误码 ≥1000)原因文案的语言,即 rtc_get_last_error 取到服务端错误时 msg_buf 里的内容。SDK 自身错误(180xxx)的原因始终是英文,不受影响。 不调用时跟随系统语言:依次取环境变量 LC_ALL、LC_MESSAGES、LANG 中第一个非空的值。系统语言为 C / POSIX 或都未设置时,服务端按中文返回。

实例生命周期

rtc_create

创建一个 SDK 实例,返回实例句柄。后续所有频道相关接口都要传这个句柄。 一个句柄对应一个频道连接。需要同时连多个频道时,创建多个实例即可。

rtc_destroy

销毁实例并释放资源。0.0.11 起,rtc_destroy 会等正在执行的回调全部返回后才返回,返回后不再触发本实例的任何回调,此时可以安全释放你传给回调的 context。
  • 允许在本实例的回调里调用 rtc_destroy(包括断线回调)。此时只等其它线程上的回调,当前这个回调返回之前不要释放它的 context
  • 回调里如果有耗时操作(解码、写文件),rtc_destroy 会相应地等更久
  • rtc_leave_channel 和用 rtc_set_*_callback 替换回调都不会等正在执行的回调,不能作为释放 context 的时机
0.0.10 及更早版本没有上述保证:rtc_destroy 返回时可能仍有回调在执行,在断线回调里调用 rtc_destroy 还会卡死。使用旧版本时请不要在 rtc_destroy 后立即释放 context,也不要在断线回调里销毁实例;建议升级到 0.0.11。
必须调用 rtc_destroy,否则实例资源不会释放。销毁后该句柄不可再使用。

加入与离开频道

rtc_join_channel

异步加入频道,立即返回。真正的连接结果通过连接状态回调(rtc_set_connection_callback)通知。 返回值

rtc_join_channel_sync

同步加入频道,阻塞直到连接成功、失败或超时。 返回值

rtc_get_last_error

取该实例最近一次失败调用的错误详情(0.0.9 起)。入会、订阅、发布等接口返回非 RTC_OK 后调用。0.1.0 起,返回 RTC_INVALID_PARAM / RTC_NOT_CONNECTED 时也会记录(180031 / 180001)。 返回值:错误码,0 表示没有记录。 句柄本身无效时没有实例可记录,返回 0;rtc_write_sample 等只带轨道句柄的接口不记录。
每个实例只保留最近一条。同一实例上多个线程并发调用接口时,后失败的会覆盖先失败的。

rtc_leave_channel

离开频道。离开后实例仍然有效,可以再次加入。彻底不用时还需调用 rtc_destroy。 返回值:RTC_OK / RTC_INVALID_PARAM(句柄无效)。

自动订阅

rtc_set_auto_subscribe

设置是否自动订阅远端轨道。开启后,频道内所有已发布和新发布的对应类型轨道都会被自动订上,数据统一走轨道数据回调。
必须在加入频道之前调用,入会后再设置不会对已有轨道生效。
参与者想”听全场”,正确做法是 rtc_set_auto_subscribe(rtc, 1, 0) 订阅所有人的音频后在业务侧自行混音,不要去订阅音频合成流 —— 合成流包含自己的声音,会产生回声。

回调注册

所有回调都通过 context 参数携带业务上下文,SDK 原样回传,不做任何解释。
context 必须是真实指针(或 NULL)。不要把 1、2 这样的小整数强转成指针当 id 用:SDK 内部会把它当指针保存,遇到小于 4096 的值会判定为非法指针并直接终止进程。需要 id 时,请传指向该 id 的内存地址。
回调执行在 SDK 内部线程上,注意三点:
  1. 不同回调可能并发触发,业务侧要自己做并发保护
  2. 回调里不要做耗时操作,否则会阻塞 SDK 事件循环;耗时处理请入队后交给自己的线程
  3. 回调参数中的指针(data、props、content_json、speakers 等)只在回调期间有效,需要留存必须立即拷贝

rtc_set_connection_callback

连接状态变化。state:0=连接中,1=已连接,2=已断开,3=重连中。

rtc_set_disconnected_callback

彻底离开频道时触发一次(与连接状态回调的 state=2 同时机,且先于它触发),带上断线原因(0.0.9 起)。
用它区分”该不该自动重进”:被踢(KICKED)、被顶号(REPLACE)、频道销毁(DESTROY)时不应自动重进;心跳超时(TIMEOUT)等情况可以用新签发的 Token 重新加入。

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 进阶能力。

典型调用顺序