# io.agora.rtc.AgoraRtcConn类 参考 (/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-rtc-conn)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
AgoraRtcConn 类,用于管理 SDK 与 RTC 频道之间的连接。
连接完成之后,你可以通过 AgoraLocalUser 对象在 RTC 频道中发送和接收媒体流。
连接频道是异步操作,你可以通过 IRtcConnObserver 对象监听连接状态变化和事件。 AgoraRtcConn 还可以监控频道中的远端用户是否加入或离开频道。
## 构造及析构函数说明 [#构造及析构函数说明]
### AgoraRtcConn() [#agorartcconn]
io.agora.rtc.AgoraRtcConn.AgoraRtcConn(long *cptr*)
构造函数。
## 成员函数说明 [#成员函数说明]
### connect() [#connect]
native int io.agora.rtc.AgoraRtcConn.connect(String *token*, String *chan_id*, String *user_id*)
连接 RTC 频道。
方法成功时,连接状态由 CONNECTION_STATE_DISCONNECTED(1) 变更为 CONNECTION_STATE_CONNECTING(2)。
根据连接是否成功,连接状态会变更为 CONNECTION_STATE_CONNECTED(3) 或 CONNECTION_STATE_FAILED(5)。SDK 会触发 onConnected 或 onDisconnected 提醒连接状态变更。
RTC token。
频道名。必须为字符串且长度不超过 64 字节。支持的字符类型包括:
- 全部小写字母: a to z
- 全部大写字母:A to Z
- 全部阿拉伯数字:0 to 9
- 空格
- 标点符号和其他特殊符号: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " \{", "\}", "|", "~", ","
本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 null, SDK 在 [onConnected](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#a4077abc157aa8be3c0060c97f394f48a) 回调中自动返回一个 user ID。你必须自行记录并管理此 ID。根据你在 initialize 方法中选择的用户 ID 类型,该参数支持的字符集也不同:
- int 型用户 ID 支持的字符集包括:
- 10 个数字 0-9
- String 型用户 ID 支持的字符集包括:
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " \{", "\}", "|", "~", ","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### createDataStream() [#createdatastream]
native int io.agora.rtc.AgoraRtcConn.createDataStream(Out *stream_id*, int *reliable*, int *ordered*)
创建数据流。
每个用户在每个频道中最多只能创建 5 个数据流。
:::info[注解]
- 声网不支持你将 reliable 设为 1 且 ordered 设为 0。
- 当需要数据包立刻到达接收端时,不能将 ordered 参数设置为 0。
:::
输出参数,数据流 ID。
该数据流是否可靠:
- 0: 接收方 5 秒内会收到发送方所发送的数据。
- 1: 接收方不保证收到,就算数据丢失也不会报错。
该数据流是否有序:
- 0: 接收方会按照发送方发送的顺序收到数据包。
- 1: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### destroy() [#destroy]
void io.agora.rtc.AgoraRtcConn.destroy()
析构函数。
### destroyConnInfo() [#destroyconninfo]
native void io.agora.rtc.AgoraRtcConn.destroyConnInfo([RtcConnInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-conn-info) *info*)
### destroyTransportStats() [#destroytransportstats]
native void io.agora.rtc.AgoraRtcConn.destroyTransportStats([RtcStats](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-stats) *stats*)
### destroyUserInfo() [#destroyuserinfo]
native void io.agora.rtc.AgoraRtcConn.destroyUserInfo([UserInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-user-info) *info*)
### disconnect() [#disconnect]
native int io.agora.rtc.AgoraRtcConn.disconnect()
与 RTC 频道断开连接。
SDK 与频道断开连接时,连接状态变更为 CONNECTION_STATE_DISCONNECTED(1)。你还可以通过 [onDisconnected](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#a356b9549fdb5034082a2847b668648c1) 回调得知。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### enableEncryption() [#enableencryption]
native int io.agora.rtc.AgoraRtcConn.enableEncryption(int *enabled*, [EncryptionConfig](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-encryption-config) *config*)
开启或关闭内置加密。
在安全要求较高的场景下,声网建议你在加入频道前,调用本方法开启内置加密。
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
配置内置加密模式和密钥。详见 [EncryptionConfig](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-encryption-config)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### getAgoraParameter() [#getagoraparameter]
native [AgoraParameter](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-parameter) io.agora.rtc.AgoraRtcConn.getAgoraParameter()
获取某个 Connection 中的 [AgoraParameter](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-parameter) 对象。
通过该方法获取的 AgoraParameter 对象,设置仅对当前 Connection 有效。如需进行全局设置,改用 [AgoraService.getAgoraParameter](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-service#af776ee9767ecb895b3e7aec2e38d1c0c) 方法。
返回值
- AgoraParameter 对象:方法调用成功。
- null:方法调用失败。
### getConnId() [#getconnid]
native int io.agora.rtc.AgoraRtcConn.getConnId()
获取连接 ID。
返回值
连接 ID。
### getConnInfo() [#getconninfo]
native [RtcConnInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-conn-info) io.agora.rtc.AgoraRtcConn.getConnInfo()
获取连接信息。
返回值
一个 [RtcConnInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-conn-info) 对象。
### getLocalUser() [#getlocaluser]
native [AgoraLocalUser](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-local-user) io.agora.rtc.AgoraRtcConn.getLocalUser()
获取 [AgoraLocalUser](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-local-user) 对象。
返回值
- [AgoraLocalUser](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-local-user) 对象:方法调用成功。
- 空指针:方法调用失败。
### getTransportStats() [#gettransportstats]
native [RtcStats](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-stats) io.agora.rtc.AgoraRtcConn.getTransportStats()
获取 RTC 连接的传输状态。
返回值
一个 [RtcStats](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-rtc-stats) 对象。
### getUserInfo() [#getuserinfo]
native [UserInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-user-info) io.agora.rtc.AgoraRtcConn.getUserInfo(String *user_id*)
获取频道中指定远端用户的信息。
用户 ID。
返回值
一个 [UserInfo](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-user-info) 对象,其中包含某一指定用户的有关信息。
### registerNetworkObserver() [#registernetworkobserver]
native int io.agora.rtc.AgoraRtcConn.registerNetworkObserver([INetworkObserver](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-network-observer) *observer*)
注册网络状态 observer。
INetworkObserver 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### registerObserver() [#registerobserver]
native int io.agora.rtc.AgoraRtcConn.registerObserver([IRtcConnObserver](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer) *observer*)
注册 RTC 连接 observer。你必须先创建 IRtcConnection 对象。
IRtcConnObserver 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### renewToken() [#renewtoken]
native int io.agora.rtc.AgoraRtcConn.renewToken(String *token*)
更新 Token。
Token 会在一定时间后过期。 当收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#a2e51cc9d7a69266ed6efdd2709b8bd26) 回调时,你必须从服务端生成一个新的 token,并使用该方法更新 Token。否则,SDK 会与频道断开连接。
新 Token。
### sendCustomReportMessage() [#sendcustomreportmessage]
native int io.agora.rtc.AgoraRtcConn.sendCustomReportMessage(String *id*, String *category*, String *event*, String *label*, int *value*)
发送自定义上报消息。
自定义事件的 ID。
自定义事件的类型。
需要上报的自定义事件。
自定义事件的标签。
自定义事件的值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### sendStreamMessage() [1/2] [#sendstreammessage-12]
native int io.agora.rtc.AgoraRtcConn.sendStreamMessage(int *stream_id*, String *data*, int *length*)
发送数据流消息。
:::error[弃用]
v4.4.32。请改用 [sendStreamMessage(int streamId, byte[] messageData)](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-rtc-conn#a1286a74a33789cc9777bf58a04f777c0) 。
:::
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 [onStreamMessage](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-local-user-observer#a24d008cf23fa8d07ff8d1600a14ccc53) 回调,远端用户可以在该回调中获取接收到的流消息。
:::info[注解]
- 请确保在调用该方法前,已调用 [createDataStream](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-rtc-conn#a9af79d071be59940c37dd2338fcdb67b) 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
:::
数据流 ID。可以通过 createDataStream 获取。
待发送的数据。
数据长度。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### sendStreamMessage() [2/2] [#sendstreammessage-22]
int io.agora.rtc.AgoraRtcConn.sendStreamMessage(int *streamId*, byte[] *messageData*)
发送数据流消息。
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 [onStreamMessage](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-local-user-observer#a24d008cf23fa8d07ff8d1600a14ccc53) 回调,远端用户可以在该回调中获取接收到的流消息。
:::info[注解]
- 请确保在调用该方法前,已调用 [createDataStream](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-agora-rtc-conn#a9af79d071be59940c37dd2338fcdb67b) 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
:::
数据流 ID。可以通过 createDataStream 获取。
待发送的数据。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### startLastmileProbeTest() [#startlastmileprobetest]
native int io.agora.rtc.AgoraRtcConn.startLastmileProbeTest([LastmileProbeConfig](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-lastmile-probe-config) *config*)
开始通话前网络质量探测。
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
启用该方法后,SDK 会依次返回如下 2 个回调:
- [onLastmileQuality](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#a879a97e08a9c3ad444a394ec2eca9c4a): 视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- [onLastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#ad174cd3a03ae31bf36b97eab3e82fe12): 视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
:::info[注解]
- 调用该方法后,在收到 [onLastmileQuality](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#a879a97e08a9c3ad444a394ec2eca9c4a) 和 [onLastmileProbeResult](/zh-CN/api-reference/rtc-server-sdk/java/interfaceio-1-1agora-1-1rtc-1-1-i-rtc-conn-observer#ad174cd3a03ae31bf36b97eab3e82fe12) 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
:::
Last mile 网络探测配置,详见 See [LastmileProbeConfig](/zh-CN/api-reference/rtc-server-sdk/java/classio-1-1agora-1-1rtc-1-1-lastmile-probe-config)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### stopLastmileProbeTest() [#stoplastmileprobetest]
native int io.agora.rtc.AgoraRtcConn.stopLastmileProbeTest()
停止通话前网络质量探测。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### unregisterNetworkObserver() [#unregisternetworkobserver]
native int io.agora.rtc.AgoraRtcConn.unregisterNetworkObserver()
释放 INetworkObserver 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
### unregisterObserver() [#unregisterobserver]
native int io.agora.rtc.AgoraRtcConn.unregisterObserver()
释放 IRtcConnObserver 对象。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
---
该类的文档由以下文件生成:
- AgoraRtcConn.java