频道 | 声网文档中心

频道是 RTM 实时网络中一种数据传输的管理机制，任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件，RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。

基于声网的能力，RTM 的频道分成三种类型以匹配不同的应用场景：

Message Channel：遵循行业标准的 Pub/Sub （发布/订阅）模式，频道无需提前创建，订阅频道即可在频道内收发消息。频道内的发布者和订阅者数量没有上限。
User Channel：基于 Pub/Sub （发布/订阅）模式的点对点消息收发。用户无需订阅频道操作，可以直接指定用户 ID 发送消息，接收消息也只需监听 didReceiveMessageEvent 事件。
Stream Channel：遵循行业类似观察者模式的 Room （房间）概念，用户需要创建并加入频道才能在频道内收发消息。频道中允许创建不同的 Topic，消息通过 Topic 进行组织和管理。

想要了解 Message Channel 和 Stream Channel 的更多用法及适用场景，可以查看：

频道

subscribeWithChannel

接口描述

RTM 提供消息、状态、事件变更等事件通知能力。通过设置事件监听，你可以接收已订阅频道中的消息和事件。关于如何添加和设置事件监听，详见事件监听章节。

通过调用 subscribeWithChannel 方法，客户端可以订阅 Message Channel 并开始接收频道中的消息和事件通知。成功调用该方法后，订阅该频道且开启 Presence 事件监听的用户会收到 AgoraRtmPresenceEventTypeRemoteJoinChannel 类型的 didReceivePresenceEvent 事件，详见事件监听。

信息

该方法仅适用于 Message Channel。

接口方法

你可以通过以下方式调用 subscribeWithChannel 方法：

Objective-C

- (void) subscribeWithChannel: (NSString* _Nonnull)channelName
                       option: (AgoraRtmSubscribeOptions* _Nullable)subscribeOption
                   completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

参数	类型	是否必填	默认值	描述
`channelName`	NSString	必填	-	频道名称。
`subscribeOption`	`AgoraRtmSubscribeOptions`	选填	-	订阅频道选项。
`completion`	`AgoraRtmOperationBlock`	选填	-	调用结果回调：调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

AgoraRtmSubscribeOptions 包含以下属性：

属性	类型	是否必填	默认值	描述
`features`	`AgoraRtmSubscribeChannelFeature`	选填	`AgoraRtmSubscribeChannelFeatureMessage` 和 `AgoraRtmSubscribeChannelFeaturePresence`	订阅频道时设置的事件通知类型，你可以通过位操作同时设置多种事件通知。默认设置消息和 Presence 事件通知。

基本用法

Objective-C

AgoraRtmSubscribeOptions* opt = [[AgoraRtmSubscribeOptions alloc] init];
opt.features = AgoraRtmSubscribeChannelFeatureMessage|AgoraRtmSubscribeChannelFeaturePresence;
[rtm subscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe success!!");
    } else {
        NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

unsubscribeWithChannel

接口描述

如果你不再需要关注某个频道，可调用 unsubscribeWithChannel 方法取消订阅该频道。成功取消订阅该频道后，其他订阅该频道并开启事件监听的用户会收到 AgoraRtmPresenceEventTypeRemoteLeaveChannel 类型的 didReceivePresenceEvent 事件通知，详见事件监听。

信息

该方法仅适用于 Message Channel。

接口方法

你可以通过以下方式调用 unsubscribeWithChannel 方法：

Objective-C

- (void) unsubscribeWithChannel: (NSString* _Nonnull)channelName
                     completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

参数	类型	是否必填	默认值	描述
`channelName`	NSString	必填	-	频道名称。
`completion`	`AgoraRtmOperationBlock`	选填	-	调用结果回调：调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

基本用法

Objective-C

[rtm unsubscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe success!!");
    } else {
        NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

createStreamChannel

接口描述

在使用 Stream Channel 之前，你需要先调用 createStreamChannel 方法创建 AgoraRtmStreamChannel 实例。成功创建实例后，你可以调用其相关方法，例如：加入频道、离开频道、发送 Topic 消息、订阅 Topic 消息等。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 createStreamChannel 方法：

Objective-C

- (AgoraRtmStreamChannel * _Nullable)createStreamChannel:(NSString * _Nonnull)channelName
                                                   error:(NSError**)error NS_SWIFT_NAME(createStreamChannel(_:));

参数	类型	是否必填	默认值	描述
`channelName`	NSString	必填	-	频道名称。
`error`	NSError	必填	-	（输出参数）错误描述。

基本用法

Objective-C

AgoraRtmStreamChannel* stream_channel = [rtm createStreamChannel:@"your_channel"];
    if (stream_channel == nil) {
        NSLog("create stream channel failed");
    } else {
        NSLog("create stream channel success");
    };

返回值

方法调用成功，返回一个 AgoraRtmStreamChannel 实例，用以在后续调用 Stream Channel 的其他 API。
nil：方法调用失败。

joinWithOption

接口描述

成功创建 Stream Channel 后，你可以调用 joinWithOption 方法加入 Stream Channel。

加入频道后，你才能进行频道相关操作。此时，订阅该频道并添加事件监听的用户会收到如下事件通知：

本地用户：
- AgoraRtmPresenceEventTypeSnapshot 类型的 didReceivePresenceEvent 事件通知。
- AgoraRtmTopicEventTypeSnapshot 类型的 didReceiveTopicEvent 事件通知。
远端用户：AgoraRtmPresenceEventTypeRemoteJoinChannel 类型的 didReceivePresenceEvent 事件通知。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 joinWithOption 方法：

Objective-C

- (void)joinWithOption: (AgoraRtmJoinChannelOption * _Nonnull)option
            completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

参数	类型	是否必填	默认值	描述
`option`	`AgoraRtmJoinChannelOption`	必填	-	加入频道选项。
`completion`	`AgoraRtmOperationBlock`	选填	-	调用结果回调：调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

AgoraRtmJoinChannelOption 包含以下属性：

属性	类型	是否必填	默认值	描述
`token`	NSString	选填	-	加入 Stream Channel 的 Token。如果你的项目开启了 Token 鉴权，你可以填入 RTC 临时 Token 或 Token 服务器生成的 RTC 正式 Token。如果你的项目未开启 Token 鉴权，你可以填入空字符串或开通了 RTC 和 RTM 服务的项目 App ID。
`features`	`AgoraRtmJoinChannelFeature`	选填	`AgoraRtmJoinChannelFeaturePresence`	加入频道时设置的事件通知类型，你可以通过位操作同时设置多种事件通知。默认设置 Presence 事件通知。

基本用法

Objective-C

AgoraRtmJoinChannelOption* join_opt =  [[AgoraRtmJoinChannelOption alloc] init];
join_opt.token =  @"your_token";
join_opt.features = AgoraRtmSubscribeChannelFeaturePresence | AgoraRtmSubscribeChannelFeatureMetadata;

[stream_channel joinWithOption:join_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"join channel success!!");
    } else {
        NSLog(@"join channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

如果你不再需要待在某个频道中，你可以调用 leave 方法离开该频道。离开后你将不再会接收到此频道中的任何消息、状态及事件通知，你在该频道中创建的 Topic 发布者的角色及你与所有 Topic 的订阅关系都将自动解除。如果想再次恢复之前的发布者角色和订阅关系，你需要调用 joinWithOption 方法再次进入该频道并自行调用 joinTopic 和 subscribeTopic 方法进行设置。

成功离开频道后，频道中的远端用户会收到 AgoraRtmPresenceEventTypeRemoteLeaveChannel 类型的 didReceivePresenceEvent 事件通知，详见事件监听。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 leave 方法：

Objective-C

- (void)leave: (AgoraRtmOperationBlock _Nullable)completionBlock;

参数	类型	是否必填	默认值	描述
`completion`	`AgoraRtmOperationBlock`	选填	-	调用结果回调：调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

基本用法

Objective-C

[stream_channel leave:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"leave channel success!!");
    } else {
        NSLog(@"leave channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

destroy

接口描述

如果你不再需要某个频道，你可以调用 destroy 方法销毁对应的 Stream Channel 实例以释放资源。调用 destroy 方法销毁 Stream Channel 实例不会销毁该频道，后续可通过再次调用 createStreamChannel 和 joinWithOption 重新加入该频道。

信息

该方法仅适用于 Stream Channel。如果不先调用 leave 离开频道而直接调用 destroy 销毁频道实例，SDK 会自动调用 leave 并触发对应的事件。
destroy 需要在非回调内的子线程调用，避免在回调中执行。

接口方法

你可以通过以下方式调用 destroy 方法：

Objective-C

- (AgoraRtmErrorCode) destroy;

基本用法

Objective-C

[stream_channel destroy];
stream_channel = nil;

返回值

destroy 操作会返回一个 AgoraRtmErrorCode 数据结构，详见错误码。

频道

subscribeWithChannel

接口描述

接口方法

基本用法

unsubscribeWithChannel

接口描述

接口方法

基本用法

createStreamChannel

接口描述

接口方法

基本用法

返回值

joinWithOption

接口描述

接口方法

基本用法

leave

接口描述

接口方法

基本用法

destroy

接口描述

接口方法

基本用法

返回值

咨询电话

咨询电话

subscribeWithChannelCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

unsubscribeWithChannelCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

createStreamChannelCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

返回值Copy Anchor Link

joinWithOptionCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

leaveCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

destroyCopy Anchor Link

接口描述Copy Anchor Link

接口方法Copy Anchor Link

基本用法Copy Anchor Link

返回值Copy Anchor Link

咨询电话

咨询电话

subscribeWithChannel

接口描述

接口方法

基本用法

unsubscribeWithChannel

接口描述

接口方法

基本用法

createStreamChannel

接口描述

接口方法

基本用法

返回值

joinWithOption

接口描述

接口方法

基本用法

leave

接口描述

接口方法

基本用法

destroy

接口描述

接口方法

基本用法

返回值