房间管理
主要包括加入、离开房间,发布、取消、静默本地媒体流,订阅、取消订阅远端媒体流,远端用户的管理,以及服务端合流相关的配置等。
事件通知及日志配置
- 初始化
// 初始化配置日志输出
// @param event_ptr 用于接收 SDK 异步通知的 QNRtcEvent 结构体指针,非线程安全,离开房间前不可修改
// @param log_level 记录日志级别,LOG_DEBUG、LOG_INFO、LOG_WARNING、LOG_ERROR
// @param log_file_name 日志文件名,如果为空,则不输出日志文件
// @return 0:成功,其它请参考错误码列表
int qn_rtc_init(QNRtcEvent* event_ptr, QNRtcQNLogLevel log_level, char* log_file_name);
SDK 启动时,需首先初始化 SDK 事件接收实例指针,以及 log 输出配置,包括存储目录和文件名,中途不能修改;同时 SDK 为了保证磁盘占用过多从而导致其它问题,SDK 内部会自动保证 log 文件不会超过 1MBytes。
- 反初始化
// 释放 SDK 所有资源,与 qn_rtc_init 成对调用
void qn_rtc_uninit();
反初始化后,将释放 SDK 内部所有资源,且不能再调用其它任何接口。
断线重连
// 配置信令信令间隔,影响监控网络断开的灵敏度
// 间隔越低,越可以更快的检测到网络断开
// @param interval_seconds_ 信令心跳间隔,可设置范围为 1~ 10;单位:秒
virtual void SetHeartBeatInterval(int interval_seconds_ = 3) = 0;
此接口可用与配置 SDK 对于网络状态监控的灵敏度,值越低可以更快的检测到网络断开,并自动重连,SDK 内部每次重连间隔时间为 1 秒,直至重连成功。
注:需在加入房间前配置。
加入/离开房间
- 房间心跳配置
// 配置信令信令间隔,影响监控网络断开的灵敏度,需在 qn_rtc_join_room 前调用
// 间隔越低,越可以更快的检测到网络断开,默认为 3
// @param interval_seconds 信令心跳间隔,可设置范围为 1~ 10;单位:秒
void qn_rtc_set_heartbeat_interval(int interval_seconds);
只有在
qn_rtc_join_room
前调用才生效。
- 加入房间
// 加入房间
// @param room_token RoomToken,由上层向 APPServer 获取
// @param user_data 用户自定义数据,服务端会向其它端透传
// @param cb 加入房间结果异步通知,只有当返回 0 时才会触发
// @return 仅当返回 0 时才会触发 OnJoinResult 回调,否则请查看错误码列表
int qn_rtc_join_room(char* room_token, char* user_data);
此方法为异步方法,如果返回值为 0,则执行结果在 QNRoomListener::OnJoinResult
进行通知,错误码请参考错误码列表;加入房间成功后,才能进行发布、订阅、踢人、合流等操作;
注:
RoomToken
建议开发者的应用程序从自己产品的 Server 端获取,关于 Server 如何生成 token 可查阅服务端开发文档。
- 是否加入房间判断
// 是否已加入了房间
// @return 1:已加入; 0:未加入
int qn_rtc_is_join();
- 离开房间
// 离开房间,此为同步方法,没有异步回调
// @return 0:成功;其它请参考错误码列表
int qn_rtc_leave_room();
此方法为同步方法,没有回调通知;
踢人
- 将用户 user_id_ 踢出房间
// 踢出房间内指定用户,需要有踢人权限,在 APP 层获取 RoomToken 时指定
// @param user_id 用于被踢出的用户 Id
// @return 成功返回 0,失败请参考错误码列表
// @brief 当返回 0 时,最终操作结果由 on_kickout_result 回调通知
int qn_rtc_kickout_user(char* user_id);
此方法需要拥有相应的 admin
权限(获取RoomToken
时指定)方可以操作,且此方法为异步方法,实际执行结果通过 on_kickout_result
进行通知,操作成功后,对方将收到 on_leave
消息,取消所有已发布 Track 后离开房间;
媒体传输协议策略
SDK 默认优先使用 UDP 传输媒体数据,但当 UDP 不可达时自动切换为 Tcp 传输协议。如果没有特殊的需求,不建议用户修改。 如需修改,需在发布 和 订阅前调用。
// 媒体传输协议配置
typedef enum
{
forceUdp = 0, // media transfer forced use udp
forceTcp = 1, // media transfer forced use tcp
preferUdp = 2, // media transfer use udp first, and if udp don't work, then downgrade using tcp
}QNRtcIcePolicy;
// 配置媒体传输通道底层传输协议,默认为 forceUdp,当用户网络下 UDP 不通时,可配置使用 forceTcp 或 preferUdp
// @param policy_ value of Enum:IcePolicy
void qn_rtc_set_ice_policy(QNRtcIcePolicy policy);
回声消除开关
某些设备自带有回声消除硬件模块,而不必再使用 SDK 内置回声消除软处理,可大大降低 CPU 资源的占用,默认开启。
// 是否开启回声消除,默认开启,禁用后在使用扬声器的场景下将产生回声
// @param enable_ 是否开启, 1 or 0
// @return 目前阶段全部返回 0
// @brief 测试阶段,慎用
int qn_rtc_enable_aec(int enable);