# 通过 RDT 通道收发消息 (/zh-CN/realtime-media/rtsa/build/data-communication/send-message-through-rdt-channel)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在文件传输、文件下载等业务场景中，通常需要可靠的数据传输来保证数据的完整性和有序性，从而避免因网络等问题造成的数据丢失。自 1.9.2 版本起，声网提供 RDT（Reliable Data Transmission, 可靠数据传输）功能，允许同一频道中的用户之间建立 RDT 通道并进行可靠的数据传输。
本文主要介绍如何在 RDT 通道中收发消息。
## 实现原理 [#实现原理]
RDT 通道是一种基于 RTC Connection 的端到端可靠数据传输通道，如下图所示，RDT 通道与音视频通道相互独立。在一个 RTC Connection 中，你可以同时发送音频数据、视频数据和 RDT 消息。
RDT 消息分为控制消息和数据消息，区别如下：
- 控制消息 (`RDT_STREAM_CMD`)：发送优先级高，不受拥塞控制策略影响，不会阻塞发送。每秒至多发送 100 个消息包，每个消息包的长度至多为 256 B。
- 数据消息 (`RDT_STREAM_DATA`)：发送优先级低，受拥塞控制策略影响。如果缓冲区已满，则消息发送失败。对发送的消息包数量没有限制，每个消息包的长度至多为 128 KB。
下图展示通过 RDT 通道收发消息的基本流程：
## 前提条件 [#前提条件]
开始前，请确保已完成 SDK 的初始化并创建 RTC Connection。参考 [实现媒体流和信令传输](/zh-CN/realtime-media/rtsa/build/media-and-signaling-transmission/implement-transmission)。
## 实现发送和接收 RDT 消息 [#实现发送和接收-rdt-消息]
本节介绍如何实现在 RDT 通道中收发消息。
### 1. 加入 RTC 频道并建立 RDT 连接 [#1-加入-rtc-频道并建立-rdt-连接]
:::info[信息]
本节仅适用于 v1.9.2 之后、v1.9.4 之前版本的 SDK。对于 v1.9.4 及之后的版本，`auto_connect_rdt` 在 SDK 内部默认设置为 `true`，不再需要额外设置；你只需要在调用 `agora_rtc_join_channel` 加入 RTC 频道时，将 `rtc_channel_options_t` 中的 `enable_rdt` 设为 `true` 即可使用 RDT 功能。如果你不想启用该功能，则将 `enable_rdt` 设为 `false`。
:::
加入 RTC 频道时，你可以通过 `rtc_channel_options_t` 中的 `auto_connect_rdt` 参数来设置是否主动建立 RDT 连接。SDK 会根据 `on_user_joined`、`on_user_offline` 回调和你在 `auto_connect_rdt` 参数中的设置来处理 RDT 连接：
- 如果你设置 `auto_connect_rdt` 参数为 `true`，则 SDK 会在收到 `on_user_joined` 回调后主动与远端用户建立 RDT 连接，在收到 `on_user_offline` 回调后主动与远端用户断开 RDT 连接。
- 如果你设置 `auto_connect_rdt` 参数为 `false`，则 SDK 不会主动与远端用户建立 RDT 连接，但会接受远端用户的连接邀请。
:::warning[注意]
只有用户角色为主播时，SDK 才会触发 `on_user_joined` 和 `on_user_offline` 回调。RTSA SDK 中默认所有用户都是主播，无需额外设置用户角色。如果你需要将 RTSA SDK 搭配其他 SDK（例如 RTC SDK）一起使用，请确保你在其他 SDK 中设置用户角色为主播。
:::
不同场景对可靠传输的需求不同，你需要根据实际需求设置 `auto_connect_rdt` 参数，例如：
- 在智能摄像头、智能门铃等 IoT 场景中，可能只需要让所有客户端和设备端收发 RDT 消息，但无需让客户端之间收发 RDT 消息。在这种情况下，你需要在设备端加入频道时设置 `auto_connect_rdt` 为 `true`，让设备端与每一个客户端都建立 RDT 连接；在客户端加入频道时设置 `auto_connect_rdt` 为 `false`，让客户端之间不建立 RDT 连接。
- 在视频会议、实时协作等办公场景中，可能需要让所有用户之间都能收发数据。在这种情况下，你需要在所有用户加入频道时设置 `auto_connect_rdt` 为 `true`，让所有用户都相互建立 RDT 连接。
```c
int ret = 0;
connection_id_t conn_id = 0;
ret = agora_rtc_create_connection(&conn_id);
if (ret != 0) {
printf("error info: %s", agora_rtc_err_2_str(ret));
return -1;
}
rtc_channel_options_t channel_opt = {0};
// 设置是否主动建立 RDT 连接。true：主动建立连接；false：不主动建立连接
channel_opt.auto_connect_rdt = true;
ret = agora_rtc_join_channel(conn_id, "channel-xxx", uid, token, &channel_opt);
if (ret != 0) {
printf("error info: %s", agora_rtc_err_2_str(ret));
return -1;
}
```
### 2. 监听 RDT 通道的状态 [#2-监听-rdt-通道的状态]
监听 `on_rdt_state` 回调，获取 RDT 通道的状态。你需要根据该状态判断能否收发 RDT 消息。
- `RDT_STATE_CLOSED`：初始状态，未连接 RDT 通道。该状态下用户不可以收发 RDT 消息。
- `RDT_STATE_OPENED`：已连接 RDT 通道。该状态下用户可以收发 RDT 消息。
- `RDT_STATE_BLOCKED`：RDT 通道中的发送缓冲区已满。该状态下用户不可以发送数据消息 (`RDT_STREAM_DATA`)，但可以发送控制消息 (`RDT_STREAM_CMD`)。
- `RDT_STATE_PENDING`：正在重新连接 RDT 通道。
- 如果重新连接成功，则连接状态会变为 `RDT_STATE_OPENED`，SDK 会保留 RDT 通道中发送和接收缓冲区中的历史数据。
- 如果重新连接失败，则连接状态会变为 `RDT_STATE_CLOSED`，SDK 会清除 RDT 通道中发送和接收缓冲区中的历史数据。
- `RDT_STATE_BROKEN`：与 RDT 通道的连接已损坏，SDK 会尝试重新连接。SDK 不论能否成功连接，都会清空 RDT 通道中发送和接收缓冲区中的历史数据。
```c
rdt_state_e g_rdt_state_for_uid_xxx = RDT_STATE_CLOSED;
void __on_rdt_state(connection_id_t conn_id, uint32_t uid, rdt_state_e state)
{
g_rdt_state_for_uid_xxx = state;
}
```
此外，你也可以调用 `agora_rtc_get_rdt_status_info` 方法主动获取 RDT 通道的状态。
### 3. 通过 RDT 通道发送消息 [#3-通过-rdt-通道发送消息]
当 RDT 通道的状态为 `RDT_STATE_OPENED` 时，用户之间才真正地成功建立了 RDT 通道，你可以调用 `agora_rtc_send_rdt_msg` 方法在 RDT 通道中发送消息。
```c tab="发送控制消息" tabGroup="datatype"
if (g_rdt_state_for_uid_xxx == RDT_STATE_OPENED || g_rdt_state_for_uid_xxx == RDT_STATE_BLOCKED) {
uint8_t cmd[256] = {xxxxx};
ret = agora_rtc_send_rdt_msg(conn_id, peer_id, RDT_STREAM_CMD, cmd, 256);
if (ret != 0) {
printf("error info: %s", agora_rtc_err_2_str(ret));
return -1;
}
}
```
```c tab="发送数据消息" tabGroup="datatype"
if (g_rdt_state_for_uid_xxx == RDT_STATE_OPENED) {
uint8_t msg[1024] = {xxxxx};
ret = agora_rtc_send_rdt_msg(conn_id, peer_id, RDT_STREAM_DATA, msg, 1024);
if (ret != 0) {
printf("error info: %s", agora_rtc_err_2_str(ret));
return -1;
}
}
```
如果 RDT 消息发送失败，SDK 会报告如下错误码，你可以根据错误码判断失败原因并处理：
- `RTC_ERR_RDT_USER_NOT_EXIST` (-8): 频道内不存在该远端用户。
- `RTC_ERR_RDT_USER_NOT_READY` (-9): 未成功与远端用户建立连接。你需要等 RDT 通道的连接状态变为 `RDT_STATE_OPENED` 后重新调用该方法。
- `RTC_ERR_RDT_DATA_BLOCKED` (-10): 发送缓冲区已满。你需要等 RDT 通道的连接状态变为 `RDT_STATE_OPENED` 后重新调用该方法。
- `RTC_ERR_RDT_CMD_EXCEED_LIMIT` (-11): 控制消息的数量超过限制。每秒发送的控制消息包不能超过 100 个。
### 4. 通过 RDT 通道接收消息 [#4-通过-rdt-通道接收消息]
如需接收 RDT 消息，你可以监听 `on_rdt_msg` 回调。
```c
void __on_rdt_msg(connection_id_t conn_id, uint32_t uid, rdt_stream_type_e type, const void *msg, size_t len)
{
printf("received rdt msg from uid=%u type=%d msg len=%zu\n", uid, type, len);
}
```
### 5. 断开 RDT 连接 [#5-断开-rdt-连接]
离开 RTC 频道后，用户在该频道内创建的 RDT 连接都会自动断开。为避免正在传输中的数据丢失，声网推荐你先调用 `agora_rtc_get_rdt_status_info` 方法查询发送缓冲区长度 (`send_queue_size`)，确保远端用户已接收完 RDT 消息 (`send_queue_size = 0`) 后再离开 RTC 频道。
## 相关信息 [#相关信息]
本节提供了在实现 RDT 功能时可能需要的参考信息。
### 示例代码 [#示例代码]
声网在 SDK 包中提供了以下示例代码供你参考：
```shell
├── agora_rtsa_sdk # 声网的 SDK 库文件和头文件
└── example # 示例代码
└── hello_rdt
├── hello_rdt.c #在单个频道中使用 RDT 通道收发消息
└── hello_rdt_multi.c #在多频道中使用 RDT 通道收发消息
```
### API 参考 [#api-参考]
在实现功能的过程中，你可能需要参考如下 API 文档：
- [`agora_rtc_join_channel`](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a6c29ff27f04623526a164cf6e5dcd738)
- [`agora_rtc_send_rdt_msg`](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a056de38235f67ad1ea91cfd695ffaf61)
- [`agora_rtc_get_rdt_status_info`](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a80f16bf3cf9bcdf8a6cecc51f8e584aa)
- [`on_rdt_state`](/zh-CN/api-reference/rtsa/c/structagora-rtc-event-handler-t#afe6c35e916473a1424f28d3fefbdda69)
- [`on_rdt_msg`](/zh-CN/api-reference/rtsa/c/structagora-rtc-event-handler-t#a7b5b9ba5f3acaf9b336040e4edd282a5)