频道相关
delegate
设置并获得 AgoraRtcEngineDelegate
。
@property(nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate;
详情
SDK 通过 AgoraRtcEngineDelegate 类向 App 报告 SDK 运行时的各种事件。该类中定义的所有方法都是可选的实现方法。
所属接口类getUserInfoByUid
通过 UID 获取用户信息。
- (AgoraUserInfo* _Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode* _Nullable)error;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- uid
- 用户 ID。
- error
- 错误码。
返回值
- 方法调用成功,返回 AgoraUserInfo 对象。
- 方法调用失败,则返回 nil。
getUserInfoByUidEx
通过 UID 获取用户信息。
- (int)getUserInfoWithUserId:(NSUInteger)uid
userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo
channelId:(NSString* _Nonnull)channelId
localUserAccount:(NSString* _Nonnull)localUserAccount;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- uid
- 用户 ID。
- userInfo
- 标识用户信息的 AgoraUserInfo 对象。
- 输入值:一个 AgoraUserInfo 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象。
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
- (AgoraUserInfo* _Nullable)getUserInfoByUserAccount:(NSString* _Nonnull)userAccount withError:(AgoraErrorCode* _Nullable)error;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- userAccount
- 用户 User Account。
- error
- 错误码。
返回值
- 方法调用成功,返回 AgoraUserInfo 对象。
- 方法调用失败,则返回 nil。
getUserInfoByUserAccountEx
通过 User Account 获取用户信息。
- (int)getUserInfoWithUserAccount:(NSString * _Nonnull)userAccount
userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo
channelId:(NSString* _Nonnull)channelId
localUserAccount:(NSString* _Nonnull)localUserAccount;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 didUserInfoUpdatedWithUserId 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。
参数
- userAccount
- 用户 User Account。
- userInfo
- 标识用户信息的 AgoraUserInfo 对象。
- 输入值:一个 AgoraUserInfo 对象。
- 输出值:一个包含了用户 User Account 和 UID 的 AgoraUserInfo 对象。
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
joinChannelByToken [1/4]
加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
info:(NSString * _Nullable)info
uid:(NSUInteger)uid
joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 不能互通。
- 本地会触发 didJoinChannel 和 connectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。
- 用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。信息如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- info
- (非必选项) 预留参数。
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 didJoinChannel 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithConfig 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelByToken [2/4]
设置媒体选项并加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
uid:(NSUInteger)uid
mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions
joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 不能互通。
- 本地会触发 didJoinChannel 和 connectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 didJoinedOfUid 回调。
在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 didRejoinChannel 回调。
相比 joinChannelByToken [1/4],该方法增加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
- 该方法允许用户一次加入仅一个频道。
- 请务必确保用于生成 Token 的 App ID 和 sharedEngineWithConfig 方法初始化引擎时用的是同一个 App ID,否则使用 Token 加入频道失败。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- 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 会自动分配一个,并在 didJoinChannel 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithConfig 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelByToken [3/4]
使用 User Account 和 Token 加入频道。
- (int)joinChannelByToken:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
userAccount:(NSString * _Nonnull)userAccount
joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- 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 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数无效。
- -3: SDK 初始化失败,请尝试重新初始化 SDK。
- -5: 调用被拒绝。
- -17: 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 AgoraRtcEngineKit 频道,当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法时,会返回此错误码。
joinChannelByToken [4/4]
使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。
- (int)joinChannelByToken:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
userAccount:(NSString * _Nonnull)userAccount
mediaOptions:(AgoraRtcChannelMediaOptions * _Nonnull)mediaOptions
joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
相比 joinChannelByToken [3/4],该方法加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- 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 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithConfig 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelExByToken [1/2]
使用连接 ID 加入频道。
- (int)joinChannelExByToken:(NSString* _Nullable)token
connection:(AgoraRtcConnection * _Nonnull)connection
delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate
mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions
joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
调用该方法,你可以同时加入多个频道。
- 如果你已经在一个频道内,你不能用相同的用户 UID 再次加入该频道。
- 如果你想在不同的设备上加入相同的频道,请确保你在不同设备上使用的用户 UID 都不同。
- 请确保生成 Token 时传入的 App ID 和创建 AgoraRtcEngineKit 实例时传入的 App ID 一致。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。信息如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 使用通配 Token。
- connection
- Connection 信息。详见 AgoraRtcConnection。
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- delegate
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,AgoraRtcChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是:调用 startEchoTestWithConfig 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelExByToken [2/2]
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
- (int)joinChannelExByToken:(NSString* _Nullable)token
channelId:(NSString* _Nonnull)channelId
userAccount:(NSString* _Nonnull)userAccount
delegate:(id<AgoraRtcEngineDelegate> _Nullable)delegate
mediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions
joinSuccess:(void(^ _Nullable)(NSString* _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;
详情
- 本地:didLocalUserRegisteredWithUserId、didJoinChannel 和 connectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 didJoinedOfUid 和 didUserInfoUpdatedWithUserId 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
- 如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。
参数
- 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 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- mediaOptions
- 频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。
- joinSuccessBlock
- 成功加入频道回调。
joinSuccessBlock
优先级高于 didJoinChannel,两个同时存在时,didJoinChannel 会被忽略。需要有 didJoinChannel 回调时,请将joinSuccessBlock
设置为nil
。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
leaveChannel [1/2]
离开频道。
- (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock;
详情
该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。
成功加入频道后,必须调用本方法或者 leaveChannel [2/2] 结束通话,否则无法开始下一次通话。
- 本地:didLeaveChannelWithStats 回调。
- 远端:通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 如果你已调用 joinChannelExByToken [1/2] 加入多频道,调用本方法后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- leaveChannelBlock
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
leaveChannel [2/2]
设置频道选项并离开频道。
- (int)leaveChannel:(AgoraLeaveChannelOptions * _Nonnull)options
leaveChannelBlock:(void (^ _Nullable)(AgoraChannelStats * _Nonnull))leaveChannelBlock;
详情
该方法会把会话相关的所有资源释放掉,离开频道,即挂断或退出通话。不管当前是否在通话中均可以调用该方法。
加入频道后,必须调用本方法结束通话,才能开始下一次通话。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 如果你已调用 joinChannelExByToken [1/2] 加入多频道,调用本方法后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- options
- 离开频道的选项,详见 AgoraLeaveChannelOptions。
- leaveChannelBlock
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
leaveChannelEx [1/2]
离开频道。
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannelEx(_:leaveChannelBlock:));
详情
离开频道,即挂断或退出通话。
调用 joinChannelExByToken [1/2] 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 didLeaveChannelWithStats 回调。
成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 调用 leaveChannel [1/2] 后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- leaveChannelBlock
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
leaveChannelEx [2/2]
设置频道选项并离开频道。
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
options:(AgoraLeaveChannelOptions * _Nonnull)options
leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;
详情
离开频道,即挂断或退出通话。
调用 joinChannelExByToken [1/2] 加入频道后,必须调用本方法结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 didLeaveChannelWithStats 回调。
成功调用该方法离开频道后,本地会触发 didLeaveChannelWithStats 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 didOfflineOfUid 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 didLeaveChannelWithStats 回调。
- 调用 leaveChannel [2/2] 后会同时离开 joinChannelByToken [2/4] 和 joinChannelExByToken [1/2] 加入的频道。
参数
- connection
- Connection 信息。详见 AgoraRtcConnection。
- options
- 自从v4.1.0
离开频道的选项,详见 AgoraLeaveChannelOptions。
信息该参数仅支持设置 AgoraLeaveChannelOptions 中的 stopMicrophoneRecording 成员,设置其他成员均不生效。 - leaveChannelBlock
成功离开频道的回调,提供通话相关的统计信息,详见 AgoraChannelStats。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
preloadChannelByToken
使用 token
、channelId
、uid
预加载频道。
- (int)preloadChannelByToken:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
uid:(NSUInteger)uid NS_SWIFT_NAME(preloadChannel(byToken:channelId:uid:));
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
调用时机
为了提升预加载频道的用户体验,声网推荐你在确认频道名、用户信息后、加入频道前,尽早调用该方法。
调用限制
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(AgoraAudioScenarioChorus),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 AgoraRtcEngineKit 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 个频道生效。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 Token。 信息生成通配 Token 时,用户 ID 不得设为 0。详见 使用通配 Token。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 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 会自动分配一个,并在 didJoinChannel 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
preloadChannelByTokenWithUserAccount
使用 token
、channelId
、userAccount
预加载频道。
- (int)preloadChannelByTokenWithUserAccount:(NSString * _Nullable)token
channelId:(NSString * _Nonnull)channelId
userAccount:(NSString * _Nonnull)userAccount NS_SWIFT_NAME(preloadChannelWithUserAccount(byToken:channelId:userAccount:));
调用该方法可以减少观众频繁切换频道时加入频道的时间,从而缩短观众听到主播首帧音频以及看到首帧画面的耗时,提升观众端的视频体验。
如果当前频道已经成功预加载,观众加入、离开频道后如需再次加入该频道,只要预加载时传入的 Token 仍在有效期内,则无需重新预加载。
调用时机
为了提升预加载频道的用户体验,声网推荐你在确认频道名、用户信息后、加入频道前,尽早调用该方法。
调用限制
- 调用该方法时,请确保用户角色设为观众、音频应用场景设为非合唱场景(AgoraAudioScenarioChorus),否则预加载不生效。
- 请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同,否则预加载不生效。
- 目前一个 AgoraRtcEngineKit 实例最多支持预加载 20 个频道,如超出限制,仅最新预加载的 20 个频道生效。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。Token 过期后,根据预加载频道的数量,你可以通过不同方式来传入用于预加载频道的新 Token:
- 预加载一个频道时:调用此方法来传入新的 Token。
- 预加载多个频道时:
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 Token。 信息生成通配 Token 时,用户 ID 不得设为 0。详见 使用通配 Token。
- 如果你使用了不同的 Token:调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。
- 如果你使用了通配的 Token,调用 updatePreloadChannelToken 来更新所有预加载频道的 Token。
- channelId
- 待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。 该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- userAccount
- 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。 该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,User Account 为空。你需要填入有效的参数,重新加入频道。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -102:频道名无效。你需要填入有效的频道名,重新加入频道。
registerLocalUserAccountWithAppID
注册本地用户 User Account。
- (int)registerLocalUserAccountWithAppID:(NSString * _Nonnull)appID userAccount:(NSString * _Nonnull)userAccount;
详情
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 didLocalUserRegisteredWithUserId 回调,告知本地用户的 UID 和 User Account。
- 先调用 registerLocalUserAccountWithAppID 方法注册 Account,再调用 joinChannelByToken [4/4] 方法加入频道。
- 直接调用 joinChannelByToken [4/4] 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccountWithAppID,可以缩短使用 joinChannelByToken [4/4] 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
- appID
- 你的项目在控制台注册的 App ID。
- userAccount
- 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 nil。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
renewToken
更新 Token。
- (int)renewToken:(NSString * _Nonnull)token;
该方法用于更新 Token。Token 会在一定时间后失效,此时 SDK 将无法和服务器建立连接。
调用时机
- 收到 tokenPrivilegeWillExpire 回调报告 Token 即将过期时;
- 收到 rtcEngineRequestToken 回调报告 Token 已过期;
- 收到 connectionStateChanged 回调报告 AgoraConnectionChangedReasonTokenExpired(9) 时;
调用限制
无。
参数
- token
- 新生成的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,Token 为空。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -110:Token 无效。请确保:
- 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致,
- 生成的 Token 和加入频道使用的 Token 一致。
setChannelProfile
设置频道场景。
- (int)setChannelProfile:(AgoraChannelProfile)profile;
详情
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannelByToken [2/4] 前调用和进行设置,进入频道后无法再设置。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。
参数
- profile
频道使用场景。详见 AgoraChannelProfile。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [1/2]
设置用户角色。
- (int)setClientRole:(AgoraClientRole)role;
详情
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 didClientRoleChanged 回调。
- 远端触发 didJoinedOfUid 或 didOfflineOfUid 回调。
参数
- role
用户角色。详见 AgoraClientRole。
信息角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时,请确保你的用户角色已切换为主播。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [2/2]
设置直播场景下的用户角色和级别。
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions * _Nullable)options;
详情
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 didClientRoleChanged 回调。
- 远端触发 didJoinedOfUid 或 didOfflineOfUid 回调。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以旁路推流等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内可以享受到的服务。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。详见 AgoraClientRole。
- options
- 用户具体设置,包含用户级别。详见 AgoraClientRoleOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
updateChannelWithMediaOptions
加入频道后更新频道媒体选项。
- (int)updateChannelWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions;
参数
- mediaOptions
- 频道媒体选项,详见 AgoraRtcChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:AgoraRtcChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken [2/4] 加入频道。
updateChannelExWithMediaOptions
加入频道后更新频道媒体选项 。
- (int)updateChannelExWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions
connection:(AgoraRtcConnection * _Nonnull)connection;
参数
- options
- 频道媒体选项,详见 AgoraRtcChannelMediaOptions。
- connection
- Connection 信息。详见 AgoraRtcConnection。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:AgoraRtcChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8:AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。建议通过 connectionStateChanged 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken [2/4] 加入频道。
updatePreloadChannelToken
更新预加载频道的通配 Token。
- (int)updatePreloadChannelToken:(NSString * _Nonnull)token NS_SWIFT_NAME(updatePreloadChannelToken(_:));
详情
你需要自行维护通配 Token 的生命周期。当通配 Token 过期后,你需要在你的服务端生成新的通配 Token,然后通过此方法来传入新的 Token。
适用场景
在需要频繁切换频道及多频道场景下,使用通配 Token 可以避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长,可以进一步加快切换频道的速度,同时减少你的 Token 服务端的压力。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数,重新加入频道。
- -7:AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
didClientRoleChanged
直播场景下用户角色已切换回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole
newRole:(AgoraClientRole)newRole newRoleOptions:(AgoraClientRoleOptions * _Nullable)newRoleOptions
NS_SWIFT_NAME(rtcEngine(_:didClientRoleChanged:newRole:newRoleOptions:));
详情
该回调是由本地用户在加入频道后调用 setClientRole [2/2] 改变用户角色触发的。
参数
- engine
- AgoraRtcEngineKit 对象。
- oldRole
- 切换前的角色:AgoraClientRole。
- newRole
- 切换后的角色:AgoraClientRole。
- newRoleOptions
- 自从v4.1.0
切换后的角色属性。详见 AgoraClientRoleOptions。
didClientRoleChangeFailed
直播场景下切换用户角色失败回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole;
详情
直播场景下,本地用户加入频道后调用 setClientRole [2/2] 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。
参数
- reason
- 切换用户角色失败的原因。详见 AgoraClientRoleChangeFailedReason。
- currentRole
- 当前用户角色。详见 AgoraClientRole。
didOccurError
发生错误回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurError:(AgoraErrorCode)errorCode;
详情
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。
参数
- engine
- AgoraRtcEngineKit 对象。
- errorCode
- 错误码。详见 AgoraErrorCode。
didJoinChannel
成功加入频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;
详情
该回调方法表示该客户端成功加入了指定的频道。
参数
- engine
- AgoraRtcEngineKit 对象。
- channel
- 频道名。
- uid
- 加入频道的用户 ID。
- elapsed
- 从本地调用 joinChannelByToken [2/4] 开始到发生此事件过去的时间(毫秒)。
didLeaveChannelWithStats
离开频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats;
详情
App 调用 leaveChannel [2/2] 方法时,SDK 提示 App 离开频道成功。在该回调方法中,App 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 通话的统计数据: AgoraChannelStats。
didLocalUserRegisteredWithUserId
本地用户成功注册 User Account 回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalUserRegisteredWithUserId:(NSUInteger)uid userAccount:(NSString * _Nonnull)userAccount;
详情
本地用户成功调用 registerLocalUserAccountWithAppID 方法注册用户 User Account,或调用 joinChannelByToken [4/4] 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 本地用户的 ID。
- userAccount
- 本地用户的 User Account。
didRejoinChannel
成功重新加入频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;
详情
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- engine
- AgoraRtcEngineKit 对象。
- channel
- 频道名。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从调用 joinChannelByToken [2/4] 方法到触发该回调的时间间隔(毫秒)。
rtcEngineRequestToken
Token 已过期回调。
- (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine;
在音视频互动过程中,如果 Token 失效,SDK 会触发该回调报告 Token 已过期。
- 单频道场景:
- 调用 renewToken 来传入新的 Token。
- 调用 leaveChannel [2/2] 离开当前频道,然后在调用 joinChannelByToken [2/4] 时传入新的 Token 重新加入频道。
- 多频道场景:调用 updateChannelExWithMediaOptions 传入新的 Token。
使用限制
无。
参数
- engine
- AgoraRtcEngineKit 对象。
reportRtcStats
当前通话相关的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
reportRtcStats:(AgoraChannelStats * _Nonnull)stats;
详情
触发时机
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
使用限制
无。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
RTC 引擎统计数据,详见 AgoraChannelStats。
tokenPrivilegeWillExpire
Token 即将在 30s 内过期回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
tokenPrivilegeWillExpire:(NSString *_Nonnull)token;
- 单频道场景:
- 调用 renewToken 来传入新的 Token。
- 调用 leaveChannel [2/2] 离开当前频道,然后在调用 joinChannelByToken [2/4] 时传入新的 Token 重新加入频道。
- 多频道场景:调用 updateChannelExWithMediaOptions 传入新的 Token。
触发时机
在音视频互动过程中,SDK 会在 Token 过期前 30 秒触发该回调,提醒 App 更新 Token。
使用限制
无。
参数
- engine
- AgoraRtcEngineKit 对象。
- token
- 即将过期的 Token。
didUserInfoUpdatedWithUserId
远端用户信息已更新回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didUserInfoUpdatedWithUserId:(NSUInteger)uid userInfo:(AgoraUserInfo* _Nonnull)userInfo;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 远端用户 ID。
- userInfo
- 标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 AgoraUserInfo 类。
didJoinedOfUid
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;
详情
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。
- 远端用户/主播加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 到该回调触发的延迟(毫秒)。
didOfflineOfUid
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
didOfflineOfUid:(NSUInteger)uid
reason:(AgoraUserOfflineReason)reason;
详情
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 离线用户或主播的用户 ID。
- reason
离线原因: AgoraUserOfflineReason。