io.agora.rtc.AgoraRtcService类 参考
AgoraRtcService 类包含应用程序调用的所有方法。
成员函数说明
configLog()
createConnection()
native int io.agora.rtc.AgoraRtcService.createConnection | ( | ) |
创建 Connection。
你需要在加入频道前调用该方法创建 Connection。如需使用同一个用户 ID 加入不同频道,或者使用不同用户 ID 加入同一个频道,则你需要多次调用该方法创建多个 Connection,然后再使用对应的 Connection ID 加入频道。
返回值
destroyConnection()
native int io.agora.rtc.AgoraRtcService.destroyConnection | ( | int | connId | ) |
销毁 Connection。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
errToStr()
fini()
getConnectionInfo()
native int io.agora.rtc.AgoraRtcService.getConnectionInfo | ( | int | connId, |
ConnectionInfo | connInfo | ||
) |
获取 Connection 信息。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
connInfo | 连接信息。详见 ConnectionInfo。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
getRdtStatusInfo()
native int io.agora.rtc.AgoraRtcService.getRdtStatusInfo | ( | int | connId, |
int | remoteUid, | ||
RdtStatusInfo | info | ||
) |
获取 RDT 通道的信息。
该方法可以获取当前 RDT 通道的连接状态和缓冲区长度,从而判断远端用户是否成功接收 RDT 消息、本地用户是否可以继续发送 RDT 消息。例如,发送缓冲区长度 (sendQueueSize
) 为 0 表示远端用户已接收完 RDT 消息。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。 |
remoteUid | 远端用户的用户 ID。 |
info | RDT 通道的信息。详见 RdtStatusInfo 。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
getVersion()
init()
native int io.agora.rtc.AgoraRtcService.init | ( | String | appId, |
AgoraRtcEvents | events, | ||
RtcServiceOptions | options | ||
) |
初始化 SDK。
参数
参数名 | 描述 |
---|---|
appId | 声网为 App 开发者签发的 APP ID。 |
events | 用于处理 SDK 事件的一系列回调。 |
options | 服务配置选项,如果不需要设置则请置空。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
joinChannel()
native int io.agora.rtc.AgoraRtcService.joinChannel | ( | int | connId, |
String | channelName, | ||
int | uid, | ||
String | token, | ||
ChannelOptions | options | ||
) |
加入频道。
该方法让用户加入指定频道。同一个频道内使用相同 App ID 的用户可以互相传输数据。
- 你可以同时加入多个频道,所有你加入的频道都能接收到你发送的音视频数据。
- 如需使用同一个用户 ID 加入不同频道,或者使用不同用户 ID 加入同一个频道,则你需要创建不同的 Connection 并在调用
joinChannel
方法时填入对应的 Connection ID。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
channelName | 频道名,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
|
uid | 用户 ID。 |
token | 用于鉴权的 Token。
|
options | 频道设置选项。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
leaveChannel()
native int io.agora.rtc.AgoraRtcService.leaveChannel | ( | int | connId | ) |
退出频道。
停止在某频道传输数据后需要离开该频道。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
licenseGenCredential()
native String io.agora.rtc.AgoraRtcService.licenseGenCredential | ( | ) |
返回值
licenseVerify()
native int io.agora.rtc.AgoraRtcService.licenseVerify | ( | String | certificate, |
String | credential | ||
) |
- 弃用:
- 自 v1.9.0 废弃。改用 onLicenseValidationFailure 回调获取 License 校验失败的错误码。
认证 SDK。
参数
参数名 | 描述 |
---|---|
certificate | 许可证 Certificate。 |
credential | 凭证 Credential。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
loginRtm()
native int io.agora.rtc.AgoraRtcService.loginRtm | ( | String | rtmUid, |
String | rtmToken, | ||
AgoraRtmEvents | events | ||
) |
登录云信令 (原 RTM) 服务。
参数
参数名 | 描述 |
---|---|
rtmUid | 云信令 (原 RTM) 用户 ID。该字符串不可超过 64 字节。不可设为空、 NULL 或 "NULL" 。以下为支持的字符集范围:
|
rtmToken | 用于登录云信令 (原 RTM) 系统的动态密钥。详见《校验用户权限》。如果你没有开启 Token 鉴权,此参数可设为 NULL 。 |
events | 云信令 (原 RTM) 回调。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
logoutRtm()
muteLocalAudio()
native int io.agora.rtc.AgoraRtcService.muteLocalAudio | ( | int | connId, |
boolean | mute | ||
) |
暂停/恢复发送本地音频流。
可以先暂停向所有频道发送音频流,然后恢复向指定频道发送音频流。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
mute | 设置是否暂停/恢复发送本地音频流:
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalVideo()
native int io.agora.rtc.AgoraRtcService.muteLocalVideo | ( | int | connId, |
boolean | mute | ||
) |
暂停/恢复发送本地视频流。
可以先暂停向所有频道发送视频流,然后恢复向指定频道发送视频流。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
mute | 设置是否暂停/恢复发送本地视频流:
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteAudio()
native int io.agora.rtc.AgoraRtcService.muteRemoteAudio | ( | int | connId, |
int | remoteUid, | ||
boolean | mute | ||
) |
暂停/恢复接收指定频道内指定远端用户的音频流。
可以先暂停接收所有频道的音频流,然后恢复接收某个指定频道的音频流。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
remoteUid | 指定用户的用户 ID。设为 0 则停止接收频道内所有用户的音频流。 |
mute | 设置是否暂停/恢复接收远端音频流:
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteVideo()
native int io.agora.rtc.AgoraRtcService.muteRemoteVideo | ( | int | connId, |
int | uid, | ||
boolean | mute | ||
) |
暂停/恢复接收指定频道内指定远端用户的视频流。
可以先暂停接收所有频道的视频流,然后恢复接收指定频道的视频流。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
uid | 指定用户的用户 ID。设为 0 则停止接收频道内所有用户的视频流。 |
mute | 设置是否暂停/恢复接收远端视频流:
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
notifyNetworkEvent()
native int io.agora.rtc.AgoraRtcService.notifyNetworkEvent | ( | int | event | ) |
向 SDK 报告网络状态。
对于 Android 11 或更高版本,SDK 无法自动处理网络事件变更。你可以通过该方法向 SDK 报告网络状态。 SDK 会根据网络事件进行相应操作,例如尝试重新加入 RTC 频道和登录 RTM 系统。
参数
参数名 | 描述 |
---|---|
event | 网络事件,详见 NetworkEventType 。
|
renewToken()
native int io.agora.rtc.AgoraRtcService.renewToken | ( | int | connId, |
String | token | ||
) |
更新指定频道或全部频道的 Token。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
token | 新生成的 Token。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
requestVideoKeyFrame()
*native int io.agora.rtc.AgoraRtcService.requestVideoKeyFrame | ( | int | connId, |
int | remoteUid, | ||
int | streamType | ||
) |
请求指定远端用户尽快为指定远端视频流生成关键帧。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
remoteUid | 需要生成关键帧的用户 ID。如果为频道内的所有用户,则设为 0。 |
streamType | 需要生成关键帧的视频流类型。详见 VideoStreamType。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
sendAudioData()
native int io.agora.rtc.AgoraRtcService.sendAudioData | ( | int | connId, |
byte[] | data, | ||
AudioFrameInfo | info | ||
) |
向加入的频道发送音频帧。
频道内所有用户都能收到你发出的音频帧。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
data | 音频包数据。 |
info | 音频帧信息。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
sendRdtMsg()
native int io.agora.rtc.AgoraRtcService.sendRdtMsg | ( | int | connId, |
int | remoteUid, | ||
int | type, | ||
byte[] | msg | ||
) |
发送 RDT(Reliable Data Transmission,可靠数据传输)消息。
在文件传输、文件下载等需要可靠传输的场景中,你可以参考如下步骤发送 RDT 消息:
- 在 RDT 通道中建立连接:在加入频道时,将
ChannelOptions
中的autoConnectRdt
参数设置为true
,主动与频道内其他用户建立连接。 - 获取 RDT 通道的连接状态:监听
onRdtState
回调。当在 RDT 通道中成功建立连接时,连接状态会变为RDT_STATE_OPENED
,此时才可进行下一步。 - 调用
sendRdtMsg
方法发送 RDT 消息:你可以根据需要发送控制消息 (RDT_STREAM_CMD
) 或数据消息 (RDT_STREAM_DATA
),二者区别如下:
- 控制消息。发送优先级高,不受拥塞控制策略影响,不会阻塞发送。每秒至多发送 100 个消息包,每个消息包的长度至多为 256 B。
- 数据消息。发送优先级低,受拥塞控制策略影响,如果缓冲区满了,则消息会发送失败。不限制发送的消息包数量,每个消息包的长度至多为 128 KB。
成功发送 RDT 消息后,远端用户会收到 onRdtMsg
回调。你可以调用 getRdtStatusInfo
方法获取远端用户是否接收完消息等信息。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。 |
remoteUid | 远端用户的用户 ID。 |
type | RDT 消息类型。详见 RdtStreamType 。 |
msg | RDT 消息负载。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
RTC_ERR_RDT_USER_NOT_EXIST
(-8): 频道内不存在该远端用户。RTC_ERR_RDT_USER_NOT_READY
(-9): 未成功与远端用户建立连接。你需要等 RDT 通道的连接状态变为RDT_STATE_OPENED
后重新调用该方法。RTC_ERR_RDT_DATA_BLOCKED
(-10): 发送缓冲区已满。你需要等 RDT 通道的连接状态变为RDT_STATE_OPENED
后重新调用该方法。RTC_ERR_RDT_CMD_EXCEED_LIMIT
(-11): 控制消息的数量超过限制。每秒发送的控制消息包不能超过 100 个。
sendRtm()
native int io.agora.rtc.AgoraRtcService.sendRtm | ( | String | rtmUid, |
byte[] | message, | ||
int[] | messageId | ||
) |
通过云信令 (原 RTM) 服务发送消息。
RTM 默认开启基于 TLS 加密的传输层安全保护且不可关闭。
onRtmEvent
回调时才可以发送消息。发送频率不能超过每 3 秒 180 条。参数
参数名 | 描述 |
---|---|
rtmUid | 云信令 (原 RTM) 用户 ID。 |
message | 消息内容。仅支持 UTF-8 编码。消息长度至多为 31 KB。 |
messageId | 消息 ID。 |
返回值
- 0: 方法调用成功。
- <0: 方法调用失败。
RTM_ERR_NOT_LOGINED
(-1001): 未登录 RTM 系统RTM_ERR_SEND_TO_SELF
(-1002): 在rtmUid
参数中误填了自己的用户 ID。RTM_ERR_EXCEED_MSG_SIZE
(-1003): RTM 消息长度超出限制。消息长度至多为 31 KB。RTM_ERR_EXCEED_MSG_CNT
(-1004): 发送频率超出限制。每秒至多发送 60 条消息。RTM_ERR_EXCEED_TCP_SKB
(-1005): 消息通道已满。等待一秒后重新发送。
sendVideoData()
native int io.agora.rtc.AgoraRtcService.sendVideoData | ( | int | connId, |
byte[] | data, | ||
VideoFrameInfo | info | ||
) |
向加入的频道发送视频帧。
频道内所有用户都能收到你发出的视频帧。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
data | 视频包数据。 |
info | 视频帧信息。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setBweParam()
native int io.agora.rtc.AgoraRtcService.setBweParam | ( | int | connId, |
int | miniBps, | ||
int | maxBps, | ||
int | startBps | ||
) |
设置 bandwidth estimation (BWE) 参数。
参数
参数名 | 描述 |
---|---|
connId | Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 createConnection 创建 Connection。 |
miniBps | 最小码率,单位为 bps。 |
maxBps | 最大码率,单位为 bps。 |
startBps | 起始码率,单位为 bps。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。