核心方法和回调
介绍 RTC SDK 中的核心方法以及对应的回调。
addHandler
添加主回调事件。
public void addHandler(IRtcEngineEventHandler handler) { mInstance.addHandler(handler); }
详情
IRtcEngineEventHandler 接口类用于 SDK 向 app 发送回调事件通知,app 通过继承该接口类的方法获取 SDK 的事件通知。 接口类的所有方法都有缺省(空)实现,app 可以根据需要只继承关心的事件。在回调方法中,app 不应该做耗时或者调用可能会引起阻塞的 API(如 sendStreamMessage), 否则可能影响 SDK 的运行。
参数
- handler
- 待添加的回调事件,详见 IRtcEngineEventHandler。
返回值
create [1/2]
创建并初始化 RtcEngine。
public static synchronized RtcEngine create( Context context, String appId, IRtcEngineEventHandler handler) throws Exception {}
详情
RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 调用该方法和 create [2/2] 均能创建 RtcEngine 实例。该方法与 create [2/2] 的区别在于,create [2/2] 支持在创建 RtcEngine 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
- context
-
安卓活动上下文。
- appId
- 声网为 app 开发者签发的 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID,必须先调用 destroy 销毁当前 RtcEngine 再重新创建。
- handler
- RtcEngine 的事件句柄,详见 IRtcEngineEventHandler。
返回值
- 方法调用成功,返回一个 RtcEngine 对象。
- 方法调用失败,抛出异常,你需要捕获异常并进行处理。
异常
- Exception
- 调用该方法时可能会发生的异常说明。
create [2/2]
创建并初始化 RtcEngine。
public static synchronized RtcEngine create(RtcEngineConfig config) throws Exception {}
详情
RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 调用该方法和 create [1/2] 均能创建 RtcEngine 实例。该方法与 create [1/2] 的 区别在于,该方法支持在创建 RtcEngine 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
- config
-
RtcEngine 实例的配置。详见 RtcEngineConfig。
返回值
- 方法调用成功,返回一个 RtcEngine 对象。
- 方法调用失败,抛出异常,你需要捕获异常并进行处理。
异常
- Exception
- 调用该方法时可能会发生的异常说明。
CreateRendererView
创建 RendererView。
public static SurfaceView CreateRendererView(Context context) { return new SurfaceView(context);
详情
- 弃用:
- 此方法已废弃。请使用 Android 原生的 SurfaceView。
该方法创建视频 RendererView,返回 SurfaceView 的类型。 View 的操作和布局由 app 管理,SDK 在 app 提供的 View 上进行渲染。 显示视频视图必须调用该方法,而不是直接调用 SurfaceView。
参数
- context
- 安卓活动 (Android Activity) 的上下文。
返回值
SurfaceView
CreateTextureView
创建 TextureView。
public static TextureView CreateTextureView(Context context) { return new TextureView(context);
详情
- 弃用:
- 此方法已废弃。请使用 Android 原生的 TextureView。
该方法创建 TextureView,适用于需要对视频画面进行缩放、旋转和平移的场景,如屏幕共享。View 的操作和布局由 app 管理,SDK 仅在 app 提供的 View 上进行渲染。
参数
- context
- 安卓活动 (Android Activity) 的上下文。
返回值
TextureView
enableInstantMediaRendering
开启音视频帧加速渲染。
public abstract int enableInstantMediaRendering();
详情
- 自从
- v4.1.1
- 一旦开启快速渲染功能,只能通过调用 destroy 方法销毁 RtcEngine 对象来取消。
- 在该模式下,SDK 启用声网自定义加密算法来缩短建立传输链路的耗时,安全性相对于标准 DTLS (Datagram Transport Layer Security) 有所降低。如果业务场景对安全标准要求较高,请谨慎调用该方法。
适用场景
声网推荐在直播场景下,对观众开启该模式。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -7: RtcEngine 尚未初始化就调用方法。
getConnectionState
获取当前网络连接状态。
public abstract RtcConnection.CONNECTION_STATE_TYPE getConnectionState();
详情
该方法在加入频道前后都能调用。
返回值
当前网络连接状态。
getNativeHandle
获取 Native SDK 的 C++ 句柄。
public abstract long getNativeHandle();
详情
该方法获取 Native SDK 引擎 的 C++ 句柄,用于包括注册音视频回调在内的特殊场景。
返回值
SDK 引擎的 Native 句柄。
joinChannel [1/2]
加入频道。
public abstract int joinChannel( String token, String channelName, String optionalInfo, int optionalUid);
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- optionalInfo
- (非必选项) 预留参数。
- optionalUid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [3/3] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannel [2/2]
设置媒体选项并加入频道。
public abstract int joinChannel( String token, String channelId, int uid, ChannelMediaOptions options);
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。
相比 joinChannel [1/2],该方法增加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
- 该方法允许用户一次加入仅一个频道。
- 请务必确保用于生成 Token 的 App ID 和 create [2/2] 方法初始化引擎时用的是同一个 App ID,否则使用 Token 加入频道失败。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回, app 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [3/3] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
preloadChannel[1/2]
使用 token、channelName、optionalUid 预加载频道。
public abstract int preloadChannel(String token, String channelName, int optionalUid);
详情
- 自从
- v4.2.2
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。由于 SDK 预加载频道需要一定的时间,因此声网推荐你在确认频道信息和用户信息后、加入频道前,尽早调用该方法。
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(AUDIO_SCENARIO_CHORUS),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 RtcEngine 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 频道个生效。
- 预加载不生效不会影响后续正常加入频道,也不会增加加入频道的耗时。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 Token。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
- channelName
- 待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。 该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- optionalUid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
preloadChannel[2/2]
使用 token、channelName、userAccount 预加载频道。
public abstract int preloadChannel(String token, String channelName, String userAccount);
详情
- 自从
- v4.2.2
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。由于 SDK 预加载频道需要一定的时间,因此声网推荐你在确认频道信息和用户信息后、加入频道前,尽早调用该方法。
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(AUDIO_SCENARIO_CHORUS),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 RtcEngine 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 频道个生效。
- 预加载不生效不会影响后续正常加入频道,也不会增加加入频道的耗时。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 Token。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
- channelName
- 待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。 该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,User Account 为空。你需要填入有效的参数,重新加入频道。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
joinChannelWithUserAccount [1/2]
使用 User Account 和 Token 加入频道。
public abstract int joinChannelWithUserAccount( String token, String channelName, String userAccount);
详情
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelName
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
joinChannelWithUserAccount [2/2]
使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。
public abstract int joinChannelWithUserAccount( String token, String channelName, String userAccount, ChannelMediaOptions options);
详情
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
相比 joinChannelWithUserAccount [1/2],该方法加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
注: 如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelName
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [3/3] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
leaveChannel [1/2]
离开频道。
public abstract int leaveChannel();
详情
该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。
成功加入频道后,必须调用本方法或者 leaveChannel [2/2] 结束通话,否则无法开始下一次通话。
- 本地:onLeaveChannel 回调。
- 远端:通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 onLeaveChannel 回调。
- 如果你已调用 joinChannelEx 加入多频道,调用本方法后会同时离开 joinChannel [2/2] 和 joinChannelEx 加入的频道。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
leaveChannel [2/2]
设置频道选项并离开频道。
public abstract int leaveChannel(LeaveChannelOptions options);
详情
该方法会把会话相关的所有资源释放掉,离开频道,即挂断或退出通话。不管当前是否在通话中均可以调用该方法。
加入频道后,必须调用本方法结束通话,才能开始下一次通话。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 onLeaveChannel 回调。
- 如果你已调用 joinChannelEx 加入多频道,调用本方法后会同时离开 joinChannel [2/2] 和 joinChannelEx 加入的频道。
参数
- options
- 离开频道的选项,详见 LeaveChannelOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
destroy
销毁 RtcEngine 对象。
public static synchronized void destroy() { if (mInstance == null) return; mInstance.doDestroy(); mInstance = null; System.gc(); }
详情
该方法释放 SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作,该方法适用于此类情况。
调用该方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须依次重新调用 create [2/2] 方法创建一个新的 RtcEngine 对象。
- 该方法为同步调用。需要等待 RtcEngine 资源释放后才能执行其他操作(例如:创建一个新的 RtcEngine 对象),因此建议在子线程中调用该方法,避免主线程阻塞。
- 不建议在 SDK 的回调中调用 destroy,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。
removeHandler
删除指定的回调句柄。
public void removeHandler(IRtcEngineEventHandler handler) { mInstance.removeHandler((IAgoraEventHandler) handler); }
详情
该方法删除指定的回调句柄。对于某些注册的回调句柄,如果你在收到相应回调事件后无需再次接收回调消息,可以调用该方法移除回调句柄。
参数
- handler
- 待删除的回调句柄。详见 IRtcEngineEventHandler。
返回值
renewToken
更新 Token。
public abstract int renewToken(String token);
详情
该方法用于更新 Token。Token 会在一定时间后失效。在以下两种情况下,app 应重新获取 Token,然后调用该方法传入新的 Token,否则 SDK 无法和服务器建立连接:- 发生 onTokenPrivilegeWillExpire 回调时。
- onConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
setChannelProfile
设置频道场景。
public abstract int setChannelProfile(int profile);
详情
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannel [2/2] 前调用和进行设置,进入频道后无法再设置。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。
参数
- profile
-
频道使用场景。
- CHANNEL_PROFILE_COMMUNICATION (0):通信。当频道中只有两个用户时,建议使用该场景。
- CHANNEL_PROFILE_LIVE_BROADCASTING (1):直播。当频道中超过两个用户时,建议使用该场景。
- CHANNEL_PROFILE_GAME (2):该属性已废弃。
- CHANNEL_PROFILE_CLOUD_GAMING (3):互动。该场景对延时进行了优化。如果你的场景中有用户需要频繁互动,建议使用该场景。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [1/2]
设置用户角色。
public abstract int setClientRole(int role);
详情
在加入频道前和加入频道后均可调用该方法设置用户角色。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 本地会触发 onClientRoleChanged 回调。
- 远端会触发 onUserJoined 或
onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)
回调。
参数
- role
-
用户的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
注: 角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时,请确保你的用户角色已切换为主播。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [2/2]
设置直播场景下的用户角色和级别。
public abstract int setClientRole(int role, ClientRoleOptions options);
详情
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 onClientRoleChanged 回调。
- 远端触发 onUserJoined 或 onUserOffline 回调。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以旁路推流等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内可以享受到的服务。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。
- CLIENT_ROLE_BROADCASTER (1): 主播。主播可以发流也可以收流。
- CLIENT_ROLE_AUDIENCE (2):(默认)观众。观众只能收流不能发流。
- options
- 用户具体设置,包含用户级别。详见 ClientRoleOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
startMediaRenderingTracing
开启视频帧渲染数据打点。
public abstract int startMediaRenderingTracing();
详情
- 自从
- v4.1.1
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 onVideoRenderingTracingResult 回调报告视频帧渲染的相关信息。
- SDK 默认在成功加入频道的时刻起打点,自动开始跟踪视频频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次成功加入频道的时刻。
适用场景
声网推荐你将该方法和 app 中的 UI 设置(按钮、滑动条等)结合使用,用于针对终端用户的体验改进。例如:在终端用户在点击 加入频道
按钮的时刻调用该方法进行打点,然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标,从而针对指标进行专项优化。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -7: RtcEngine 尚未初始化就调用方法。
updateChannelMediaOptions
加入频道后更新频道媒体选项。
public abstract int updateChannelMediaOptions(ChannelMediaOptions options);
参数
- options
- 频道媒体选项,详见 ChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:ChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 onConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannel [2/2] 加入频道。
updatePreloadChannelToken
更新预加载频道的通配 Token。
public abstract int updatePreloadChannelToken(String token);
详情
- 自从
- v4.2.2
你需要自行维护通配 Token 的生命周期。当通配 Token 过期后,你需要在你的服务端生成新的通配 Token,然后通过此方法来传入新的 Token。
适用场景
在需要频繁切换频道及多频道场景下,使用通配 Token 可以避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长,可以进一步加快切换频道的速度,同时减少你的 Token 服务端的压力。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数,重新加入频道。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
onClientRoleChanged
直播场景下用户角色已切换回调。
public void onClientRoleChanged(int oldRole, int newRole, ClientRoleOptions newRoleOptions) {}
该回调是由本地用户在加入频道后调用 setClientRole [2/2] 改变用户角色触发的。
参数
- oldRole
- 切换前的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
- newRole
- 切换后的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
- newRoleOptions
-
- 自从
- v4.1.0
切换后的角色属性。详见 ClientRoleOptions。
onClientRoleChangeFailed
直播场景下切换用户角色失败回调。
public void onClientRoleChangeFailed(int reason, int currentRole) {}
直播场景下,本地用户加入频道后调用 setClientRole [2/2] 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。
参数
- reason
- 切换用户角色失败的原因。
- CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS(1): 频道内主播人数达到上限。
注: 该枚举仅在开启 128 人功能后报告。主播人数的上限根据开启 128 人功能时实际配置的人数而定。
- CLIENT_ROLE_CHANGE_FAILED_NOT_AUTHORIZED(2): 请求被服务端拒绝。建议提示用户重新尝试切换用户角色。
- CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT(3): 请求超时。建议提示用户检查网络连接状况后重新尝试切换用户角色。
- CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED(4): 网络连接断开。可根据 onConnectionStateChanged 报告的 reason,排查网络连接失败的具体原因。
- CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS(1): 频道内主播人数达到上限。
- currentRole
- 当前用户角色。
- CLIENT_ROLE_BROADCASTER(1): 主播。主播可以发流也可以收流。
- CLIENT_ROLE_AUDIENCE(2): 观众。观众只能收流不能发流。
onError
发生错误回调。
public void onError(int err) {}
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 app 干预或提示用户。
参数
- err
- 错误码。
onJoinChannelSuccess
成功加入频道回调。
public void onJoinChannelSuccess(String channel, int uid, int elapsed) {}
该回调方法表示该客户端成功加入了指定的频道。
参数
- channel
- 频道名。
- uid
- 加入频道的用户 ID。
- elapsed
- 从本地调用 joinChannel [2/2] 开始到发生此事件过去的时间(毫秒)。
onLeaveChannel
离开频道回调。
public void onLeaveChannel(RtcStats stats) {}
App 调用 leaveChannel [2/2] 方法时,SDK 提示 app 离开频道成功。在该回调方法中,app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- stats
- 通话的统计数据: RtcStats。
onRejoinChannelSuccess
成功重新加入频道回调。
public void onRejoinChannelSuccess(String channel, int uid, int elapsed) {}
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- channel
- 频道名。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从调用 joinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
onRequestToken
Token 已过期回调。
public void onRequestToken() {}
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 app 更新 Token。
- 调用 renewToken 来传入新的 Token。
- 调用 leaveChannel [2/2] 离开当前频道,然后在调用 joinChannel [2/2] 时传入新的 Token 重新加入频道。
参数
onRtcStats
当前通话统计信息回调。
public void onRtcStats(RtcStats stats) {}
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
参数
- stats
-
RTC 引擎统计数据,详见 RtcStats。
onTokenPrivilegeWillExpire
Token 服务将在30s内过期回调。
public void onTokenPrivilegeWillExpire(String token) {}
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。在多频道场景下,你需要调用 updateChannelMediaOptionsEx 来传入新的 Token。
参数
- token
- 即将服务失效的 Token。
onUserInfoUpdated
远端用户信息已更新回调。
public void onUserInfoUpdated(int uid, UserInfo userInfo) {}
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
参数
- uid
- 远端用户 ID。
- userInfo
- 标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 UserInfo 类。
onUserJoined
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
public void onUserJoined(int uid, int elapsed) {}
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。
- 远端用户/主播加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
参数
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 到该回调触发的延迟(毫秒)。
onUserOffline
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
public void onUserOffline(int uid, int reason) {}
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
参数
- uid
- 离线用户或主播的用户 ID。
- reason
-
远端用户(通信场景)或主播(直播场景)下线的原因:
- USER_OFFLINE_QUIT(0):用户主动离开。此时离开频道的用户会发送一个类似“再见”的消息。收到该消息是,SDK 判定该用户、 离开频道。
- USER_OFFLINE_DROPPED(1):因过长时间收不到对方数据包,SDK 判定该远端用户超时掉线。注意:在网络连接不稳定时,该判定 可能会有误。建议使用实时消息 SDK 来做可靠的掉线检测。
- USER_OFFLINE_BECOME_AUDIENCE(2):用户的角色从主播切换为观众。
onVideoRenderingTracingResult
视频帧渲染事件回调。
public void onVideoRenderingTracingResult(int uid, Constants.MEDIA_RENDER_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo) {}
- 自从
- v4.1.1
调用 startMediaRenderingTracing 方法或加入频道后,SDK 会触发该回调,报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化,以提高出图效率。
参数
- uid
- 用户 ID。
- currentEvent
- 当前视频帧渲染事件。详见 MEDIA_TRACE_EVENT。
- tracingInfo
- 视频帧渲染过程中的指标。开发者需要尽可能降低指标值,以提高出图效率。详见 VideoRenderingTracingInfo。