频道相关
GetUserInfoByUid
通过 UID 获取用户信息。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int GetUserInfoByUid(int64 uid, FUserInfo& userInfo);
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 FOnUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 FUserInfo 对象。
参数
- uid
- 用户 ID。
- userInfo
- 输入和输出参数。标识用户的 FUserInfo 对象:
- 输入值:一个 FUserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 FUserInfo 对象
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
GetUserInfoByUserAccount
通过 User Account 获取用户信息。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int GetUserInfoByUserAccount(FString userAccount, FUserInfo& userInfo);
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 FOnUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 FUserInfo 对象。
参数
- userAccount
- 用户 User Account。
- userInfo
- 输入和输出参数。标识用户的 FUserInfo 对象:
- 输入值:一个 FUserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 FUserInfo 对象
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
JoinChannel
设置媒体选项并加入频道。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int JoinChannel(FString token, FString channelId, int64 uid, const FChannelMediaOptions& options);
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 不能互通。
- 本地会触发 FOnJoinChannelSuccess 和 FOnConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 FOnUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 FOnRejoinChannelSuccess 回调。
- 该方法允许用户一次加入仅一个频道。
- 请务必确保用于生成 Token 的 App ID 和 Initialize 方法初始化引擎时用的是同一个 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 会自动分配一个,并在 FOnJoinChannelSuccess 回调中返回, App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
- 频道媒体设置选项。详见 FChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,FChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是:调用 StartEchoTest 开始通话回路测试后,未调用 StopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 StopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
JoinChannelEx
使用连接 ID 加入频道。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int JoinChannelEx(FString token, const FRtcConnection& connection, const FChannelMediaOptions& options, UIRtcEngineEventHandler* eventHandler);
详情
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 App ID 和创建 IRtcEngine 实例时传入的 App ID 一致。
- 在多摄像头采集场景下,你需要在调用该方法之后调用 StartPreview 方法设置 sourceType 为 VIDEO_SOURCE_CAMERA_SECONDARY,以确保第二个摄像头采集正常。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。信息如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- connection
- Connection 信息。详见 FRtcConnection。
- options
- 频道媒体设置选项。详见 FChannelMediaOptions。
- eventHandler
- IRtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,FChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是:调用 StartEchoTest 开始通话回路测试后,未调用 StopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 StopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
JoinChannelWithUserAccount
使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int JoinChannelWithUserAccount(FString token, FString channelId, FString userAccount, const FChannelMediaOptions& options);
详情
- 本地:FOnLocalUserRegistered、FOnJoinChannelSuccess 和 FOnConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 FOnUserJoined 和 FOnUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。信息如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。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
- 频道媒体设置选项。详见 FChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,FChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:IRtcEngine 对象初始化失败。你需要重新初始化 IRtcEngine 对象。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是:调用 StartEchoTest 开始通话回路测试后,未调用 StopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 StopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
JoinChannelWithUserAccountEx
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int JoinChannelWithUserAccountEx(FString token, FString channelId, FString userAccount, const FChannelMediaOptions& options, UIRtcEngineEventHandler* eventHandler);
详情
- 本地:FOnLocalUserRegistered、FOnJoinChannelSuccess 和 FOnConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 FOnUserJoined 和 FOnUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。信息如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。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
- 频道媒体设置选项。详见 FChannelMediaOptions。
- eventHandler
- IRtcEngineEx 的回调类,详见 IRtcEngineEventHandler。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
LeaveChannel
设置频道选项并离开频道。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int LeaveChannel(const FLeaveChannelOptions& options);
详情
该方法会把会话相关的所有资源释放掉,离开频道,即挂断或退出通话。不管当前是否在通话中均可以调用该方法。
加入频道后,必须调用本方法结束通话,才能开始下一次通话。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,本地会触发 FOnLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 FOnUserOffline 回调。
- 如果你调用了本方法后立即调用 Release 方法,SDK 将无法触发 FOnLeaveChannel 回调。
- 如果你已调用 JoinChannelEx 加入多频道,调用本方法后会同时离开 JoinChannel 和 JoinChannelEx 加入的频道。
参数
- options
- 离开频道的选项,详见 FLeaveChannelOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
LeaveChannelEx
设置频道选项并离开频道。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int LeaveChannelEx(const FRtcConnection& connection, const FLeaveChannelOptions& options);
详情
离开频道,即挂断或退出通话。
调用 JoinChannelEx 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 FOnLeaveChannel 回调。
成功调用该方法离开频道后,本地会触发 FOnLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 FOnUserOffline 回调。
- 如果你调用了本方法后立即调用 Release 方法,SDK 将无法触发 FOnLeaveChannel 回调。
- 调用 LeaveChannel 后会同时离开 JoinChannel 和 JoinChannelEx 加入的频道。
参数
- connection
- Connection 信息。详见 FRtcConnection。
- options
离开频道的选项,详见 FLeaveChannelOptions。
信息该参数仅支持设置 FLeaveChannelOptions 中的 stopMicrophoneRecording 成员,设置其他成员均不生效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
RegisterLocalUserAccount
注册本地用户 User Account。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int RegisterLocalUserAccount(FString appId, FString userAccount);
详情
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 FOnLocalUserRegistered 回调,告知本地用户的 UID 和 User Account。
- 先调用 RegisterLocalUserAccount 方法注册 Account,再调用 JoinChannelWithUserAccount 方法加入频道。
- 直接调用 JoinChannelWithUserAccount 方法加入频道。
两种方式的区别在于,提前调用 RegisterLocalUserAccount,可以缩短使用 JoinChannelWithUserAccount 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
- appId
- 你的项目在控制台注册的 App ID。
- userAccount
- 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
RenewToken
更新 Token。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int RenewToken(FString token);
详情
- 发生 FOnTokenPrivilegeWillExpire 回调时。
- FOnConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
SetChannelProfile
设置频道场景。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetChannelProfile(ECHANNEL_PROFILE_TYPE profile);
详情
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 JoinChannel 前调用和进行设置,进入频道后无法再设置。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 SetDefaultAudioRouteToSpeakerphone 和 SetVideoEncoderConfiguration 中的说明。
参数
- profile
频道使用场景。详见 ECHANNEL_PROFILE_TYPE。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数无效。
- -7: SDK 尚未初始化。
SetClientRole
设置直播场景下的用户角色和级别。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetClientRole(ECLIENT_ROLE_TYPE clientroletype, FClientRoleOptions& options);
详情
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 SetupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布状态。
- 本地触发 FOnClientRoleChanged 回调。
- 远端触发 FOnUserJoined 或 FOnUserOffline 回调。
参数
- clientroletype
- 直播场景中的用户角色。详见 ECLIENT_ROLE_TYPE。
- options
- 用户具体设置,包含用户级别。详见 FClientRoleOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
UpdateChannelMediaOptions
加入频道后更新频道媒体选项。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int UpdateChannelMediaOptions(const FChannelMediaOptions& options);
参数
- options
- 频道媒体选项,详见 FChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:FChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 JoinChannel 加入频道。
UpdateChannelMediaOptionsEx
加入频道后更新频道媒体选项 。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int UpdateChannelMediaOptionsEx(const FChannelMediaOptions& options, const FRtcConnection& connection);
参数
- options
- 频道媒体选项,详见 FChannelMediaOptions。
- connection
- Connection 信息。详见 FRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:FChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。
- -8:IRtcEngine 对象内部状态错误。可能的原因是用户不在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 JoinChannel 加入频道。
FOnClientRoleChanged
直播场景下用户角色已切换回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FOnClientRoleChanged, ECLIENT_ROLE_TYPE, oldRole, ECLIENT_ROLE_TYPE, newRole, FClientRoleOptions, roleoption);
详情
该回调是由本地用户在加入频道后调用 SetClientRole 改变用户角色触发的。
参数
- oldRole
- 切换前的角色:ECLIENT_ROLE_TYPE。
- newRole
- 切换后的角色:ECLIENT_ROLE_TYPE。
- newRoleOptions
切换后的角色属性。详见 FClientRoleOptions。
FOnClientRoleChangeFailed
直播场景下切换用户角色失败回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnClientRoleChangeFailed, ECLIENT_ROLE_CHANGE_FAILED_REASON, reason, ECLIENT_ROLE_TYPE, currentRole);
详情
直播场景下,本地用户加入频道后调用 SetClientRole 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。
参数
- reason
- 切换用户角色失败的原因。详见 ECLIENT_ROLE_CHANGE_FAILED_REASON。
- currentRole
- 当前用户角色。详见 ECLIENT_ROLE_TYPE。
FOnError
发生错误回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnError, int, err, FString, msg);
详情
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。
参数
- msg
- 错误描述。
- err
- 错误码。
- ERR_OK(0):没有错误。
- ERR_FAILED(1):一般性的错误(没有明确归类的错误原因)。请重新调用方法。
- ERR_INVALID_ARGUMENT(2):方法中设置了无效的参数。例如指定的频道名中含有非法字符。请重新设置参数。
- ERR_NOT_READY(3):SDK 尚未准备好。可能的原因有:
- IRtcEngine 初始化失败。请重新初始化 IRtcEngine。
- 调用方法时用户尚未加入频道。请检查方法的调用逻辑。
- 调用 Rate 或 Complain 方法时用户尚未离开频道。请检查方法的调用逻辑。
- 请检查是否已开启音频模块。请检查程序集完整性。
- ERR_NOT_SUPPORTED(4):IRtcEngine 当前状态不支持该操作。可能的原因有:
- 使用内置加密时,设置的加密模式不正确,或加载外部加密库失败。请检查加密的枚举值是否正确,或重新加载外部加密库。
- ERR_REFUSED(5):方法调用被拒绝。可能的原因有:
- IRtcEngine 初始化失败。请重新初始化 IRtcEngine。
- 在加入频道时,将频道名设为空字符
""
。请重新设置频道名。 - 多频道场景下,在调用 JoinChannelEx 方法加入频道时,设置的频道名已存在。请重新设置频道名。
- ERR_BUFFER_TOO_SMALL(6):缓冲区大小不足以存放返回的数据。
- ERR_NOT_INITIALIZED(7):IRtcEngine 尚未初始化就调用方法。请确认在调用该方法前已创建 IRtcEngine 对象并完成初始化。
- ERR_INVALID_STATE(8):当前状态无效。
- ERR_NO_PERMISSION(9):没有操作权限。请检查用户是否授予了 App 音视频设备的使用权限。
- ERR_TIMEDOUT(10): 方法调用超时。有些方法调用需要 SDK 返回结果,如果 SDK 处理事件过长,超过 10 秒没有返回,会出现此错误。
- ERR_JOIN_CHANNEL_REJECTED(17):加入频道被拒绝。可能的原因有:
- 用户已经在频道中。建议通过 FOnConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- 用户在调用 StartEchoTest 进行通话测试后,未调用 StopEchoTest 结束当前测试就尝试加入频道。开始通话测试后,需要先调用 StopEchoTest 结束当前测试,再加入频道。
- ERR_LEAVE_CHANNEL_REJECTED(18):离开频道失败。可能的原因有:
- 调用 LeaveChannel 前,用户已离开频道。停止调用该方法即可。
- 用户尚未加入频道,就调用 LeaveChannel 退出频道。这种情况下无需额外操作。
- ERR_ALREADY_IN_USE(19):资源已被占用,不能重复使用。
- ERR_ABORTED(20):SDK 放弃请求,可能由于请求的次数太多。
- ERR_RESOURCE_LIMITED(22):SDK 分配资源失败,可能由于 App 占用资源过多或系统资源耗尽。
- ERR_INVALID_APP_ID(101):不是有效的 App ID。请更换有效的 App ID 重新加入频道。
- ERR_INVALID_CHANNEL_NAME(102):不是有效的频道名。可能的原因是设置的参数数据类型不正确。请更换有效的频道名重新加入频道。
- ERR_NO_SERVER_RESOURCES(103):无法获取当前区域的服务器资源。请在初始化 IRtcEngine 时尝试指定其他区域。
- ERR_TOKEN_EXPIRED(109):当前使用的 Token 过期,不再有效。请在服务端申请生成新的 Token,并调用 RenewToken 更新 Token。 废弃
- 该枚举已废弃。请改用 FOnConnectionStateChanged 回调中的 CONNECTION_CHANGED_TOKEN_EXPIRED(9)。
- ERR_INVALID_TOKEN(110):Token 无效。一般有以下原因:
- 在控制台中启用了 App 证书,但未使用 App ID + Token 鉴权。当项目启用了 App 证书,就必须使用 Token 鉴权。
- 生成 Token 时填入的
uid
字段,和用户加入频道时填入的 uid 不匹配。
- 弃用:
- 该枚举已废弃。请改用 FOnConnectionStateChanged 回调中的 CONNECTION_CHANGED_INVALID_TOKEN(8)。
- ERR_CONNECTION_INTERRUPTED(111):网络连接中断。SDK 在和服务器建立连接后,失去网络连接超过 4 秒。
- ERR_CONNECTION_LOST(112):网络连接丢失。网络连接中断,且 SDK 无法在 10 秒内连接服务器。
- ERR_NOT_IN_CHANNEL(113):调用 SendStreamMessage 方法时用户不在频道内。
- ERR_SIZE_TOO_LARGE(114):在调用 SendStreamMessage 时,发送的数据长度大于 1 KB。
- ERR_BITRATE_LIMIT(115):在调用 SendStreamMessage 时,发送数据的频率超过限制(6 KB/s)。
- ERR_TOO_MANY_DATA_STREAMS(116):在调用 CreateDataStream 时,创建的数据流超过限制(5 个)。
- ERR_STREAM_MESSAGE_TIMEOUT(117):数据流发送超时。
- ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED(119):用户切换角色失败,请尝试重新加入频道。
- ERR_DECRYPTION_FAILED(120):解密失败。可能是用户加入频道时使用了错误的密码。请检查用户加入频道时填入的密码,或引导用户尝试重新加入频道。
- ERR_INVALID_USER_ID(121):该用户 ID 无效。
- ERR_CLIENT_IS_BANNED_BY_SERVER(123):该用户被服务器禁止。
- ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH(130):SDK 不支持将加密过的流推到 CDN 上。
- ERR_INVALID_USER_ACCOUNT(134):无效的 user account,可能是因为设置了无效的参数。
- ERR_LOAD_MEDIA_ENGINE(1001):加载媒体引擎失败。
- ERR_ADM_GENERAL_ERROR(1005):音频设备出现错误(未指明何种错误)。请检查音频设备是否被其他应用占用,或者尝试重新进入频道。
- ERR_ADM_INIT_PLAYOUT(1008):初始化播放设备出错。请检查播放设备是否被其他应用占用,或者尝试重新进入频道。
- ERR_ADM_START_PLAYOUT(1009):启动播放设备出错。请检查播放设备是否正常。
- ERR_ADM_STOP_PLAYOUT(1010):停止播放设备出错。
- ERR_ADM_INIT_RECORDING(1011):初始化录音设备出错。请检查录音设备是否正常,或者尝试重新进入频道。
- ERR_ADM_START_RECORDING(1012):启动录音设备出错。请检查录音设备是否正常。
- ERR_ADM_STOP_RECORDING(1013):停止录音设备出错。
- ERR_VDM_CAMERA_NOT_AUTHORIZED(1501):没有摄像头使用权限。请检查是否已经打开摄像头权限。
FOnJoinChannelSuccess
FOnLeaveChannel
离开频道回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLeaveChannel, const FRtcStats&, stats);
详情
App 调用 LeaveChannel 方法时,SDK 提示 App 离开频道成功。在该回调方法中,App 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- stats
- 通话的统计数据: FRtcStats。
FOnLocalUserRegistered
本地用户成功注册 User Account 回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnLocalUserRegistered, int64, uid, FString, userAccount);
详情
本地用户成功调用 RegisterLocalUserAccount 方法注册用户 User Account,或调用 JoinChannelWithUserAccount 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
参数
- uid
- 本地用户的 ID。
- userAccount
- 本地用户的 User Account。
FOnRejoinChannelSuccess
成功重新加入频道回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FOnRejoinChannelSuccess, FString, channel, int64, uid, int, elapsed);
详情
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- channel
- 频道名。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从调用 JoinChannel 方法到触发该回调的时间间隔(毫秒)。
FOnRequestToken
Token 已过期回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnRequestToken);
详情
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 App 更新 Token。
- 调用 RenewToken 来传入新的 Token。
- 调用 LeaveChannel 离开当前频道,然后在调用 JoinChannel 时传入新的 Token 重新加入频道。
FOnRtcStats
FOnTokenPrivilegeWillExpire
Token 服务将在30s内过期回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnTokenPrivilegeWillExpire, FString, token);
详情
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 App 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 RenewToken 将新生成的 Token 传给 SDK。在多频道场景下,你需要调用 UpdateChannelMediaOptionsEx 来传入新的 Token。
参数
- token
- 即将服务失效的 Token。
FOnUserInfoUpdated
远端用户信息已更新回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserInfoUpdated, int64, uid, const FUserInfo&, info);
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
参数
- uid
- 远端用户 ID。
- info
- 标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 FUserInfo 类。
FOnUserJoined
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserJoined, int64, uid, int, elapsed);
详情
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。
- 远端用户/主播加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
参数
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 JoinChannel 到该回调触发的延迟(毫秒)。
FOnUserOffline
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnUserOffline, int64, uid, EUSER_OFFLINE_REASON_TYPE, reason);
详情
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
参数
- uid
- 离线用户或主播的用户 ID。
- reason
离线原因: EUSER_OFFLINE_REASON_TYPE。