频道相关 | 文档中心

delegate

设置并获得 AgoraRtcEngineDelegate。

Objective-C
@property(nonatomic, weak) id<AgoraRtcEngineDelegate> _Nullable delegate;

详情

SDK 通过 AgoraRtcEngineDelegate 类向 App 报告 SDK 运行时的各种事件。该类中定义的所有方法都是可选的实现方法。

所属接口类

AgoraRtcEngineKit

getUserInfoByUid:withError:

通过 UID 获取用户信息。

Objective-C
- (AgoraUserInfo* _Nullable)getUserInfoByUid:(NSUInteger)uid withError:(AgoraErrorCode* _Nullable)error;

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。收到回调后，调用该方法传入 UID 来获取包含了指定用户 User Account 的 AgoraUserInfo 对象。

调用时机

在收到 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调后调用。

调用限制

无。

参数

uid: 用户 ID。
error: 错误码。

返回值

方法调用成功，返回 AgoraUserInfo 对象。
方法调用失败，则返回 nil。

所属接口类

AgoraRtcEngineKit

getUserInfoWithUserId:userInfo:channelId:localUserAccount:

通过 UID 获取用户信息。

Objective-C
- (int)getUserInfoWithUserId:(NSUInteger)uid
                    userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo
                   channelId:(NSString* _Nonnull)channelId
            localUserAccount:(NSString* _Nonnull)localUserAccount;

详情

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。收到回调后，调用该方法传入 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKitEx

getUserInfoByUserAccount:withError:

通过 User Account 获取用户信息。

Objective-C
- (AgoraUserInfo* _Nullable)getUserInfoByUserAccount:(NSString* _Nonnull)userAccount withError:(AgoraErrorCode* _Nullable)error;

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。收到回调后，调用该方法传入 User Account 来获取包含了指定用户 UID 的 AgoraUserInfo 对象。

调用时机

在收到 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调后调用。

调用限制

无。

参数

userAccount: 用户 User Account。
error: 错误码。

返回值

方法调用成功，返回 AgoraUserInfo 对象。
方法调用失败，则返回 nil。

所属接口类

AgoraRtcEngineKit

getUserInfoWithUserAccount:userInfo:channelId:localUserAccount:

通过 User Account 获取用户信息。

Objective-C
- (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 的映射表，并在本地触发 rtcEngine:didUserInfoUpdatedWithUserId:userInfo: 回调。收到回调后，调用该方法传入 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKitEx

joinChannelByToken:channelId:info:uid:joinSuccess:

加入频道。

Objective-C
- (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;

加入频道后，默认情况下用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过相应的 mute 方法实现。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后再调用。

调用限制

该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a~z
26 个大写英文字母 A~Z
10 个数字 0~9
"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

info

(非必选项) 预留参数。

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 rtcEngine:didJoinChannel:withUid:elapsed: 回调中返回，应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKit

joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:

设置媒体选项并加入频道。

Objective-C
- (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;

相比 joinChannelByToken:channelId:info:uid:joinSuccess:，该方法增加了 options 参数，用于设置媒体选项，如是否在频道内发布音视频流等。用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后再调用。

调用限制

该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见使用通配 Token。

channelId

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a~z
26 个大写英文字母 A~Z
10 个数字 0~9
"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 rtcEngine:didJoinChannel:withUid:elapsed: 回调中返回，应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

mediaOptions

频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。

joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKit

joinChannelByToken:channelId:userAccount:joinSuccess:

使用 User Account 和 Token 加入频道。

Objective-C
- (int)joinChannelByToken:(NSString * _Nullable)token
                channelId:(NSString * _Nonnull)channelId
              userAccount:(NSString * _Nonnull)userAccount
              joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed))joinSuccessBlock;

调用该方法前，如果你未调用 registerLocalUserAccountWithAppID:userAccount: 注册一个 User Account，调用该方法加入频道时，SDK 会自动为你创建一个 User Account。先调用 registerLocalUserAccountWithAppID:userAccount: 方法注册 Account，再调用此方法加入频道，可以缩短进入频道的时间。

用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

注意

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后再调用。

调用限制

该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 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 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKit

joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:

使用 User Account 和 Token 加入频道，并设置频道媒体选项。

Objective-C
- (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;

调用该方法前，如果你未调用 registerLocalUserAccountWithAppID:userAccount: 注册一个 User Account，调用该方法加入频道时，SDK 会自动为你创建一个 User Account。先调用 registerLocalUserAccountWithAppID:userAccount: 方法注册 Account，再调用此方法加入频道，可以缩短进入频道的时间。

相比 joinChannelByToken:channelId:userAccount:joinSuccess:，该方法增加了 options 参数，用于在加入频道时设置媒体选项，如是否在频道内发布音视频流等。默认情况下，用户订阅频道内所有其他用户的音频流和视频流，因此会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

注意

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后再调用。

调用限制

该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 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 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKit

joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:

加入频道。

Objective-C
- (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;

调用该方法，你可以同时加入多个频道。如果你想在不同的设备上加入相同的频道，请确保你在不同设备上使用的用户 ID 都不同。

适用场景

该方法适用于多频道场景。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后调用。

在多摄像头采集场景下，你需要在调用该方法之后调用 startPreview: 方法设置 sourceType 为 AgoraVideoSourceTypeCameraSecondary，以确保第二个摄像头采集正常。

调用限制

如果你已经在一个频道内，你不能用相同的用户 ID 再次加入该频道。

加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token，详见使用通配 Token。

connection

Connection 信息。详见 AgoraRtcConnection。

mediaOptions

频道媒体设置选项。详见 AgoraRtcChannelMediaOptions。

delegate

AgoraRtcEngineKitEx 的回调类，详见 AgoraRtcEngineDelegate。多频道相关的事件通知通过你在此参数中传递的 delegate 对象回调。

joinSuccessBlock

成功加入频道回调。joinSuccessBlock 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKitEx

joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:

使用 User Account 和 Token 加入频道，并设置频道媒体选项。

Objective-C
- (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;

调用该方法前，如果你未调用 registerLocalUserAccountWithAppID:userAccount: 注册一个 User Account，调用该方法加入频道时，SDK 会自动为你创建一个 User Account。先调用 registerLocalUserAccountWithAppID:userAccount: 方法注册 Account，再调用此方法加入频道，可以缩短进入频道的时间。

用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过设置 mediaOptions 参数或调用相应的 mute 方法实现。

注意

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

调用时机

该方法需要在 sharedEngineWithConfig:delegate: 之后再调用。

调用限制

该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道前，请确保用于生成 Token 的 App ID 和调用 sharedEngineWithConfig:delegate: 方法初始化引擎时使用的是同一个 App ID，否则使用 Token 加入频道会失败。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

信息

（推荐）如果你的项目开启了安全模式，即选择 APP ID + Token 为鉴权机制，则该参数为必填。
如果你的项目仅开启调试模式，即选择 APP ID 为鉴权机制，则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。
如果你需要同时加入多个频道或在频道间频繁切换，声网推荐你使用通配 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 优先级高于 rtcEngine:didJoinChannel:withUid:elapsed:，两个同时存在时，rtcEngine:didJoinChannel:withUid:elapsed: 会被忽略。需要有 rtcEngine:didJoinChannel:withUid:elapsed: 回调时，请将 joinSuccessBlock 设置为 nil。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token，uid 参数未设置为整型，或 AgoraRtcChannelMediaOptions 成员值不合法。你需要填入有效的参数，重新加入频道。
- -3：AgoraRtcEngineKit 对象初始化失败。你需要重新初始化 AgoraRtcEngineKit 对象。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是：调用 startEchoTestWithConfig: 开始通话回路测试后，未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17：加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。除收到 AgoraConnectionStateDisconnected(1) 状态外，不要再次调用该方法加入频道。
- -102：频道名无效。你需要在 channelId 中填入有效的频道名，重新加入频道。
- -121：用户 ID 无效。你需要在 uid 中填入有效的用户 ID，重新加入频道。

所属接口类

AgoraRtcEngineKitEx

leaveChannel:

离开频道。

Objective-C
- (int)leaveChannel:(void(^ _Nullable)(AgoraChannelStats * _Nonnull stat))leaveChannelBlock;

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

成功加入频道后，必须调用本方法结束通话，否则无法开始下一次通话。

注意

该方法是异步操作，调用返回时并没有真正退出频道。
如果你已调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 加入多个频道，调用本方法后会同时离开所有已加入的频道。

调用时机

该方法需要在加入频道后调用。

调用限制

如果你调用了该方法后立即调用 destroy 方法，SDK 将不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

参数

leaveChannelBlock: 成功离开频道的回调，提供通话相关的统计信息，详见 AgoraChannelStats。

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -7: SDK 尚未初始化。

所属接口类

AgoraRtcEngineKit

leaveChannel:leaveChannelBlock:

设置频道选项并离开频道。

Objective-C
- (int)leaveChannel:(AgoraLeaveChannelOptions * _Nonnull)options
  leaveChannelBlock:(void (^ _Nullable)(AgoraChannelStats * _Nonnull))leaveChannelBlock;

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

成功加入频道后，必须调用本方法或者 leaveChannel: 结束通话，否则无法开始下一次通话。如果你已调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 加入多个频道，调用本方法后会同时离开所有已加入的频道。

注意

该方法是异步操作，调用返回时并没有真正退出频道。

调用时机

该方法需要在加入频道后调用。

调用限制

如果你调用了该方法后立即调用 destroy 方法，SDK 将不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

参数

options: 离开频道的选项，详见 AgoraLeaveChannelOptions。
leaveChannelBlock: 成功离开频道的回调，提供通话相关的统计信息，详见 AgoraChannelStats。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKit

leaveChannelEx:leaveChannelBlock:

离开频道。

Objective-C
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
    leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock NS_SWIFT_NAME(leaveChannelEx(_:leaveChannelBlock:));

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 成功加入频道后，必须调用本方法或 leaveChannelEx:options:leaveChannelBlock: 结束通话，否则无法开始下一次通话。

注意

该方法是异步操作，调用返回时并没有真正退出频道。
如果你调用了 leaveChannel: 或 leaveChannel:leaveChannelBlock: ，会同时离开 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 及 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 加入的频道。

适用场景

该方法适用于多频道场景。

调用时机

该方法需要在 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 后调用。

调用限制

如果你调用了该方法后立即调用 destroy 方法，SDK 将不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

参数

connection: Connection 信息。详见 AgoraRtcConnection。
leaveChannelBlock: 成功离开频道的回调，提供通话相关的统计信息，详见 AgoraChannelStats。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKitEx

leaveChannelEx:options:leaveChannelBlock:

设置频道选项并离开频道。

Objective-C
- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
              options:(AgoraLeaveChannelOptions * _Nonnull)options
    leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;

调用该方法后，SDK 会终止音视频互动、离开当前频道，并会释放会话相关的所有资源。

调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 成功加入频道后，必须调用本方法或 leaveChannelEx:leaveChannelBlock: 结束通话，否则无法开始下一次通话。

注意

该方法是异步操作，调用返回时并没有真正退出频道。
如果你调用了 leaveChannel: 或 leaveChannel:leaveChannelBlock: 后，会同时离开 joinChannelByToken:channelId:info:uid:joinSuccess: 或 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 及 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 加入的频道。

适用场景

该方法适用于多频道场景。

调用时机

该方法需要在 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 后调用。

调用限制

如果你调用了该方法后立即调用 destroy 方法，SDK 将不会触发 rtcEngine:didLeaveChannelWithStats: 回调。

参数

connection: Connection 信息。详见 AgoraRtcConnection。
options: 自从
v4.1.0

离开频道的选项，详见 AgoraLeaveChannelOptions。

信息
该参数仅支持设置 AgoraLeaveChannelOptions 中的 stopMicrophoneRecording 成员，设置其他成员均不生效。
leaveChannelBlock: 成功离开频道的回调，提供通话相关的统计信息，详见 AgoraChannelStats。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKitEx

preloadChannelByToken:channelId:uid:

使用 token、channelId、uid 预加载频道。

Objective-C
- (int)preloadChannelByToken:(NSString * _Nullable)token
                   channelId:(NSString * _Nonnull)channelId
                         uid:(NSUInteger)uid NS_SWIFT_NAME(preloadChannel(byToken:channelId:uid:));

自从

v4.2.2

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

信息

预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。

调用时机

为了提升预加载频道的用户体验，声网推荐你在确认频道名、用户信息后、加入频道前，尽早调用该方法。

调用限制

调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（AgoraAudioScenarioChorus），否则预加载不生效。
请确保预加载频道时传入的频道名、用户 ID、Token 和后续加入频道时传入的值相同，否则预加载不生效。
目前一个 AgoraRtcEngineKit 实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 个频道生效。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

Token 过期后，根据预加载频道的数量，你可以通过不同方式来传入用于预加载频道的新 Token：

预加载一个频道时：调用此方法来传入新的 Token。
预加载多个频道时：
- 如果你使用了通配的 Token，调用 updatePreloadChannelToken: 来更新所有预加载频道的 Token。
  信息
  生成通配 Token 时，用户 ID 不得设为 0。详见使用通配 Token。
- 如果你使用了不同的 Token：调用此方法并传入你的用户 ID、对应的频道名和更新后的 Token。

channelId

待预加载的频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a~z
26 个大写英文字母 A~Z
10 个数字 0~9
"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

uid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2³²-1。如果不指定（即设为 0），SDK 会自动分配一个，并在 rtcEngine:didJoinChannel:withUid:elapsed: 回调中返回，应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -102：频道名无效。你需要填入有效的频道名，重新加入频道。

所属接口类

AgoraRtcEngineKit

preloadChannelByTokenWithUserAccount:channelId:userAccount:

使用 token、channelId、userAccount 预加载频道。

Objective-C
- (int)preloadChannelByTokenWithUserAccount:(NSString * _Nullable)token
                   channelId:(NSString * _Nonnull)channelId
                 userAccount:(NSString * _Nonnull)userAccount NS_SWIFT_NAME(preloadChannelWithUserAccount(byToken:channelId:userAccount:));

自从

v4.2.2

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

信息

预加载不生效不会影响后续正常加入频道，也不会增加加入频道的耗时。

调用时机

为了提升预加载频道的用户体验，声网推荐你在确认频道名、用户信息后、加入频道前，尽早调用该方法。

调用限制

调用该方法时，请确保用户角色设为观众、音频应用场景设为非合唱场景（AgoraAudioScenarioChorus），否则预加载不生效。
请确保预加载频道时传入的频道名、用户 User Account、Token 和后续加入频道时传入的值相同，否则预加载不生效。
目前一个 AgoraRtcEngineKit 实例最多支持预加载 20 个频道，如超出限制，仅最新预加载的 20 个频道生效。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

Token 过期后，根据预加载频道的数量，你可以通过不同方式来传入用于预加载频道的新 Token：

预加载一个频道时：调用此方法来传入新的 Token。
预加载多个频道时：
- 如果你使用了通配的 Token，调用 updatePreloadChannelToken: 来更新所有预加载频道的 Token。
  信息
  生成通配 Token 时，用户 ID 不得设为 0。详见使用通配 Token。
- 如果你使用了不同的 Token：调用此方法并传入你的用户 ID、对应的频道名和更新后的 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：频道名无效。你需要填入有效的频道名，重新加入频道。

所属接口类

AgoraRtcEngineKit

registerLocalUserAccountWithAppID:userAccount:

注册本地用户 User Account。

Objective-C
- (int)registerLocalUserAccountWithAppID:(NSString * _Nonnull)appID userAccount:(NSString * _Nonnull)userAccount;

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。

该方法为可选。如果你希望用户使用 User Account 加入频道，可参考下列任意一种方式实现：

先调用 registerLocalUserAccountWithAppID:userAccount: 方法注册 Account，再调用 joinChannelByToken:channelId:userAccount:joinSuccess: 或 joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess: 方法加入频道，可以缩短进入频道的时间。
直接调用 joinChannelByToken:channelId:userAccount:joinSuccess: 或 joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess: 方法加入频道。

注意

请确保在该方法中设置的 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

AgoraRtcEngineKit

renewToken:

更新 Token。

Objective-C
- (int)renewToken:(NSString * _Nonnull)token;

该方法用于更新 Token。Token 会在一定时间后失效，此时 SDK 将无法和服务器建立连接。

调用时机

在以下任意一种情况下，声网推荐你在你的服务端重新生成 Token，然后调用该方法传入新的 Token：

收到 rtcEngine:tokenPrivilegeWillExpire: 回调报告 Token 即将过期时；
收到 rtcEngineRequestToken: 回调报告 Token 已过期；
收到 rtcEngine:connectionStateChanged:reason: 回调报告 AgoraConnectionChangedReasonTokenExpired(9) 时；

调用限制

无。

参数

token: 新生成的 Token。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，Token 为空。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -110：Token 无效。请确保：
  - 生成 Token 时指定的用户 ID 与加入频道时使用的用户 ID 一致，
  - 生成的 Token 和加入频道使用的 Token 一致。

所属接口类

AgoraRtcEngineKit

setChannelProfile:

设置频道场景。

Objective-C
- (int)setChannelProfile:(AgoraChannelProfile)profile;

你可以调用该方法设置频道的使用场景。SDK 会针对不同的使用场景采用不同的优化策略，如直播场景优先保证画质。SDK 初始化后默认的频道场景为直播场景。

调用时机

该方法需要在加入频道前调用。

调用限制

为保证实时音视频质量，相同频道内的用户必须使用同一种频道场景。

参数

profile: 频道使用场景。详见 AgoraChannelProfile。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数无效。
- -7: SDK 尚未初始化。

所属接口类

AgoraRtcEngineKit

setClientRole:

设置用户角色。

Objective-C
- (int)setClientRole:(AgoraClientRole)role;

SDK 默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。用户角色（role）确定用户在 SDK 层的权限，包含是否可以发送流等。

调用时机

该方法在加入频道前后均可调用。

如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo: 方法设置了本地视频属性，则用户加入频道时会自动开启本地视频预览。

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动调用 muteLocalAudioStream: 和 muteLocalVideoStream: 修改发布音视频流的状态。

调用限制

在频道外调用本方法并将用户角色设为 BROADCASTER（主播）时，本地不会触发 rtcEngine:didClientRoleChanged:newRole:newRoleOptions: 回调。

参数

role: 用户角色。详见 AgoraClientRole。

信息
角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时，请确保你的用户角色已切换为主播。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -7: SDK 尚未初始化。

所属接口类

AgoraRtcEngineKit

setClientRole:options:

设置直播场景下的用户角色和观众端延时级别。

Objective-C
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions * _Nullable)options;

SDK 默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。用户角色（role）确定用户在 SDK 层的权限，包含是否有发流权限等。

该方法与 setClientRole: 的区别在于，该方法还支持设置观众端延时级别（audienceLatencyLevel）。audienceLatencyLevel 需与 role 结合使用，确定用户在其权限范围内可以享受到的服务。例如对于观众，选择接收低延时还是超低延时的视频流。不同的延时级别会影响计费，详见计费策略。

调用时机

该方法在加入频道前后均可调用。

如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo: 方法设置了本地视频属性，则用户加入频道时会自动开启本地视频预览。

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动调用 muteLocalAudioStream: 和 muteLocalVideoStream: 修改发布音视频流的状态。

调用限制

当用户角色设为主播时，观众端延时级别仅支持设置为 AgoraAudienceLatencyLevelUltraLowLatency（超低延时）。

在加入频道前调用该方法并将 role 设为 BROADCASTER（主播）时，本地不会触发 rtcEngine:didClientRoleChanged:newRole:newRoleOptions: 回调。

参数

role: 用户角色。详见 AgoraClientRole。
信息
角色为观众的用户无法在频道内发布音视频流。在直播场景下发流时，请确保你的用户角色已切换为主播。
options: 用户具体设置，包含用户级别。详见 AgoraClientRoleOptions。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。

所属接口类

AgoraRtcEngineKit

updateChannelWithMediaOptions:

加入频道后更新频道媒体选项。

Objective-C
- (int)updateChannelWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions;

参数

mediaOptions: 频道媒体选项，详见 AgoraRtcChannelMediaOptions。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2：AgoraRtcChannelMediaOptions 成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5)，则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 加入频道。

所属接口类

AgoraRtcEngineKit

updateChannelExWithMediaOptions:connection:

加入频道后更新频道媒体选项。

Objective-C
- (int)updateChannelExWithMediaOptions:(AgoraRtcChannelMediaOptions* _Nonnull)mediaOptions
                            connection:(AgoraRtcConnection * _Nonnull)connection;

参数

options: 频道媒体选项，详见 AgoraRtcChannelMediaOptions。
connection: Connection 信息。详见 AgoraRtcConnection。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2：AgoraRtcChannelMediaOptions 成员值设置无效。例如，使用了不合法的 Token，设置了无效的用户角色。你需要填入有效的参数。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。
- -8：AgoraRtcEngineKit 对象内部状态错误。可能的原因是用户不在频道中。建议通过 rtcEngine:connectionStateChanged:reason: 回调判断用户是否在频道中。如果收到 AgoraConnectionStateDisconnected(1) 或 AgoraConnectionStateFailed(5)，则表示用户不在频道中。你需要在调用该方法前调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 加入频道。

所属接口类

AgoraRtcEngineKitEx

updatePreloadChannelToken:

更新预加载频道的通配 Token。

Objective-C
- (int)updatePreloadChannelToken:(NSString * _Nonnull)token NS_SWIFT_NAME(updatePreloadChannelToken(_:));

详情

自从

v4.2.2

你需要自行维护通配 Token 的生命周期。当通配 Token 过期后，你需要在你的服务端生成新的通配 Token，然后通过此方法来传入新的 Token。

适用场景

在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，可以进一步加快切换频道的速度，同时减少你的 Token 服务端的压力。

参数

token: 新的 Token。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2：传入的参数无效。例如，使用了不合法的 Token。你需要填入有效的参数，重新加入频道。
- -7：AgoraRtcEngineKit 对象尚未初始化。你需要在调用该方法前成功初始化 AgoraRtcEngineKit 对象。

所属接口类

AgoraRtcEngineKit

rtcEngine:didClientRoleChanged:newRole:newRoleOptions:

用户角色、观众端延时级别已切换回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole
newRole:(AgoraClientRole)newRole newRoleOptions:(AgoraClientRoleOptions * _Nullable)newRoleOptions
NS_SWIFT_NAME(rtcEngine(_:didClientRoleChanged:newRole:newRoleOptions:));

触发时机

在以下任意一种情况时，会触发此回调：

在加入频道后调用 setClientRole: 或 setClientRole:options: 设置用户角色或观众端延时级别。
在加入频道前调用 setClientRole: 或 setClientRole:options: 并将用户角色设为 AUDIENCE。

使用限制

当你在加入频道前调用 setClientRole: 或 setClientRole:options: 并将用户角色设为 BROADCASTER 时，不会触发此回调。

参数

engine: AgoraRtcEngineKit 对象。
oldRole: 切换前的角色：AgoraClientRole。
newRole: 切换后的角色：AgoraClientRole。
newRoleOptions: 自从
v4.1.0

切换后的角色属性。详见 AgoraClientRoleOptions。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didClientRoleChangeFailed:currentRole:

用户角色切换失败回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole;

当用户角色切换失败时，你可以通过此回调得知切换失败的原因和当前的用户角色。

触发时机

本地用户加入频道后调用 setClientRole: 或 setClientRole:options: 设置用户角色失败时，SDK 会触发该回调。

使用限制

无。

参数

reason: 切换用户角色失败的原因。详见 AgoraClientRoleChangeFailedReason。
currentRole: 当前用户角色。详见 AgoraClientRole。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didOccurError:

发生错误回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurError:(AgoraErrorCode)errorCode;

详情

该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 App 干预或提示用户。

参数

engine: AgoraRtcEngineKit 对象。
errorCode: 错误码。详见 AgoraErrorCode。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didJoinChannel:withUid:elapsed:

成功加入频道回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
        didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

详情

该回调方法表示该客户端成功加入了指定的频道。

触发时机

当你调用 joinChannelByToken:channelId:info:uid:joinSuccess:、joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:、joinChannelByToken:channelId:userAccount:joinSuccess:、joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:、 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 或 joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess: 方法成功加入频道后，SDK 会触发该回调。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
channel: 频道名。
uid: 加入频道的用户 ID。
elapsed: 从本地调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 开始到发生此事件过去的时间（毫秒）。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didLeaveChannelWithStats:

离开频道回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats;

你可以通过该回调获取此次通话的总通话时长、SDK 收发数据的流量等信息。

触发时机

当你成功调用 leaveChannel:、leaveChannel:leaveChannelBlock:、leaveChannelEx:leaveChannelBlock: 或 leaveChannelEx:options:leaveChannelBlock: 离开频道后，SDK 会触发该回调。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
stats: 通话的统计数据，详见 AgoraChannelStats。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didLocalUserRegisteredWithUserId:userAccount:

本地用户成功注册 User Account 回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalUserRegisteredWithUserId:(NSUInteger)uid userAccount:(NSString * _Nonnull)userAccount;

详情

本地用户成功调用 registerLocalUserAccountWithAppID:userAccount: 方法注册用户 User Account，或调用 joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess: 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。

参数

engine: AgoraRtcEngineKit 对象。
uid: 本地用户的 ID。
userAccount: 本地用户的 User Account。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didRejoinChannel:withUid:elapsed:

成功重新加入频道回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;

触发时机

有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
channel: 频道名。
uid: 重新加入频道的用户 ID。
elapsed: 从调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 方法到触发该回调的时间间隔（毫秒）。

所属接口类

AgoraRtcEngineDelegate

rtcEngineRequestToken:

Token 已过期回调。

Objective-C
- (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine;

在音视频互动过程中，如果 Token 失效，SDK 会触发该回调报告 Token 已过期。

当收到该回调时，你需要重新在服务端生成新的 Token，然后通过下列任意一种方式来更新 Token：

单频道场景：
- 调用 renewToken: 来传入新的 Token。
- 调用 leaveChannel:leaveChannelBlock: 离开当前频道，然后在调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 时传入新的 Token 重新加入频道。
多频道场景：调用 updateChannelExWithMediaOptions:connection: 传入新的 Token。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:reportRtcStats:

当前通话相关的统计信息回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    reportRtcStats:(AgoraChannelStats * _Nonnull)stats;

触发时机

SDK 定期向 App 报告当前通话的统计信息，每两秒触发一次。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
stats: RTC 引擎统计数据，详见 AgoraChannelStats。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:tokenPrivilegeWillExpire:

Token 即将在 30s 内过期回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
     tokenPrivilegeWillExpire:(NSString *_Nonnull)token;

当收到该回调时，你需要重新在服务端生成新的 Token，然后通过下列任意一种方式来更新 Token：

单频道场景：
- 调用 renewToken: 来传入新的 Token。
- 调用 leaveChannel:leaveChannelBlock: 离开当前频道，然后在调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 时传入新的 Token 重新加入频道。
多频道场景：调用 updateChannelExWithMediaOptions:connection: 传入新的 Token。

触发时机

在音视频互动过程中，SDK 会在 Token 过期前 30 秒触发该回调，提醒 App 更新 Token。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
token: 即将过期的 Token。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didUserInfoUpdatedWithUserId:userInfo:

远端用户信息已更新回调。

Objective-C
- (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 类。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didJoinedOfUid:elapsed:

远端用户（通信场景）/主播（直播场景）加入当前频道回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;

通信场景下，该回调提示有远端用户加入了频道。如果加入之前已经有其他用户在频道中，新加入的用户也会收到这些已有用户加入频道的回调。
直播场景下，该回调提示有主播加入了频道。如果加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。

触发时机

该回调在如下情况下会被触发：

远端用户/主播加入频道。
远端用户加入频道后将用户角色改变为主播。
远端用户/主播网络中断后重新加入频道。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
uid: 新加入频道的远端用户/主播 ID。
elapsed: 从本地用户调用 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 到该回调触发的延迟（毫秒）。

所属接口类

AgoraRtcEngineDelegate

rtcEngine:didOfflineOfUid:reason:

远端用户（通信场景）/主播（直播场景）离开当前频道回调。

Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine
    didOfflineOfUid:(NSUInteger)uid
    reason:(AgoraUserOfflineReason)reason;

用户离开频道一般有以下两个原因：

正常离开：远端用户或主播会发送类似“再见”的消息然后主动离开频道。
超时掉线：在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。建议使用 RTM SDK 来做可靠的掉线检测。

触发时机

在音视频互动过程中，当远端用户或主播离开当前频道时会触发该回调。

使用限制

无。

参数

engine: AgoraRtcEngineKit 对象。
uid: 离线的远端用户或主播的 ID。
reason: 远端用户（通信场景）或主播（直播场景）离线的原因，详见 AgoraUserOfflineReason。

所属接口类

AgoraRtcEngineDelegate

delegate

详情​

getUserInfoByUid:withError:

调用时机

调用限制

相关回调

参数​

返回值​

getUserInfoWithUserId:userInfo:channelId:localUserAccount:

详情​

参数​

返回值​

getUserInfoByUserAccount:withError:

调用时机

调用限制

相关回调

参数​

返回值​

getUserInfoWithUserAccount:userInfo:channelId:localUserAccount:

详情​

参数​

返回值​

joinChannelByToken:channelId:info:uid:joinSuccess:

调用时机

调用限制

相关回调

参数​

返回值​

joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:

调用时机

调用限制

相关回调

参数​

返回值​

joinChannelByToken:channelId:userAccount:joinSuccess:

调用时机

调用限制

相关回调

参数​

返回值​

joinChannelByToken:channelId:userAccount:mediaOptions:joinSuccess:

调用时机

调用限制

相关回调

参数​

返回值​

joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:

适用场景

调用时机

调用限制

相关回调

参数​

返回值​

joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:

调用时机

调用限制

相关回调

参数​

返回值​

leaveChannel:

调用时机

调用限制

相关回调

参数​

返回值​

leaveChannel:leaveChannelBlock:

调用时机

调用限制

相关回调

参数​

返回值​

leaveChannelEx:leaveChannelBlock:

适用场景

调用时机

调用限制

相关回调

参数​

返回值​

leaveChannelEx:options:leaveChannelBlock:

适用场景

详情

参数

返回值

详情

参数

返回值

参数

返回值

详情

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

详情

参数

返回值

参数

参数

详情

参数

详情

参数