agora::rtc::IRtcConnection类参考

abstract

IRtcConnection 类，用于管理 SDK 与 RTC 频道之间的连接。

连接完成之后，你可以通过 ILocalUser 对象在 RTC 频道中发送和接收媒体流。

连接频道是异步操作，你可以通过 IRtcConnectionObserver 对象监听连接状态变化和事件。IRtcConnection 还可以监控频道中的远端用户是否加入或离开频道。

构造及析构函数说明

~IRtcConnection()

agora::rtc::IRtcConnection::~IRtcConnection ( )

成员函数说明

connect()

virtual int agora::rtc::IRtcConnection::connect	(	const char *	token,
		const char *	channelId,
		user_id_t	userId
	)

连接 RTC 频道。

方法成功时，连接状态由 CONNECTION_STATE_DISCONNECTED(1) 变更为 CONNECTION_STATE_CONNECTING(2)。

根据连接是否成功，连接状态会变更为 CONNECTION_STATE_CONNECTED(3) 或 CONNECTION_STATE_FAILED(5)。 SDK 会触发 onConnected 或 onDisconnected 提醒连接状态变更。

参数

参数名	描述
token	RTC Token。详见使用 Token 鉴权。如果你的项目中未开启 App 证书，则仅需在该参数中填写你声网项目的 App ID。
channelId	频道名。必须为字符串且长度不超过 64 字节。支持的字符类型包括：全部小写字母： a to z 全部大写字母：A to Z 全部阿拉伯数字： 0 to 9 空格。标点符号和其他特殊符号： "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", ","
userId	本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 NULL，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(ERR_INVALID_ARGUMENT)：参数无效。
- -8(ERR_INVALID_STATE): 当前连接状态不是 CONNECTION_STATE_DISCONNECTED(1) 。

createDataStream()

virtual int agora::rtc::IRtcConnection::createDataStream	(	int *	streamId,
		bool	reliable,
		bool	ordered,
		bool	sync
	)

创建数据流。

每个用户在每个频道中最多只能创建 5 个数据流。

注解

声网不支持你将 reliable 设为 true 且 ordered 设为 false。
当需要数据包立刻到达接收端时，不能将 ordered 参数设置为 true。
设置为与音频同步后，如果数据包的延迟在音频延迟的范围内，SDK 会在播放音频的同时触发与该音频包同步的 onStreamMessage 回调。当需要数据包立刻到达接收端时，不能将 sync 参数设置为 true。声网推荐你仅在需要实现特殊场景，例如歌词同步时，设置为与音频同步。

参数

参数名	描述
streamId	输出参数，数据流 ID。
reliable	该数据流是否可靠： `true`: 接收方 5 秒内会收到发送方所发送的数据。 `false`: 接收方不保证收到，就算数据丢失也不会报错。
ordered	该数据流是否有序： `true`: 接收方会按照发送方发送的顺序收到数据包。 `false`: 接收方不保证按照发送方发送的顺序收到数据包。
sync	是否与本地发送的音频流同步： `true`: 数据流与音频流同步。 `false`: 数据流与音频流不同步。

返回值

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

disconnect()

virtual int agora::rtc::IRtcConnection::disconnect ( )

与 RTC 频道断开连接。

SDK 与频道断开连接时，连接状态变更为 CONNECTION_STATE_DISCONNECTED(1)。你还可以通过 onDisconnected 回调得知。

返回值

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

enableEncryption()

virtual int agora::rtc::IRtcConnection::enableEncryption	(	bool	enabled,
		const EncryptionConfig &	config
	)

开启或关闭内置加密。

在安全要求较高的场景下，声网建议你在加入频道前，调用本方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

注解

如果开启了内置加密，则不能使用直推 CDN 功能。

参数

参数名	描述
enabled	是否开启内置加密： true: 开启内置加密。 false: 关闭内置加密。
config	配置内置加密模式和密钥。详见 EncryptionConfig 。

返回值

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

getAgoraParameter()

virtual agora::base::IAgoraParameter * agora::rtc::IRtcConnection::getAgoraParameter ( )

获取某个 Connection 中的 IAgoraParameter 对象。

通过该方法获取的 IAgoraParameter 对象，设置仅对当前 Connection 有效。如需进行全局设置，改用 IAgoraService::getAgoraParameter 方法。

返回值

IAgoraParameter 对象：方法调用成功。
空指针：方法调用失败。

getConnectionInfo()

virtual TConnectionInfo agora::rtc::IRtcConnection::getConnectionInfo ( )

获取连接信息。

返回值

TConnectionInfo 对象：方法调用成功。
空指针：方法调用失败。

getConnId()

virtual conn_id_t agora::rtc::IRtcConnection::getConnId ( )

获取连接 ID。

返回值

连接 ID：方法调用成功。
空指针：方法调用失败。

getLocalUser()

virtual ILocalUser * agora::rtc::IRtcConnection::getLocalUser ( )

获取本地用户对象的指针。每个连接仅对应一个本地用户。

返回值

ILocalUser 对象：方法调用成功。
空指针：方法调用失败。

getRemoteUsers()

virtual int agora::rtc::IRtcConnection::getRemoteUsers ( UserList & users )

获取频道中全部远端用户的信息。

参数

参数名	描述
users [out]	用户列表： UserList 对象。

返回值

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

getTransportStats()

virtual RtcStats agora::rtc::IRtcConnection::getTransportStats ( )

获取 RTC 连接的传输状态。

返回值

RtcStats：方法调用成功。
空指针：方法调用失败。

getUserInfo()

virtual int agora::rtc::IRtcConnection::getUserInfo	(	user_id_t	userId,
		agora::UserInfo &	userInfo
	)

获取频道中指定远端用户的信息。

参数

参数名	描述
userId [in]	用户 ID。
userInfo [out]	用户信息： UserInfo 对象。

返回值

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

getUserInfoByUid()

virtual int agora::rtc::IRtcConnection::getUserInfoByUid	(	uid_t	uid,
		rtc::UserInfo *	userInfo
	)

根据用户 ID 获取用户信息。

参数

参数名	描述
uid	用户 ID
userInfo [in,out]	UserInfo 对象：输入: 一个 UserInfo 对象。输出: 一个 UserInfo 对象，包含 user account 和 user ID。

返回值

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

getUserInfoByUserAccount()

virtual int agora::rtc::IRtcConnection::getUserInfoByUserAccount	(	const char *	userAccount,
		rtc::UserInfo *	userInfo
	)

根据 user account（String 型用户 ID）获取用户信息。

参数

参数名	描述
userAccount	用户的 user account。
userInfo [in,out]	UserInfo 对象：输入: 一个 UserInfo 对象。输出: 一个 UserInfo 对象，包含 user account 和 user ID。

返回值

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

registerNetworkObserver()

virtual int agora::rtc::IRtcConnection::registerNetworkObserver	(	INetworkObserver *	observer,
		void()(INetworkObserver )	safeDeleter = `NULL`
	)

注册网络状态 observer。

参数

参数名	描述
observer	INetworkObserver 对象。

返回值

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

registerObserver()

virtual int agora::rtc::IRtcConnection::registerObserver	(	IRtcConnectionObserver *	observer,
		void()(IRtcConnectionObserver )	safeDeleter = `NULL`
	)

参数

参数名	描述
observer	IRtcConnectionObserver 对象。

返回值

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

renewToken()

virtual int agora::rtc::IRtcConnection::renewToken ( const char * token )

更新 Token。

Token 会在一定时间后过期。

当收到 onTokenPrivilegeWillExpire 回调时，你必须从服务端生成一个新的 token，并使用该方法更新 Token。否则，SDK 会与频道断开连接。

参数

参数名	描述
token	新 Token。

sendStreamMessage()

virtual int agora::rtc::IRtcConnection::sendStreamMessage	(	int	streamId,
		const char *	data,
		size_t	length
	)

发送数据流消息。

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

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

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

注解

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

参数

参数名	描述
streamId	数据流 ID。可以通过 `createDataStream` 获取。
data	待发送的数据。
length	数据长度。

返回值

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

startLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::startLastmileProbeTest ( const LastmileProbeConfig & config )

开始通话前网络质量探测。

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后，SDK 会依次返回如下 2 个回调：

onLastmileQuality: 视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
onLastmileProbeResult: 视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。
注解
调用该方法后，在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

参数

参数名	描述
config	Last mile 网络探测配置，详见 LastmileProbeConfig 。

返回值

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

stopLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::stopLastmileProbeTest ( )

停止通话前网络质量探测。

返回值

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

unregisterNetworkObserver()

virtual int agora::rtc::IRtcConnection::unregisterNetworkObserver ( INetworkObserver * observer )

销毁网络状态 observer。

参数

参数名	描述
observer	INetworkObserver 对象。

返回值

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

unregisterObserver()

virtual int agora::rtc::IRtcConnection::unregisterObserver ( IRtcConnectionObserver * observer )

销毁 RTC 连接 observer。

参数

参数名	描述
observer	IRtcConnectionObserver 对象。

返回值

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

构造及析构函数说明​

~IRtcConnection()

成员函数说明​

connect()

参数​

返回值​

createDataStream()

参数​

返回值​

disconnect()

返回值​

enableEncryption()

参数​

返回值​

getAgoraParameter()

返回值​

getConnectionInfo()

返回值​

getConnId()

返回值​

getLocalUser()

返回值​

getRemoteUsers()

参数​

返回值​

getTransportStats()

返回值​

getUserInfo()

参数​

返回值​

getUserInfoByUid()

参数​

返回值​

getUserInfoByUserAccount()

参数​

返回值​

registerNetworkObserver()

参数​

返回值​

registerObserver()

参数​

返回值​

renewToken()

参数​

sendStreamMessage()

参数​

返回值​

startLastmileProbeTest()

参数​

返回值​

stopLastmileProbeTest()

返回值​

unregisterNetworkObserver()

参数​

返回值​

unregisterObserver()

参数​

返回值​

构造及析构函数说明

成员函数说明

参数

返回值

参数

返回值

返回值

参数

返回值

返回值

返回值

返回值

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值