# 通过 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)