频道

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

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

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

AgoraRtmClientKit RTM 客户端实例

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：方法调用失败。

AgoraRtmStreamChannel Stream Channel 实例

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

接口描述

如果你不再需要待在某个频道中，你可以调用 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 方法：

Objective-C

- (AgoraRtmErrorCode) destroy;

基本用法

Objective-C

[stream_channel destroy];
stream_channel = nil;

返回值

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