# agora::rtc::IRtcConnection类 参考 (/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
继承自 agora::RefCountInterface.
## 详细描述 [#详细描述]
[`IRtcConnection`](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection) 类,用于管理 SDK 与 RTC 频道之间的连接。
连接完成之后,你可以通过 [`ILocalUser`](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-local-user) 对象在 RTC 频道中发送和接收媒体流。
连接频道是异步操作,你可以通过 [IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) 对象监听连接状态变化和事件。[`IRtcConnection`](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection) 还可以监控频道中的远端用户是否加入或离开频道。
## 构造及析构函数说明 [#构造及析构函数说明]
### ~IRtcConnection() [#irtcconnection]
agora::rtc::IRtcConnection::~IRtcConnection()
## 成员函数说明 [#成员函数说明]
### connect() [#connect]
virtual int agora::rtc::IRtcConnection::connect(const char * *token*, const char * *channelId*, [user_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a67aa7eac4d2b30c5c02951f1303bcc48) *userId*)
连接 RTC 频道。
方法成功时,连接状态由 `CONNECTION_STATE_DISCONNECTED(1)` 变更为 `CONNECTION_STATE_CONNECTING(2)`。
根据连接是否成功,连接状态会变更为 `CONNECTION_STATE_CONNECTED(3)` 或 `CONNECTION_STATE_FAILED(5)`。 SDK 会触发 `onConnected` 或 `onDisconnected` 提醒连接状态变更。
RTC Token。详见 使用 Token 鉴权 。如果你的项目中未开启 App 证书,则仅需在该参数中填写你声网项目的 App ID。
频道名。必须为字符串且长度不超过 64 字节。支持的字符类型包括:
- 全部小写字母: a to z
- 全部大写字母:A to Z
- 全部阿拉伯数字: 0 to 9
- 空格。
- 标点符号和其他特殊符号: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " \{", "\}", "|", "~", ","
本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 NULL,SDK 在 [onConnected](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a1df408778b1886055df47cd7d0ff8e5c) 回调中自动返回一个 user ID。 你必须自行记录并管理此 ID。根据你在 [initialize](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1base-1-1-i-agora-service#a6f1fb6e792c564dee46903cbb3bc35fc) 方法中选择的用户 ID 类型,该参数支持的字符集也不同:
- int 型用户 ID 支持的字符集包括:
- 10 个数字 0-9
- String 型用户 ID 支持的字符集包括:
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " \{", "\}", "|", "~", ","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(ERR_INVALID_ARGUMENT):参数无效。
- -8(ERR_INVALID_STATE): 当前连接状态不是 CONNECTION_STATE_DISCONNECTED(1)。
### disconnect() [#disconnect]
virtual int agora::rtc::IRtcConnection::disconnect()
与 RTC 频道断开连接。
SDK 与频道断开连接时,连接状态变更为 `CONNECTION_STATE_DISCONNECTED(1)`。你还可以通过 [onDisconnected](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#ae62590c268ad2904583dc9c62c337056) 回调得知。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### startLastmileProbeTest() [#startlastmileprobetest]
virtual int agora::rtc::IRtcConnection::startLastmileProbeTest(const [LastmileProbeConfig](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-lastmile-probe-config) & *config*)
开始通话前网络质量探测。
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
启用该方法后,SDK 会依次返回如下 2 个回调:
- [onLastmileQuality](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a255ffd92a1b67201f04d018e163118fc): 视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- [onLastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a91037dcd860c1000e31a3d0eecb1889a): 视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
:::info[注解]
:::
- 调用该方法后,在收到 [onLastmileQuality](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a255ffd92a1b67201f04d018e163118fc) 和 [onLastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a91037dcd860c1000e31a3d0eecb1889a) 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
Last mile 网络探测配置,详见 [LastmileProbeConfig](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-lastmile-probe-config) 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### stopLastmileProbeTest() [#stoplastmileprobetest]
virtual int agora::rtc::IRtcConnection::stopLastmileProbeTest()
停止通话前网络质量探测。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### renewToken() [#renewtoken]
virtual int agora::rtc::IRtcConnection::renewToken(const char * *token*)
更新 Token。
Token 会在一定时间后过期。
当收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer#a27ee9184ccaba5855389412846f6949f) 回调时,你必须从服务端生成一个新的 token,并使用该方法更新 Token。否则,SDK 会与频道断开连接。
新 Token。
### getConnectionInfo() [#getconnectioninfo]
virtual [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) agora::rtc::IRtcConnection::getConnectionInfo()
获取连接信息。
返回值
- [TConnectionInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-t-connection-info) 对象:方法调用成功。
- 空指针:方法调用失败。
### getLocalUser() [#getlocaluser]
virtual [ILocalUser](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-local-user)* agora::rtc::IRtcConnection::getLocalUser()
获取本地用户对象的指针。每个连接仅对应一个本地用户。
返回值
- [ILocalUser](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-local-user) 对象:方法调用成功。
- 空指针:方法调用失败。
### getRemoteUsers() [#getremoteusers]
virtual int agora::rtc::IRtcConnection::getRemoteUsers([UserList](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a46a0d0064b7c6713de256d37dc24b9ad) & *users*)
获取频道中全部远端用户的信息。
用户列表: [UserList](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a46a0d0064b7c6713de256d37dc24b9ad) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### getUserInfo() [#getuserinfo]
virtual int agora::rtc::IRtcConnection::getUserInfo([user_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora#a67aa7eac4d2b30c5c02951f1303bcc48) *userId*, [agora::UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1-user-info) & *userInfo*)
获取频道中指定远端用户的信息。
用户 ID。
用户信息: [UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1-user-info) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### registerObserver() [#registerobserver]
virtual int agora::rtc::IRtcConnection::registerObserver([IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) * *observer*, void(*)([IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) *) *safeDeleter* = `NULL`)
注册 RTC 连接 observer。你必须先创建 [`IRtcConnection`](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection) 对象。
[IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### unregisterObserver() [#unregisterobserver]
virtual int agora::rtc::IRtcConnection::unregisterObserver([IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) * *observer*)
销毁 RTC 连接 observer。
[IRtcConnectionObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection-observer) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### registerNetworkObserver() [#registernetworkobserver]
virtual int agora::rtc::IRtcConnection::registerNetworkObserver([INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-network-observer) * *observer*, void(*)([INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-network-observer) *) *safeDeleter* = `NULL`)
注册网络状态 observer。
[INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-network-observer) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### unregisterNetworkObserver() [#unregisternetworkobserver]
virtual int agora::rtc::IRtcConnection::unregisterNetworkObserver([INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-network-observer) * *observer*)
销毁网络状态 observer。
[INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-network-observer) 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### getConnId() [#getconnid]
virtual [conn_id_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#ab669d53cb37e3274112d7fba3eaa27d9) agora::rtc::IRtcConnection::getConnId()
获取连接 ID。
返回值
- 连接 ID: 方法调用成功。
- 空指针:方法调用失败。
### getTransportStats() [#gettransportstats]
virtual [RtcStats](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-rtc-stats) agora::rtc::IRtcConnection::getTransportStats()
获取 RTC 连接的传输状态。
返回值
- [RtcStats](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-rtc-stats):方法调用成功。
- 空指针:方法调用失败。
### getAgoraParameter() [#getagoraparameter]
virtual [agora::base::IAgoraParameter](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1base-1-1-i-agora-parameter)* agora::rtc::IRtcConnection::getAgoraParameter()
获取某个 Connection 中的 [IAgoraParameter](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1base-1-1-i-agora-parameter) 对象。
通过该方法获取的 `IAgoraParameter` 对象,设置仅对当前 Connection 有效。如需进行全局设置,改用 [IAgoraService::getAgoraParameter](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1base-1-1-i-agora-service#a1c707744b5e4f06467219a25ecaeccb7) 方法。
返回值
- `IAgoraParameter` 对象:方法调用成功。
- 空指针:方法调用失败。
### createDataStream() [#createdatastream]
virtual int agora::rtc::IRtcConnection::createDataStream(int * *streamId*, bool *reliable*, bool *ordered*, bool *sync*)
创建数据流。
每个用户在每个频道中最多只能创建 5 个数据流。
:::info[注解]
- 声网不支持你将 `reliable` 设为 `true` 且 `ordered` 设为 `false`。
- 当需要数据包立刻到达接收端时,不能将 `ordered` 参数设置为 `true`。
- 设置为与音频同步后,如果数据包的延迟在音频延迟的范围内,SDK 会在播放音频的同时触发与该音频包同步的 [onStreamMessage](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-local-user-observer#a0a0af52ad5ef54b08919df497b738f8b) 回调。 当需要数据包立刻到达接收端时,不能将 `sync` 参数设置为 `true`。声网推荐你仅在需要实现特殊场景,例如歌词同步时,设置为与音频同步。
:::
输出参数,数据流 ID。
该数据流是否可靠:
- `true`: 接收方 5 秒内会收到发送方所发送的数据。
- `false`: 接收方不保证收到,就算数据丢失也不会报错。
该数据流是否有序:
- `true`: 接收方会按照发送方发送的顺序收到数据包。
- `false`: 接收方不保证按照发送方发送的顺序收到数据包。
是否与本地发送的音频流同步:
- `true`: 数据流与音频流同步。
- `false`: 数据流与音频流不同步。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### sendStreamMessage() [#sendstreammessage]
virtual int agora::rtc::IRtcConnection::sendStreamMessage(int *streamId*, const char * *data*, size_t *length*)
发送数据流消息。
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 [onStreamMessage](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-local-user-observer#a0a0af52ad5ef54b08919df497b738f8b) 回调,远端用户可以在该回调中获取接收到的流消息。
:::info[注解]
- 请确保在调用该方法前,已调用 [createDataStream](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-rtc-connection#a53f87120cf152e9a80a64de9f0144ede) 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
:::
数据流 ID。可以通过 `createDataStream` 获取。
待发送的数据。
数据长度。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### enableEncryption() [#enableencryption]
virtual int agora::rtc::IRtcConnection::enableEncryption(bool *enabled*, const [EncryptionConfig](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-encryption-config) & *config*)
开启或关闭内置加密。
在安全要求较高的场景下,声网建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
:::info[注解]
- 如果开启了内置加密,则不能使用直推 CDN 功能。
:::
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-encryption-config) 。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### getUserInfoByUserAccount() [#getuserinfobyuseraccount]
virtual int agora::rtc::IRtcConnection::getUserInfoByUserAccount(const char * *userAccount*, [rtc::UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) * *userInfo*)
根据 user account(String 型用户 ID) 获取用户信息。
用户的 user account。
[UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象:
- 输入: 一个 [UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象。
- 输出: 一个 [UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象,包含 user account 和 user ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### getUserInfoByUid() [#getuserinfobyuid]
virtual int agora::rtc::IRtcConnection::getUserInfoByUid([uid_t](/zh-CN/api-reference/rtc-server-sdk/cpp/namespaceagora-1-1rtc#ab650539cb2bdcf8382d0aa32c6d70aa7) *uid*, [rtc::UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) * *userInfo*)
根据用户 ID 获取用户信息。
用户 ID
[UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象:
- 输入: 一个 [UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象。
- 输出: 一个 [UserInfo](/zh-CN/api-reference/rtc-server-sdk/cpp/structagora-1-1rtc-1-1-user-info) 对象,包含 user account 和 user ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。