# RtcConnection 类 (/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
`RtcConnection` 类，用于管理 SDK 与 RTC 频道之间的连接。连接完成之后，你可以通过 `LocalUser` 对象在 RTC 频道中发送和接收媒体流。连接频道是异步操作，你可以通过 [`RtcConnectionObserver`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go) 对象监听连接状态变化和事件。`RtcConnection` 还可以监控频道中的远端用户是否加入或离开频道。
## NewRtcConnection [#newrtcconnection]
```go
func NewRtcConnection(cfg *RtcConnectionConfig) *RtcConnection {
cCfg := CRtcConnectionConfig(cfg)
defer FreeCRtcConnectionConfig(cCfg)
ret := &RtcConnection{
cConnection: C.agora_rtc_conn_create(agoraService.service, cCfg),
handler: nil,
localUserObserver: nil,
audioObserver: nil,
videoObserver: nil,
remoteVideoRWMutex: &sync.RWMutex{},
remoteEncodedVideoReceivers: make(map[*VideoEncodedImageReceiver]*videoEncodedImageReceiverInner),
}
ret.localUser = &LocalUser{
connection: ret,
cLocalUser: C.agora_rtc_conn_get_local_user(ret.cConnection),
}
ret.parameter = &AgoraParameter{
cParameter: C.agora_rtc_conn_get_agora_parameter(ret.cConnection),
}
agoraService.connectionRWMutex.Lock()
agoraService.consByCCon[ret.cConnection] = ret
agoraService.consByCLocalUser[ret.localUser.cLocalUser] = ret
agoraService.connectionRWMutex.Unlock()
return ret
}
```
创建一个 RTC 连接对象。
#### 参数 [#参数]
| 参数 | 描述 |
|---------------|----------------------------------------------------------------------|
| `cfg` | RTC 连接配置。详见 [`RtcConnectionConfig`](/zh-CN/api-reference/rtc-server-sdk/go-api/apidatatype.go#rtcconnconfig)。 |
#### 返回值 [#返回值]
- `RtcConnection` 对象: 方法调用成功。
- `nil`: 方法调用失败。
## Connect [#connect]
```go
func (conn *RtcConnection) Connect(token string, channel string, uid string) int {
if conn.cConnection == nil {
return -1
}
conn.connInfo.ChannelId = channel
conn.connInfo.LocalUserId = uid
uidInt, _ := strconv.Atoi(uid)
conn.connInfo.InternalUid = uint(uidInt)
cChannel := C.CString(channel)
cToken := C.CString(token)
cUid := C.CString(uid)
defer C.free(unsafe.Pointer(cChannel))
defer C.free(unsafe.Pointer(cToken))
defer C.free(unsafe.Pointer(cUid))
return int(C.agora_rtc_conn_connect(conn.cConnection, cToken, cChannel, cUid))
}
```
连接 RTC 频道。
方法成功时，连接状态由 `true` 变更为 `2`。
根据连接是否成功，连接状态会变更为 `3` 或 `5`。SDK 会触发 [`OnConnected`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go#onconnected) 或 [`on_disconnected`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go#ondisconnected) 提醒连接状态变更。
#### 参数 [#参数-1]
| 参数 | 描述 |
| --- | --- |
| `token` | RTC Token。详见 [使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 |
| `channel` | [rtcconnection-go-html-0-2-1 details](#table-slot-rtcconnection-go-html-0-2-1) |
| `uid` | [rtcconnection-go-html-0-3-1 details](#table-slot-rtcconnection-go-html-0-3-1) |
**rtcconnection-go-html-0-2-1 details**
频道名。必须为字符串且长度不超过 64 字节。支持的字符类型包括：
- 全部小写字母：a 到 z
- 全部大写字母：A 到 Z
- 全部阿拉伯数字：0 到 9
- 空格
- 标点符号和其他特殊符号：`!`、`#`、`$`、`%`、`&`、`(`、`)`、`+`、`-`、`:`、`;`、`<`、`=`、`.`、`>`、`?`、`@`、`[`、`]`、`^`、`_`、` {`、`}`、`|`、`~`、`,`
**rtcconnection-go-html-0-3-1 details**
本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 nil，SDK 在 `OnConnected` 回调中自动返回一个 user ID。你必须自行记录并管理此 ID。根据你在 [`Initialize`](/zh-CN/api-reference/rtc-server-sdk/go-api/agoraservice.go#initialize) 方法中选择的用户 ID 类型，该参数支持的字符集也不同：
- int 型用户 ID 支持的字符集包括：
- 10 个数字 0-9
- String 型用户 ID 支持的字符集包括：
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- `!`、`#`、`$`、`%`、`&`、`(`、`)`、`+`、`-`、`:`、`;`、`<`、`=`、`.`、`>`、`?`、`@`、`[`、`]`、`^`、`_`、` {`、`}`、`|`、`~`、`,`
#### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。
- `-2`: 参数无效。
- `-8`: 当前连接状态不是 `true`。
## Disconnect [#disconnect]
```go
func (conn *RtcConnection) Disconnect() int {
if conn.cConnection == nil {
return -1
}
return int(C.agora_rtc_conn_disconnect(conn.cConnection))
}
```
与 RTC 频道断开连接。SDK 与频道断开连接时，连接状态变更为 `true`。你还可以通过 [`OnDisconnected`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go#ondisconnected) 回调得知。
#### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## RenewToken [#renewtoken]
```go
func (conn *RtcConnection) RenewToken(token string) int {
if conn.cConnection == nil {
return -1
}
cToken := C.CString(token)
defer C.free(unsafe.Pointer(cToken))
return int(C.agora_rtc_conn_renew_token(conn.cConnection, cToken))
}
```
更新 Token。Token 会在一定时间后过期。当收到 [`OnTokenPrivilegeWillExpire`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go#ontokenprivilegewillexpire) 回调时，你必须从服务端生成一个新的 Token，并使用该方法更新 Token。否则，SDK 会与频道断开连接。
#### 参数 [#参数-2]
| 参数 | 描述 |
|------------|------------|
| `token` | 新 Token。|
#### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## CreateDataStream [#createdatastream]
```go
func (conn *RtcConnection) CreateDataStream(reliable bool, ordered bool) (int, int) {
if conn.cConnection == nil {
return -1, -1
}
// int* stream_id, int reliable, int ordered
cStreamId := C.int(-1)
ret := int(C.agora_rtc_conn_create_data_stream(conn.cConnection, &cStreamId, CIntFromBool(reliable), CIntFromBool(ordered)))
return int(cStreamId), ret
}
```
创建数据流。
:::info[自从]
v2.2.0 起新增。
:::
在 Connection 生命周期内，每个用户最多可以创建五条数据流。离开 Connection 时数据流会被销毁，如需使用需要重新创建数据流。
将 `reliable` 设置为 `true` 后，如果接收方 5 秒没有收到发送方所发送的数据，会触发 [`OnStreamMessageError`](/zh-CN/api-reference/rtc-server-sdk/go-api/localuserobserver.go) 回调并获得相应报错信息。
#### 参数 [#参数-3]
| 参数 | 描述 |
| --- | --- |
| `reliable` | [rtcconnection-go-html-1-1-1 details](#table-slot-rtcconnection-go-html-1-1-1) |
| `ordered` | [rtcconnection-go-html-1-2-1 details](#table-slot-rtcconnection-go-html-1-2-1) |
**rtcconnection-go-html-1-1-1 details**
是否保证数据可靠性，即接收方是否需要在数据发送后的 5 秒内接收：
- `true`: 是。SDK 提供有限度的可靠保证，在发送后的 5 秒内会有丢包检测和重传。
- `false`: 否。SDK 不做丢包检测和重传。
:::warning[注意]
SDK 仅支持将 `reliable` 和 `ordered` 同时设为 `true` 或 `false`。
:::
**rtcconnection-go-html-1-2-1 details**
是否保证接收方需要收到有序的数据流：
- `true`: 接收方按照发送方发送的顺序收到数据流。
- `false`: 接收方不保证按照发送方发送的顺序收到数据流。
#### 返回值 [#返回值-4]
- 创建的数据流的 ID：方法调用成功。
- < 0：方法调用失败。
## SendStreamMessage [#sendstreammessage]
```go
func (conn *RtcConnection) SendStreamMessage(streamId int, msg []byte) int {
if conn.cConnection == nil {
return -1
}
cMsg := C.CBytes(msg)
defer C.free(cMsg)
return int(C.agora_rtc_conn_send_stream_message(conn.cConnection, C.int(streamId), (*C.char)(cMsg), C.uint32_t(len(msg))))
}
```
发送数据流消息。
:::info[自从]
v2.2.0 起新增。
:::
调用 [`createDataStream`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go#createdatastream) 创建数据流后，你可以调用该方法向频道内所有用户发送数据流消息。
:::warning[注意]
SDK 对该方法的实现进行了如下限制：
- 频道内每个客户端最多可以同时拥有 5 个数据通道，所有数据通道共用的总发包码率限制为 30 KB/s。
- 每个数据通道每秒最多能发送 60 个包，每个包最大为 1 KB。
:::
成功调用该方法后，远端会触发 [`OnStreamMessage`](/zh-CN/api-reference/rtc-server-sdk/go-api/localuserobserver.go#onstreammessage) 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 [`OnStreamMessageError`](/zh-CN/api-reference/rtc-server-sdk/go-api/localuserobserver.go) 回调。
#### 参数 [#参数-4]
| 参数 | 描述 |
| ---- | ---- |
| `streamId` | 数据流 ID，可以通过 [`CreateDataStream`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go#createdatastream) 获取。 |
| `msg` | 待发送的消息数据。 |
#### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## RegisterObserver [#registerobserver]
```go
func (conn *RtcConnection) RegisterObserver(handler *RtcConnectionObserver) int {
if conn.cConnection == nil || handler == nil {
return -1
}
conn.handler = handler
if conn.cHandler == nil {
conn.cHandler = CRtcConnectionObserver()
C.agora_rtc_conn_register_observer(conn.cConnection, conn.cHandler)
}
return 0
}
```
注册 RTC 连接 observer。
#### 参数 [#参数-5]
| 参数 | 描述 |
|----------------|------------|
| `handler`| [`RtcConnectionObserver`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnectionobserver.go) 对象。|
#### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## UnregisterObserver [#unregisterobserver]
```go
func (conn *RtcConnection) UnregisterObserver() int {
conn.handler = nil
return 0
}
```
销毁 RTC 连接 observer。
#### 返回值 [#返回值-7]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## CreateDataStream [#createdatastream-1]
```go
func (conn *RtcConnection) CreateDataStream(reliable bool, ordered bool) (int, int) {
if conn.cConnection == nil {
return -1, -1
}
cStreamId := C.int(-1)
ret := int(C.agora_rtc_conn_create_data_stream(conn.cConnection, &cStreamId, CIntFromBool(reliable), CIntFromBool(ordered)))
return int(cStreamId), ret
}
```
创建数据流。
每个用户在每个频道中最多只能创建 5 个数据流。
:::warning[注意]
- 声网不支持你将 `reliable` 设为 `true` 且 `ordered` 设为 `false`。
- 当需要数据包立刻到达接收端时，不能将 `ordered` 参数设置为 `true`。
:::
#### 参数 [#参数-6]
| 参数 | 描述 |
| --- | --- |
| `reliable` | [rtcconnection-go-html-2-1-1 details](#table-slot-rtcconnection-go-html-2-1-1) |
| `ordered` | [rtcconnection-go-html-2-2-1 details](#table-slot-rtcconnection-go-html-2-2-1) |
**rtcconnection-go-html-2-1-1 details**
该数据流是否可靠：
- `true`: 接收方 5 秒内会收到发送方所发送的数据。
- `0`: 接收方不保证收到，就算数据丢失也不会报错。
**rtcconnection-go-html-2-2-1 details**
该数据流是否有序：
- `true`: 接收方会按照发送方发送的顺序收到数据包。
- `0`: 接收方不保证按照发送方发送的顺序收到数据包。
#### 返回值 [#返回值-8]
- `stream_id`：方法调用成功，返回数据流 ID。
- `nil`：方法调用失败。
## EnableEncryption [#enableencryption]
```go
func (conn *RtcConnection) EnableEncryption(enable int, config *EncryptionConfig);
```
开启加密功能。
该方法需要在 [`Connect`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go#connect) 之前调用。你需要在该方法中设置加密模式和具体的加密配置。
#### 参数 [#参数-7]
| 参数 | 描述 |
| --- | --- |
| `enable` | [rtcconnection-go-html-3-1-1 details](#table-slot-rtcconnection-go-html-3-1-1) |
| `config` | 具体的加密配置项：[`EncryptionConfig`](/zh-CN/api-reference/rtc-server-sdk/go-api/apidatatype.go#encryptionconfig)。 |
**rtcconnection-go-html-3-1-1 details**
是否开启加密功能。
- `1`：开启
- `0`：不开启
#### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## SendStreamMessage [#sendstreammessage-1]
```go
func (conn *RtcConnection) SendStreamMessage(streamId int, msg []byte) int {
if conn.cConnection == nil {
return -1
}
cMsg := C.CBytes(msg)
defer C.free(cMsg)
return int(C.agora_rtc_conn_send_stream_message(conn.cConnection, C.int(streamId), (*C.char)(cMsg), C.uint32_t(len(msg))))
}
```
发送数据流消息。
该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：
- 频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后，远端会触发 [`on_stream_message`](/zh-CN/api-reference/rtc-server-sdk/go-api/localuserobserver.go#onstreammessage) 回调，远端用户可以在该回调中获取接收到的流消息。
:::warning[注意]
- 请确保在调用该方法前，已调用 [`create_data_stream`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go#createdatastream) 创建了数据通道。
- 直播场景下，该方法仅适用于主播用户。
:::
#### 参数 [#参数-8]
| 参数 | 描述 |
|-------------|------------|
| `stream_id` | 数据流 ID。可以通过 [`CreateDataStream`](/zh-CN/api-reference/rtc-server-sdk/go-api/rtcconnection.go#createdatastream) 获取。|
| `data` | 待发送的数据。|
#### 返回值 [#返回值-10]
- 0: 方法调用成功。
- < 0: 方法调用失败。
## GetAgoraParameter [#getagoraparameter]
```go
func (conn *RtcConnection) GetAgoraParameter() *AgoraParameter {
return conn.parameter
}
```
获取 `AgoraParameter` 对象。
#### 返回值 [#返回值-11]
- `AgoraParameter` 对象：方法调用成功。
- `nil`：方法调用失败。
## GetLocalUser [#getlocaluser]
```go
func (conn *RtcConnection) GetLocalUser() *LocalUser {
return conn.localUser
}
```
获取 `LocalUser` 对象。每个连接仅对应一个本地用户。
#### 返回值 [#返回值-12]
- `LocalUser` 对象：方法调用成功。
- `nil`：方法调用失败。
## Release [#release]
```go
func (conn *RtcConnection) Release() {
if conn.cConnection == nil {
return
}
agoraService.connectionRWMutex.Lock()
delete(agoraService.consByCCon, conn.cConnection)
delete(agoraService.consByCLocalUser, conn.localUser.cLocalUser)
if conn.cVideoObserver != nil {
delete(agoraService.consByCVideoObserver, conn.cVideoObserver)
}
agoraService.connectionRWMutex.Unlock()
encodedVideoReceiversInners := make([]*videoEncodedImageReceiverInner, 0, 10)
conn.remoteVideoRWMutex.RLock()
for _, receiverInner := range conn.remoteEncodedVideoReceivers {
encodedVideoReceiversInners = append(encodedVideoReceiversInners, receiverInner)
}
conn.remoteVideoRWMutex.RUnlock()
agoraService.remoteVideoRWMutex.Lock()
for _, receiverInner := range encodedVideoReceiversInners {
delete(agoraService.remoteEncodedVideoReceivers, receiverInner.cReceiver)
}
agoraService.remoteVideoRWMutex.Unlock()
localUser := conn.localUser
if conn.cAudioObserver != nil {
C.agora_local_user_unregister_audio_frame_observer(localUser.cLocalUser)
}
if conn.cVideoObserver != nil {
C.agora_local_user_unregister_video_frame_observer(localUser.cLocalUser, conn.cVideoObserver)
}
if conn.cLocalUserObserver != nil {
C.agora_local_user_unregister_observer(localUser.cLocalUser)
}
if conn.cHandler != nil {
C.agora_rtc_conn_unregister_observer(conn.cConnection)
}
C.agora_rtc_conn_destroy(conn.cConnection)
conn.remoteVideoRWMutex.Lock()
conn.remoteEncodedVideoReceivers = make(map[*VideoEncodedImageReceiver]*videoEncodedImageReceiverInner)
conn.remoteVideoRWMutex.Unlock()
for _, receiverInner := range encodedVideoReceiversInners {
receiverInner.release()
}
encodedVideoReceiversInners = nil
conn.cConnection = nil
if conn.cAudioObserver != nil {
FreeCAudioFrameObserver(conn.cAudioObserver)
conn.cAudioObserver = nil
}
if conn.cVideoObserver != nil {
FreeCVideoFrameObserver(conn.cVideoObserver)
conn.cVideoObserver = nil
}
if conn.cLocalUserObserver != nil {
FreeCLocalUserObserver(conn.cLocalUserObserver)
conn.cLocalUserObserver = nil
}
if conn.cHandler != nil {
FreeCRtcConnectionObserver(conn.cHandler)
conn.cHandler = nil
}
conn.parameter = nil
conn.localUser = nil
localUser.connection = nil
localUser.cLocalUser = nil
localUser = nil
conn.handler = nil
conn.localUserObserver = nil
conn.audioObserver = nil
conn.videoObserver = nil
}
```
释放 RTC 连接。