需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

RtcConnection 类

  • Go

更新时间不可用

RtcConnection 类，用于管理 SDK 与 RTC 频道之间的连接。连接完成之后，你可以通过 LocalUser 对象在 RTC 频道中发送和接收媒体流。连接频道是异步操作，你可以通过 RtcConnectionObserver 对象监听连接状态变化和事件。RtcConnection 还可以监控频道中的远端用户是否加入或离开频道。

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 连接对象。

参数

参数描述
cfgRTC 连接配置。详见 RtcConnectionConfig。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • RtcConnection 对象: 方法调用成功。
  • nil: 方法调用失败。

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 或 on_disconnected 提醒连接状态变更。

参数

参数描述
tokenRTC Token。详见 使用 Token 鉴权。
channel

频道名。必须为字符串且长度不超过 64 字节。支持的字符类型包括：

  • 全部小写字母：a 到 z
  • 全部大写字母：A 到 Z
  • 全部阿拉伯数字：0 到 9
  • 空格
  • 标点符号和其他特殊符号：!、#、$、%、&、(、)、+、-、:、;、<、=、.、>、?、@、[、]、^、_、 {、}、|、~、,
uid

本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 nil，SDK 在 OnConnected 回调中自动返回一个 user ID。你必须自行记录并管理此 ID。根据你在 Initialize 方法中选择的用户 ID 类型，该参数支持的字符集也不同：

  • int 型用户 ID 支持的字符集包括：
    • 10 个数字 0-9
  • String 型用户 ID 支持的字符集包括：
    • 26 个小写英文字母 a-z
    • 26 个大写英文字母 A-Z
    • 10 个数字 0-9
    • 空格
    • !、#、$、%、&、(、)、+、-、:、;、<、=、.、>、?、@、[、]、^、_、 {、}、|、~、,
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。
    • -2: 参数无效。
    • -8: 当前连接状态不是 true。

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 回调得知。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

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 回调时，你必须从服务端生成一个新的 Token，并使用该方法更新 Token。否则，SDK 会与频道断开连接。

参数

参数描述
token新 Token。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

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
}

创建数据流。

自从

v2.2.0 起新增。

在 Connection 生命周期内，每个用户最多可以创建五条数据流。离开 Connection 时数据流会被销毁，如需使用需要重新创建数据流。

将 reliable 设置为 true 后，如果接收方 5 秒没有收到发送方所发送的数据，会触发 OnStreamMessageError 回调并获得相应报错信息。

参数

参数描述
reliable

是否保证数据可靠性，即接收方是否需要在数据发送后的 5 秒内接收：

  • true: 是。SDK 提供有限度的可靠保证，在发送后的 5 秒内会有丢包检测和重传。
  • false: 否。SDK 不做丢包检测和重传。

注意

SDK 仅支持将 reliable 和 ordered 同时设为 true 或 false。

ordered

是否保证接收方需要收到有序的数据流：

  • true: 接收方按照发送方发送的顺序收到数据流。
  • false: 接收方不保证按照发送方发送的顺序收到数据流。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 创建的数据流的 ID：方法调用成功。
  • < 0：方法调用失败。

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))))
}

发送数据流消息。

自从

v2.2.0 起新增。

调用 createDataStream 创建数据流后，你可以调用该方法向频道内所有用户发送数据流消息。

注意

SDK 对该方法的实现进行了如下限制：

  • 频道内每个客户端最多可以同时拥有 5 个数据通道，所有数据通道共用的总发包码率限制为 30 KB/s。
  • 每个数据通道每秒最多能发送 60 个包，每个包最大为 1 KB。

成功调用该方法后，远端会触发 OnStreamMessage 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 OnStreamMessageError 回调。

参数

参数描述
streamId数据流 ID，可以通过 CreateDataStream 获取。
msg待发送的消息数据。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

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。

参数

参数描述
handlerRtcConnectionObserver 对象。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

UnregisterObserver

Go
func (conn *RtcConnection) UnregisterObserver() int {
    conn.handler = nil
    return 0
}
销毁 RTC 连接 observer。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

CreateDataStream

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 个数据流。

注意

  • 声网不支持你将 reliable 设为 true 且 ordered 设为 false。
  • 当需要数据包立刻到达接收端时，不能将 ordered 参数设置为 true。

参数

参数描述
reliable

该数据流是否可靠：

  • true: 接收方 5 秒内会收到发送方所发送的数据。
  • 0: 接收方不保证收到，就算数据丢失也不会报错。
ordered

该数据流是否有序：

  • true: 接收方会按照发送方发送的顺序收到数据包。
  • 0: 接收方不保证按照发送方发送的顺序收到数据包。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • stream_id：方法调用成功，返回数据流 ID。
  • nil：方法调用失败。

EnableEncryption

Go
func (conn *RtcConnection) EnableEncryption(enable int, config *EncryptionConfig);

开启加密功能。

该方法需要在 Connect 之前调用。你需要在该方法中设置加密模式和具体的加密配置。

参数

参数描述
enable

是否开启加密功能。

  • 1：开启
  • 0：不开启
config具体的加密配置项：EncryptionConfig。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

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))))
}

发送数据流消息。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：

  • 频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
  • 每个客户端每秒最多能发送 6 KB 数据。
  • 频道内每人最多能同时有 5 个数据通道。

成功调用该方法后，远端会触发 on_stream_message 回调，远端用户可以在该回调中获取接收到的流消息。

注意

  • 请确保在调用该方法前，已调用 create_data_stream 创建了数据通道。
  • 直播场景下，该方法仅适用于主播用户。

参数

参数描述
stream_id数据流 ID。可以通过 CreateDataStream 获取。
data待发送的数据。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

GetAgoraParameter

Go
func (conn *RtcConnection) GetAgoraParameter() *AgoraParameter {
    return conn.parameter
}
获取 AgoraParameter 对象。

返回值

  • AgoraParameter 对象：方法调用成功。
  • nil：方法调用失败。

GetLocalUser

Go
func (conn *RtcConnection) GetLocalUser() *LocalUser {
    return conn.localUser
}
获取 LocalUser 对象。每个连接仅对应一个本地用户。

返回值

  • LocalUser 对象：方法调用成功。
  • nil：方法调用失败。

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 连接。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利