# 频道 (/zh-CN/api-reference/rtm/cpp/channel)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
频道是 RTM 实时网络中一种数据传输的管理机制,任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件,RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。
基于声网的能力,RTM 的频道分成三种类型以匹配不同的应用场景:
- Message Channel:遵循行业标准的 Pub/Sub (发布/订阅)模式,频道无需提前创建,订阅频道即可在频道内收发消息。频道内的发布者和订阅者数量没有上限。
- User Channel:基于 Pub/Sub (发布/订阅)模式的点对点消息收发。用户无需订阅频道操作,可以直接指定用户 ID 发送消息,接收消息也只需监听 `onMessageEvent` 事件。
- Stream Channel:遵循行业类似观察者模式的 Room (房间)概念,用户需要创建并加入频道才能在频道内收发消息。频道中允许创建不同的 Topic,消息通过 Topic 进行组织和管理。
想要了解 Message Channel 和 Stream Channel 的更多用法及适用场景,可以查看:
- [频道](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic)
## subscribe [#subscribe]
### 接口描述 [#接口描述]
RTM 提供消息、状态等事件通知能力。通过设置事件监听,你可以接收已订阅频道中的消息和事件。关于如何添加和设置事件监听,详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)章节。
通过调用 `subscribe` 方法,客户端可以订阅 Message Channel 并开始接收频道中的消息和事件通知。成功调用该方法后,订阅该频道且开启 Presence 事件监听的用户会收到 `RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL` 类型的 `onPresenceEvent` 事件,详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。
:::info[信息]
该方法仅适用于 Message Channel。
:::
### 接口方法 [#接口方法]
你可以通过以下方式调用 `subscribe` 方法:
```cpp
virtual void subscribe(const char* channelName, const SubscribeOptions& options, uint64_t& requestId) = 0;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | const char* | 必填 | - | 频道名称。 |
| `options` | `const SubscribeOptions&` | 必填 | - | 订阅频道选项。 |
| `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 |
`SubscribeOptions` 包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `withMessage` | bool | 选填 | `true` | 是否订阅此频道中的消息事件通知。 |
| `withMetadata` | bool | 选填 | `false` | 是否订阅此频道中的 Storage 事件通知。 |
| `withPresence` | bool | 选填 | `true` | 是否订阅此频道中的 Presence 事件通知。 |
| `withLock` | bool | 选填 | `false` | 是否订阅此频道中的 Lock 事件通知。 |
| `beQuiet` | bool | 选填 | `false` | [channel-cpp-html-1-5-4 details](#table-slot-channel-cpp-html-1-5-4) |
**channel-cpp-html-1-5-4 details**
是否静默订阅频道。该参数设置为 `true` 时表示静默订阅频道,表现如下:
- 不影响你接收频道内其他用户的事件通知。
- 频道内其他用户不会收到你订阅/取消订阅频道、设置/获取/删除临时状态的事件通知。
- 调用 `whoNow` 方法查询不到自己。
- 调用 `whereNow` 方法查询不到自己静默订阅的频道。
### 异步回调 [#异步回调]
调用该方法后,SDK 会触发 `onSubscribeResult` 回调并通过以下参数返回 API 调用结果:
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `requestId` | const uint64_t | 请求标识符。 |
| `channelName` | const char* | 频道名称。 |
| `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 |
### 基本用法 [#基本用法]
```cpp tab="方法调用"
// 方法调用
SubscribeOptions options;
options.withLock = true;
options.withMessage = true;
options.withMetadata = true;
options.withPresence = true;
options.beQuiet = false;
uint64_t requestId;
rtmClient->subscribe("channelName", options, requestId);
```
```cpp tab="异步回调"
// 异步回调
class RtmEventHandler : public IRtmEventHandler {
void onSubscribeResult(const uint64_t requestId, const char *channelName, RTM_ERROR_CODE errorCode) {
if (errorCode != RTM_ERROR_OK) {
printf("subscribe rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
} else {
printf("subscribe rtm channel %s success\n", channelName);
}
}
};
```
## unsubscribe [#unsubscribe]
### 接口描述 [#接口描述-1]
如果你不再需要关注某个频道,可调用 `unsubscribe` 方法取消订阅该频道。成功取消订阅该频道后,其他订阅该频道并开启事件监听的用户会收到 `RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL` 类型的 `onPresenceEvent` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。
:::info[信息]
该方法仅适用于 Message Channel。
:::
### 接口方法 [#接口方法-1]
你可以通过以下方式调用 `unsubscribe` 方法:
```cpp
virtual void unsubscribe(const char* channelName, uint64_t& requestId) = 0;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | const char* | 必填 | - | 频道名称。 |
| `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 |
### 异步回调 [#异步回调-1]
调用该方法后,SDK 会触发 `onUnsubscribeResult` 回调并通过以下参数返回 API 调用结果:
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `requestId` | const uint64_t | 请求标识符。 |
| `channelName` | const char* | 频道名称。 |
| `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 |
### 基本用法 [#基本用法-1]
```cpp
uint64_t requestId;
rtm_client->unsubscribe("channelName", requestId);
```
```cpp
// 异步回调
class RtmEventHandler : public IRtmEventHandler {
void onUnsubscribeResult(const uint64_t requestId, const char* channelName, RTM_ERROR_CODE errorCode) override {
if (errorCode != RTM_ERROR_OK) {
printf("unsubscribe rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
} else {
printf("unsubscribe rtm channel %s success\n", channelName);
}
}
};
```
## createStreamChannel [#createstreamchannel]
### 接口描述 [#接口描述-2]
在使用 Stream Channel 之前,你需要先调用 `createStreamChannel` 方法创建 `IStreamChannel` 实例。成功创建实例后,你可以调用其相关方法,例如:加入频道、离开频道、发送 Topic 消息、订阅 Topic 消息等。
:::info[信息]
该方法仅适用于 Stream Channel。
:::
### 接口方法 [#接口方法-2]
你可以通过以下方式调用 `createStreamChannel` 方法:
```cpp
virtual IStreamChannel* createStreamChannel(const char* channelName, int& errorCode) = 0;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| ---------- | --- | ----- | --- | ---------- |
| `channelName` | const char* | 必填 | - | 频道名称。 |
| `errorCode` | int& | 必填 | - | (输出参数)[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting#errorcode)。 |
### 基本用法 [#基本用法-2]
```cpp
int errorCode = 0;
IStreamChannel* streamChannel = rtmClient->createStreamChannel("channelName", errorCode);
if (streamChannel == nullptr || errorCode != 0) {
printf("create stream channel failed");
} else {
printf("create stream channel success");
}
```
### 返回值 [#返回值]
- 方法调用成功:一个指向 [`IStreamChannel`](#IStreamChannel) 对象的指针。
- 方法调用失败:`NULL`。
## join [#join]
### 接口描述 [#接口描述-3]
成功创建 Stream Channel 后,你可以调用 `join` 方法加入 Stream Channel。
成功加入频道后,你才能进行频道相关操作。此时,订阅该频道并添加事件监听的用户会收到如下事件通知:
- 本地用户:
- `RTM_PRESENCE_EVENT_TYPE_SNAPSHOT` 类型的 `onPresenceEvent` 事件通知。
- `RTM_TOPIC_EVENT_TYPE_SNAPSHOT` 类型的 `onTopicEvent` 事件通知。
- 远端用户:`RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL` 类型的 `onPresenceEvent` 事件通知。
:::info[信息]
该方法仅适用于 Stream Channel。
:::
### 接口方法 [#接口方法-3]
你可以通过以下方式调用 `join` 方法:
```cpp
virtual void join(const JoinChannelOptions& options, uint64_t& requestId) = 0;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `options` | `const JoinChannelOptions&` | 必填 | - | 加入频道选项。 |
| `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 |
`JoinChannelOptions` 包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `token` | const char* | 必填 | - | [channel-cpp-html-6-1-4 details](#table-slot-channel-cpp-html-6-1-4) |
| `withMetadata` | bool | 选填 | `false` | 是否订阅此频道中的 Storage 事件通知。 |
| `withPresence` | bool | 选填 | `true` | 是否订阅此频道中的 Presence 事件通知。 |
| `withLock` | bool | 选填 | `false` | 是否订阅此频道中的 Lock 事件通知。 |
| `beQuiet` | bool | 选填 | `false` | [channel-cpp-html-6-5-4 details](#table-slot-channel-cpp-html-6-5-4) |
**channel-cpp-html-6-1-4 details**
加入 Stream Channel 的 Token。
- 如果你的项目开启了 Token 鉴权,你可以填入 [RTC 临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service#获取临时-token) 或 Token 服务器生成的 [RTC 正式 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
- 如果你的项目未开启 Token 鉴权,你可以填入空字符串或开通了 RTC 和 RTM 服务的项目 App ID。
**channel-cpp-html-6-5-4 details**
是否静默加入频道。该参数设置为 `true` 时表示静默加入频道,表现如下:
- 不影响你接收频道内其他用户的事件通知。
- 频道内其他用户不会收到你加入/离开频道、设置/获取/删除临时状态的事件通知。
- 调用 `whoNow` 方法查询不到自己。
- 调用 `whereNow` 方法查询不到自己静默加入的频道。
### 异步回调 [#异步回调-2]
调用该方法后,SDK 会触发 `onJoinResult` 回调并通过以下参数返回 API 调用结果:
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `requestId` | const uint64_t | 请求标识符。 |
| `channelName` | const char* | 频道名称。 |
| `userId` | const char* | 用户 ID。 |
| `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 |
### 基本用法 [#基本用法-3]
```cpp tab="方法调用"
// 方法调用
JoinChannelOptions options;
options.token = "your_token";
options.withLock = false;
options.withMetadata = false;
options.withPresence = true;
options.beQuiet = false;
uint64_t requestId;
streamChannel->join(options, requestId);
```
```cpp tab="异步回调"
// 异步回调
class RtmEventHandler : public IRtmEventHandler {
void onJoinResult(const uint64_t requestId, const char *channelName, const char *userId, RTM_ERROR_CODE errorCode) {
if (errorCode != RTM_ERROR_OK) {
printf("join rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
} else {
printf("join rtm channel %s success\n", channelName);
}
}
};
```
## leave [#leave]
### 接口描述 [#接口描述-4]
如果你不再需要待在某个频道中,你可以调用 `leave` 方法离开该频道。离开后你将不再会接收到此频道中的任何消息、状态及事件通知,你在该频道中创建的 Topic 发布者的角色及你与所有 Topic 的订阅关系都将自动解除。如果想再次恢复之前的发布者角色和订阅关系,你需要调用 `join` 方法再次进入该频道并自行调用 `joinTopic` 和 `subscribeTopic` 方法进行设置。
成功离开频道后,频道中的远端用户会收到 `RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL` 类型的 `onPresenceEvent` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。
:::info[信息]
该方法仅适用于 Stream Channel。
:::
### 接口方法 [#接口方法-4]
你可以通过以下方式调用 `leave` 方法:
```cpp
virtual void leave(uint64_t& requestId) = 0;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 |
#### 异步回调 [#异步回调-3]
调用该方法后,SDK 会触发 `onLeaveResult` 回调并通过以下参数返回 API 调用结果:
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `requestId` | const uint64_t | 请求标识符。 |
| `channelName` | const char* | 频道名称。 |
| `userId` | const char* | 用户 ID。 |
| `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 |
### 基本用法 [#基本用法-4]
```cpp tab="方法调用"
// 方法调用
uint64_t requestId;
streamChannel->leave(requestId);
```
```cpp tab="异步回调"
// 异步回调
class RtmEventHandler : public IRtmEventHandler {
void onLeaveResult(const uint64_t requestId, const char *channelName, const char *userId, RTM_ERROR_CODE errorCode) {
if (errorCode != RTM_ERROR_OK) {
printf("leave rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
} else {
printf("leave rtm channel %s success\n", channelName);
}
}
};
```
## release [#release]
### 接口描述 [#接口描述-5]
如果你不再需要某个频道,你可以调用 `release` 方法销毁对应的 Stream Channel 实例以释放资源。调用 `release` 方法销毁 Stream Channel 实例不会销毁该频道,后续可通过再次调用 `createStreamChannel` 和 `join` 重新加入该频道。
:::info[信息]
- 该方法仅适用于 Stream Channel。如果不先调用 `leave` 离开频道而直接调用 `release` 销毁频道实例,SDK 会自动调用 `leave` 并触发对应的事件。
- `release` 需要在非回调内的子线程调用,避免在回调中执行。
:::
### 接口方法 [#接口方法-5]
你可以通过以下方式调用 `release` 方法:
```cpp
virtual int release() = 0;
```
### 基本用法 [#基本用法-5]
```cpp
int ret = streamChannel->release();
```
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。