agora::rtc::IRtcConnection类 参考
- C++
更新时间不可用
继承自 agora::RefCountInterface.
详细描述
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 字节。支持的字符类型包括：
|
userId | 本地用户 ID。长度不超过 64 字节。如果你不设置用户 ID 或设为 NULL，SDK 在 onConnected 回调中自动返回一个 user ID。 你必须自行记录并管理此 ID。根据你在 initialize 方法中选择的用户 ID 类型，该参数支持的字符集也不同：
|
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。
- -2(ERR_INVALID_ARGUMENT)：参数无效。
- -8(ERR_INVALID_STATE): 当前连接状态不是 CONNECTION_STATE_DISCONNECTED(1)。
disconnect()
virtual int agora::rtc::IRtcConnection::disconnect()与 RTC 频道断开连接。
SDK 与频道断开连接时，连接状态变更为 CONNECTION_STATE_DISCONNECTED(1)。你还可以通过 onDisconnected 回调得知。
返回值
- 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: 方法调用失败。
renewToken()
virtual int agora::rtc::IRtcConnection::renewToken(const char * token)更新 Token。
Token 会在一定时间后过期。
当收到 onTokenPrivilegeWillExpire 回调时，你必须从服务端生成一个新的 token，并使用该方法更新 Token。否则，SDK 会与频道断开连接。
| 参数名 | 描述 |
|---|---|
token | 新 Token。 |
getConnectionInfo()
virtual TConnectionInfo agora::rtc::IRtcConnection::getConnectionInfo()获取连接信息。
返回值
- TConnectionInfo 对象：方法调用成功。
- 空指针：方法调用失败。
getLocalUser()
virtual ILocalUser* agora::rtc::IRtcConnection::getLocalUser()获取本地用户对象的指针。每个连接仅对应一个本地用户。
返回值
- ILocalUser 对象：方法调用成功。
- 空指针：方法调用失败。
getRemoteUsers()
virtual int agora::rtc::IRtcConnection::getRemoteUsers(UserList & users)获取频道中全部远端用户的信息。
| 参数名 | 描述 |
|---|---|
users | 用户列表： UserList 对象。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfo()
virtual int agora::rtc::IRtcConnection::getUserInfo(user_id_t userId, agora::UserInfo & userInfo)获取频道中指定远端用户的信息。
| 参数名 | 描述 |
|---|---|
userId | 用户 ID。 |
userInfo | 用户信息： UserInfo 对象。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerObserver()
virtual int agora::rtc::IRtcConnection::registerObserver(IRtcConnectionObserver * observer, void(*)(IRtcConnectionObserver *) safeDeleter = NULL)注册 RTC 连接 observer。你必须先创建 IRtcConnection 对象。
| 参数名 | 描述 |
|---|---|
observer |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterObserver()
virtual int agora::rtc::IRtcConnection::unregisterObserver(IRtcConnectionObserver * observer)销毁 RTC 连接 observer。
| 参数名 | 描述 |
|---|---|
observer |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerNetworkObserver()
virtual int agora::rtc::IRtcConnection::registerNetworkObserver(INetworkObserver * observer, void(*)(INetworkObserver *) safeDeleter = NULL)注册网络状态 observer。
| 参数名 | 描述 |
|---|---|
observer | INetworkObserver 对象。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterNetworkObserver()
virtual int agora::rtc::IRtcConnection::unregisterNetworkObserver(INetworkObserver * observer)销毁网络状态 observer。
| 参数名 | 描述 |
|---|---|
observer | INetworkObserver 对象。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getConnId()
virtual conn_id_t agora::rtc::IRtcConnection::getConnId()获取连接 ID。
返回值
- 连接 ID： 方法调用成功。
- 空指针：方法调用失败。
getTransportStats()
virtual RtcStats agora::rtc::IRtcConnection::getTransportStats()获取 RTC 连接的传输状态。
返回值
- RtcStats：方法调用成功。
- 空指针：方法调用失败。
getAgoraParameter()
virtual agora::base::IAgoraParameter* agora::rtc::IRtcConnection::getAgoraParameter()获取某个 Connection 中的 IAgoraParameter 对象。
通过该方法获取的 IAgoraParameter 对象，设置仅对当前 Connection 有效。如需进行全局设置，改用 IAgoraService::getAgoraParameter 方法。
返回值
IAgoraParameter对象：方法调用成功。- 空指针：方法调用失败。
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 | 该数据流是否可靠：
|
ordered | 该数据流是否有序：
|
sync | 是否与本地发送的音频流同步：
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
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。可以通过 |
data | 待发送的数据。 |
length | 数据长度。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableEncryption()
virtual int agora::rtc::IRtcConnection::enableEncryption(bool enabled, const EncryptionConfig & config)开启或关闭内置加密。
在安全要求较高的场景下，声网建议你在加入频道前，调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。
注解
- 如果开启了内置加密，则不能使用直推 CDN 功能。
| 参数名 | 描述 |
|---|---|
enabled | 是否开启内置加密：
|
config | 配置内置加密模式和密钥。详见 EncryptionConfig 。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoByUserAccount()
virtual int agora::rtc::IRtcConnection::getUserInfoByUserAccount(const char * userAccount, rtc::UserInfo * userInfo)根据 user account（String 型用户 ID） 获取用户信息。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoByUid()
virtual int agora::rtc::IRtcConnection::getUserInfoByUid(uid_t uid, rtc::UserInfo * userInfo)根据用户 ID 获取用户信息。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。