# Topic (/zh-CN/api-reference/rtm/ios/topic)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Topic 是 Stream Channel 中的数据流管理机制。用户可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等。

:::info[信息]
Topic 只存在于 Stream Channel。所以用户在使用相关特性之前，需要先创建一个 `AgoraRtmStreamChannel` 对象实例。
:::

想要了解 Topic 的更多特性，可以查看：

- [Topic](/zh-CN/realtime-media/rtm/build/channels-and-topics/topics/topic-basic)

## joinTopic [#jointopic]

### 接口描述 [#接口描述]

加入 Topic 的目的在于注册成为该 Topic 的消息发布者之一，从而让用户具备发送消息的能力。是否执行该操作都不影响该用户是否成为该 Topic 的订阅者。

:::info[信息]
- 当前 RTM 支持单客户端在同一个 Stream Channel 中同时加入 8 个 Topic。
- 在执行此操作之前，用户需要首先创建 `AgoraRtmStreamChannel` 对象实例，并调用 `joinWithOption` 方法加入频道，详见[频道](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic)。
:::

成功加入 Topic 后，订阅该 Topic 并添加事件监听的用户会收到 `AgoraRtmTopicEventTypeRemoteJoinTopic` 类型的 `didReceiveTopicEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/ios/configuration#事件监听)。

### 接口方法 [#接口方法]

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

```objc
- (void) joinTopic:(NSString * _Nonnull)topic
            option:(AgoraRtmJoinTopicOption * _Nullable)option
        completion:(AgoraRtmOperationBlock _Nullable)completionBlock
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `topic` | NSString | 必填 | - | Topic 名称。 |
| `option` | `AgoraRtmJoinTopicOption` | 选填 | - | 加入 Topic 选项。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [topic-ios-html-0-3-4 details](#table-slot-topic-ios-html-0-3-4) |

<a id="table-slot-topic-ios-html-0-3-4"></a>

**topic-ios-html-0-3-4 details**

调用结果回调：

- 调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。
- 调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

`AgoraRtmJoinTopicOption` 数据类型包含以下属性：

|     属性     |  类型  |  是否必填  |  默认值  |                     描述                     |
| -------------- | ---- | ----- | --- | ---------- |
| `qos` | `AgoraRtmMessageQos` |  选填  | `AgoraRtmMessageQosUnordered`    | 定义此 Topic 中传输数据是否保序。详见 [`AgoraRtmMessageQos`](/zh-CN/api-reference/rtm/ios/enumv#messageqos)。 |
|     `priority`     |  `AgoraRtmMessagePriority` |  选填  |   `AgoraRtmMessagePriorityNormal`      | 定义此 Topic 中传输数据的优先级（相比于同频道中的其他 Topic）。详见 [`AgoraRtmMessagePriority`](/zh-CN/api-reference/rtm/ios/enumv#messagepriority)。 |
|  `meta`  |  NSString |  选填  |     -     |    加入 Topic 时携带的其他辅助信息。                    |
|  `syncWithMedia`  |  BOOL |  选填  |     `false`     |  此 Topic 中发送的数据是否与共频道的 RTC 音视频数据流实现数据同步（时间戳对齐）。     |

### 基本用法 [#基本用法]

```objc
AgoraRtmJoinTopicOption* join_topic_opt = [[AgoraRtmJoinTopicOption alloc] init];
join_topic_opt.qos = AgoraRtmMessageQosOrdered;
[stream_channel joinTopic:@"your_topic" option:join_topic_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"join topic success!!");
    } else {
        NSLog(@"join topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

## publishTopicMessage [#publishtopicmessage]

### 接口描述 [#接口描述-1]

`publishTopicMessage` 方法用于向 Topic 发送消息，频道中订阅此 Topic 及此消息发布者的用户会在 100 毫秒内收到此消息。调用 `publishTopicMessage` 方法需要用户首先加入 Stream Channel 并且通过调用 `joinTopic` 方法注册成为该 Topic 的消息发布者。

用户发送的消息在传输的过程中会被 TLS 加密，数据链路加密默认开启且无法关闭。用户也可以在出初始化的时候开启端侧加密，以获得更高的数据安全等级，详见[初始配置](/zh-CN/api-reference/rtm/ios/configuration)。

### 接口方法 [#接口方法-1]

你可以通过以下方式调用 `publishTopicMessage`[1/2] 和 `publishTopicMessage`[2/2] 方法：

```objc tab="publishTopicMessage[1/2]"
// publishTopicMessage[1/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
                     message:(NSString * _Nonnull)message
                      option:(AgoraRtmTopicMessageOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock
```

```objc tab="publishTopicMessage[2/2]"
// publishTopicMessage[2/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
  data:(NSData * _Nonnull)data
                      option:(AgoraRtmTopicMessageOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `topic` | NSString | 必填 | - | Topic 名称。 |
| `message` | NSString | 必填 | - | 在 `publishTopicMessage`[1/2] 方法中发布 String 型消息负载。 |
| `data` | NSData | 必填 | - | 在 `publishTopicMessage`[2/2] 方法中发布 Byte 型消息负载。 |
| `options` | `AgoraRtmTopicMessageOptions` | 选填 | - | 消息选项。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [topic-ios-html-1-5-4 details](#table-slot-topic-ios-html-1-5-4) |

<a id="table-slot-topic-ios-html-1-5-4"></a>

**topic-ios-html-1-5-4 details**

调用结果回调：

- 调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。
- 调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

<a id="options"></a>
`AgoraRtmTopicMessageOptions` 数据类型包含以下属性：

|     属性     |  类型  | 是否必填 | 默认值 | 描述  |
| --------- | --- | ----- | --- | ----------- |
| `sendTs` | unsigned long long |   选填   |   `0`    | 消息发送时间戳。只有在 `joinTopic` 中设置 `syncWithMedia = true` 时，该参数才有效，SDK 会根据此时间戳与 RTC 音视频数据流进行数据同步。   |
| `customType` | NSString |   必填   |   -    | 用户自定义字段。仅支持 NSString 型。 |

### 接口方法 [#接口方法-2]

示例 1：向指定频道发送 String 消息

```objc
NSString* message = @"Hello Agora!";
NSString* channel = @"your_channel";
[stream_channel publishTopicMessage:@"your_topic" message:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

示例 2：向指定频道发送 Byte 消息

```objc
unsigned char byte_array[5] = {0,1,2,3,4};
NSData* raw_message = [[NSData alloc] initWithBytes:byte_array length:5];
NSString* channel = @"your_channel";
[stream_channel publishTopicMessage:@"your_topic" data:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

## leaveTopic [#leavetopic]

### 接口描述 [#接口描述-2]

当你不再需要向某个 Topic 发布消息，你可以调用 `leaveTopic` 方法取消注册为该 Topic 的消息发布者，从而释放资源。该方法不影响你是否订阅该 Topic，也不影响其他用户对该 Topic 的任何操作。

成功调用该方法后，订阅该频道并开启事件监听的用户会收到 `AgoraRtmTopicEventTypeRemoteLeaveTopic` 类型的 `didReceiveTopicEvent` 事件通知，详见[事件监听](/zh-CN/api-reference/rtm/ios/configuration#事件监听)。

### 接口方法 [#接口方法-3]

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

```objc
- (void) leaveTopic: (NSString * _Nonnull)topic
         completion: (AgoraRtmOperationBlock _Nullable)completionBlock;
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `topic` | NSString | 必填 | - | Topic 名称。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [topic-ios-html-2-2-4 details](#table-slot-topic-ios-html-2-2-4) |

<a id="table-slot-topic-ios-html-2-2-4"></a>

**topic-ios-html-2-2-4 details**

调用结果回调：

- 调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。
- 调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

### 基本用法 [#基本用法-1]

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

    }
}];
```

## subscribeTopic [#subscribetopic]

### 接口描述 [#接口描述-3]

加入频道后，你可以调用 `subscribeTopic` 方法订阅该频道中 Topic 的消息发布者。

`subscribeTopic` 为增量方法。例如，第一次调用该方法时，订阅消息发布者列表为 `[UserA, UserB]`，第二次调用该方法时，订阅消息发布者列表为 `[UserB, UserC]`，则最后成功订阅的结果是 `[UserA, UserB, UserC]`。

同一个用户在同一个频道中最多只能同时订阅 50 个 Topic，且每个 Topic 中最多只能订阅 64 个消息发布者。详见 [API 调用限制](/zh-CN/realtime-media/rtm/reference/usage-limits-and-errors/api-limits)。

### 接口方法 [#接口方法-4]

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

```objc
- (void) subscribeTopic:(NSString * _Nonnull)topic
                 option:(AgoraRtmTopicOption * _Nullable)option
             completion:(AgoraRtmTopicSubscriptionBlock _Nullable)completionBlock
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `topic` | NSString | 必填 | - | Topic 名称。 |
| `option` | `AgoraRtmTopicOption` | 选填 | - | 订阅 Topic 选项。 |
| `completion` | `AgoraRtmTopicSubscriptionBlock` | 选填 | - | [topic-ios-html-3-3-4 details](#table-slot-topic-ios-html-3-3-4) |

<a id="table-slot-topic-ios-html-3-3-4"></a>

**topic-ios-html-3-3-4 details**

调用结果回调：

- 调用成功：在 `response` 参数中返回 `AgoraRtmTopicSubscriptionResponse` 数据，在 `errorInfo` 参数中返回 `nil`。
- 调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

`AgoraRtmTopicOption` 数据类型包含以下属性：

|  属性   |   类型   | 是否必填 | 默认值 |           描述            |
| ---- | ----- | ----- | --- | ------- |
| `users` | `NSArray<NSString *>` |   选填   |   -    | 需要订阅的消息发布者（Publisher）的 `UserId` 列表，如果不设置，则默认随机订阅不超过 64 个用户。 |

`AgoraRtmTopicSubscriptionResponse` 数据类型包含如下属性：

|  属性  |  类型  | 描述               |
| ----------- | ---------------- | ------ |
| `succeedUsers`      |      `NSArray<NSString *>`      | 订阅成功的用户列表。 |
| `failedUsers`      | `NSArray<NSString *>` | 订阅失败的用户列表。 |

### 基本用法 [#基本用法-2]

示例 1：订阅 Topic 中指定的消息发布者

```objc
AgoraRtmTopicOption* topic_opt = [[AgoraRtmTopicOption alloc] init];
topic_opt.users = @[@"user1", @"user2"];
[stream_channel subscribeTopic:@"your_topic" option:topic_opt completion:^(AgoraRtmTopicSubscriptionResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSArray<NSString *> *sucees_users = response.succeedUsers;
        NSArray<NSString *> *fail_users = response.failedUsers;
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

示例 2：随机订阅 Topic 中的 64 个消息发布者

```objc
[stream_channel subscribeTopic:@"your_topic" option:nil completion:^(AgoraRtmTopicSubscriptionResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

## unsubscribeTopic [#unsubscribetopic]

### 接口描述 [#接口描述-4]

如果你对某个 Topic 不再感兴趣，或者不再需要订阅 Topic 中的一个或多个消息发布者，你可以调用 `unsubscribeTopic` 方法取消订阅该 Topic 或取消订阅该 Topic 中指定的消息发布者。

### 接口方法 [#接口方法-5]

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

```objc
- (void) unsubscribeTopic:(NSString * _Nonnull)topic
                   option:(AgoraRtmTopicOption * _Nullable)option
               completion:(AgoraRtmOperationBlock _Nullable)completionBlock
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `topic` | NSString | 必填 | - | Topic 名称。 |
| `options` | `AgoraRtmTopicOption` | 选填 | - | 取消订阅 Topic 选项。 |
| `completion` | `AgoraRtmOperationBlock` | 选填 | - | [topic-ios-html-4-3-4 details](#table-slot-topic-ios-html-4-3-4) |

<a id="table-slot-topic-ios-html-4-3-4"></a>

**topic-ios-html-4-3-4 details**

调用结果回调：

- 调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。
- 调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

`AgoraRtmTopicOption` 数据类型包含以下属性：

|  属性   |   类型   | 是否必填 | 默认值 |           描述            |
| ---- | ----- | ----- | --- | ------- |
| `users` | `NSArray<NSString *>` |   选填   |   -    | 需要取消订阅的消息发布者（Publisher）的 `UserId` 列表，如果不设置，则默认随机取消订阅不超过 64 个用户。 |

### 基本用法 [#基本用法-3]

示例 1：取消订阅 Topic 中指定的消息发布者

```objc
AgoraRtmTopicOption* topic_opt = [[AgoraRtmTopicOption alloc] init];
topic_opt.users = @[@"user1", @"user2"];
[stream_channel unsubscribeTopic:@"your_topic" option:topic_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```

示例 2：随机取消订阅 Topic 中的 64 个消息发布者

```objc
[stream_channel unsubscribeTopic:@"your_topic" option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];
```