网络及其他
介绍跟网络相关的方法以及其他方法和回调。
complain
投诉通话质量。
virtual int complain(const char* callId, const char* description) = 0;
详情
该方法允许用户就通话质量进行投诉。需要在离开频道后调用。
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- description
- (非必选项)通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 参数无效。
- -3:SDK 尚未准备好。可能的原因有:
- IRtcEngine 初始化失败。请重新初始化 IRtcEngine。
- 调用方法时用户尚未加入频道。请检查方法的调用逻辑。
- 调用 rate 或 complain 方法时用户尚未离开频道。请检查方法的调用逻辑。
- 请检查是否已开启音频模块。请检查程序集完整性。
createDataStream [1/2]
创建数据流。
virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;
详情
在 IRtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。离开频道时数据流会被销毁,如需使用需要重新创建数据流。
- 该方法需要在加入频道后调用。
- 不可将 reliable 设为
true
且将 ordered 设为false
。
参数
- streamId
- 输出参数,创建好的数据流 ID。
- reliable
-
该数据流是否可靠:
true
: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 onStreamMessageError 回调并获得相应报错信息。false
: 接收方不保证收到,就算数据丢失也不会报错。
- ordered
-
该数据流是否有序:
true
: 接收方会按照发送方发送的顺序收到数据包。false
: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 0: 创建数据流成功。
- < 0:方法调用失败。
createDataStream [2/2]
创建数据流。
virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0;
详情
该方法用于创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStream [1/2],该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- streamId
- 输出参数,创建好的数据流 ID。
- config
- 数据流设置。详见 DataStreamConfig。
返回值
- 0: 创建数据流成功。
- < 0:方法调用失败。
enableEncryption
开启或关闭内置加密。
virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0;
详情
在安全要求较高的场景下,建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。
enableExtension
启用/禁用插件。
virtual int enableExtension(
const char* provider, const char* extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
详情
如需调用本方法,请在初始化 IRtcEngine 对象后立即调用。
- 如果要开启多个插件,需要多次调用该方法。
- 不同插件在 SDK 中处理数据的顺序由插件的开通顺序决定。即先开启的插件会先处理数据。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- enable
-
是否启用插件:
true
: 启用插件。false
: 禁用插件。
- type
- 媒体资源类型。详见 MEDIA_SOURCE_TYPE。
注意: 在该方法中,该参数仅支持以下两种设置:
- 默认值为 UNKNOWN_MEDIA_SOURCE。
- 如果要使用第二个摄像头采集视频,将该参数设置为 SECONDARY_CAMERA_SOURCE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置或该动态库名是否正确。
enableWebSdkInteroperability
打开与 Web SDK 的互通(仅在直播场景适用)。
virtual int enableWebSdkInteroperability(bool enabled) = 0;
详情
- 弃用:
- 该方法已废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Web SDK 的互通:
true
: 打开互通。false
: (默认) 关闭互通。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getCallId
getErrorDescription
获取警告或错误描述。
virtual const char* getErrorDescription(int code) = 0;
参数
- code
- SDK 报告的错误码或警告码。
返回值
具体的错误或警告描述。
getExtensionProperty
获取插件的详细信息。
virtual int getExtensionProperty(
const char* provider, const char* extension,
const char* key, char* value, int buf_len, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
详情
参数
- provider
- 输出参数。提供插件的服务商名称。
- extension
- 输出参数。插件的名称。
- key
- 输出参数。插件属性的 Key。
- value
- 输出参数。插件属性 Key 对应的值。
- type
- 插件的媒体源类型。详见 MEDIA_SOURCE_TYPE。
- buf_len
- 插件属性 JSON 字符串的最大长度。最大值为 512 字节。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
getNetworkType
获取本地网络连接类型。
virtual int getNetworkType() = 0;
详情
- 自从
- v4.0.1
你可以在任何阶段通过该方法获取正在使用的网络类型。
返回值
- ≥ 0: 方法调用成功,返回本地网络连接类型。
- 0:网络连接已断开。
- 1:网络类型为 LAN。
- 2:网络类型为 Wi-Fi(包含热点)。
- 3:网络类型为 2G 移动网络。
- 4:网络类型为 3G 移动网络。
- 5:网络类型为 4G 移动网络。
- 6:网络类型为 5G 移动网络。
- < 0: 方法调用失败,返回错误码。
- -1:网络连接类型未知。
getNtpWallTimeInMs
获取当前的 NTP (网络时间协议) 时间。
virtual uint64_t getNtpWallTimeInMs() = 0;
详情
- 自从
- v4.2.0
在实时合唱的场景中,特别是在各个接收端由于网络原因导致下行链路不一致的情况下,你可以调用该方法来获取当前的 NTP 时间作为基准时间,以对齐多个接收端的歌词和音乐,实现合唱同步。
返回值
当前 NTP 时间的 Unix 时间戳 (毫秒)。
getUserInfoByUid
通过 UID 获取用户信息。
virtual int getUserInfoByUid(uid_t uid, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- uid
- 用户 ID。
- userInfo
- 输入和输出参数。标识用户的 UserInfo 对象:
- 输入值:一个 UserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
virtual int getUserInfoByUserAccount(const char* userAccount, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0;
详情
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- userAccount
- 用户 User Account。
- userInfo
- 输入和输出参数。标识用户的 UserInfo 对象:
- 输入值:一个 UserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
- channelId
- 频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- localUserAccount
- 本地用户的 User Account。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getVersion
获取 SDK 版本。
virtual const char* getVersion(int* build) = 0;
参数
- build
- 编译号。
返回值
当前的 SDK 版本号。格式为字符串。
loadExtensionProvider
将插件添加到 SDK 中。
virtual int loadExtensionProvider(const char* path, bool unload_after_use = false) = 0;
详情
参数
- path
- 插件的动态库路径和名称。例如:
/library/libagora_segmentation_extension.dll
。 - unload_after_use
- 是否在插件使用完毕后自动卸载:
true
: 当 IRtcEngine 销毁时自动卸载插件。false
: 不自动卸载插件,直到进程退出(推荐)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
queryInterface
获取指定接口类的指针。
virtual int queryInterface(INTERFACE_ID_TYPE iid, void** inter) = 0;
参数
- iid
- 想要获取的接口类 ID。详见 INTERFACE_ID_TYPE。
- inter
- 输出参数。指定接口的对象指针。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
rate
给通话评分。
virtual int rate(const char* callId,
int rating,
const char* description) = 0;
详情
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- rating
- 给通话的评分,最低 1 分,最高 5 分,如超过这个范围,SDK 会返回 -2(
ERR_INVALID_ARGUMENT
) 错误。 - description
- (非必选项)给通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(
ERR_INVALID_ARGUMENT
)。 - -3(
ERR_NOT_READY
)。
- -2(
registerExtension
注册插件。
virtual int registerExtension(const char* provider, const char* extension,
agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
详情
- 自从
- v4.1.0
加载插件后,你可以通过该方法注册插件。
该方法仅适用于 Windows。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- type
- 媒体资源类型。详见 MEDIA_SOURCE_TYPE。
注意: 在该方法中,该参数仅支持以下两种设置:
- 默认值为 UNKNOWN_MEDIA_SOURCE。
- 如果要使用第二个摄像头采集视频,将该参数设置为 SECONDARY_CAMERA_SOURCE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
registerLocalUserAccount
注册本地用户 User Account。
virtual int registerLocalUserAccount(const char* appId, const char* userAccount) = 0;
详情
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 onLocalUserRegistered 回调,告知本地用户的 UID 和 User Account。
- 先调用 registerLocalUserAccount 方法注册 Account,再调用 joinChannelWithUserAccount [2/2] 方法加入频道。
- 直接调用 joinChannelWithUserAccount [2/2] 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount [2/2] 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
- appId
- 你的项目在控制台注册的 App ID。
- userAccount
-
用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 NULL。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerPacketObserver
注册数据包观测器。
virtual int registerPacketObserver(IPacketObserver* observer) = 0;
详情
该方法注册数据包观测器 (Packet Observer)。在 SDK 发送/接收(语音、视频)网络包时,会回调 IPacketObserver 定义的接口,App 可用此接口对数据做处理,例如加解密。
- 处理后发送到网络的包大小不应超过 1200 字节,否则有可能发送失败。
- 若需调用此方法,需确保接收端和发送端都调用此方法,否则会出现未定义行为(例如音频无声或视频黑屏)。
- 若在直播场景下使用旁路推流、录制,不建议调用此方法。
- 你需要在加入频道前调用该方法。
参数
- observer
- IPacketObserver 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
sendCustomReportMessage
发送自定义上报消息。
virtual int sendCustomReportMessage(const char *id,
const char* category,
const char* event,
const char* label,
int value) = 0;
详情
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessage
发送数据流。
virtual int sendStreamMessage(int streamId,
const char* data,
size_t length) = 0;
详情
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 onStreamMessageError 回调。
- 请确保在调用该方法前,已调用 createDataStream [2/2] 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
参数
- streamId
- 数据流 ID。可以通过 createDataStream [2/2] 获取。
- data
- 待发送的数据。
- length
- 数据长度。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAVSyncSource
设置发流端音画同步。
virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0;
详情
同一用户可能使用两个设备分别发送音频流和视频流,为保证接收端听到和看到的音频和视频的时间同步性,你可以在视频发送端调用该方法,并传入音频发送端的频道名、用户 ID。 SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流,以保证即使在两个发送端的上行网络情况不一致(如分别使用 Wi-Fi 和 4G 网络)的情况下,也能让接收到的音视频具有时间同步性。
参数
- channelId
- 标识音频发送端所在频道的频道名。
- uid
- 音频发送端的用户 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setCloudProxy
设置云代理服务。
virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0;
详情
当用户的网络访问受到防火墙限制时,你需要将声网提供的 IP 和端口号添加到防火墙白名单,然后调用该方法开启云代理,并通过 proxyType 参数设置云代理类型。
成功连接云代理后,SDK 会触发 onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) 回调。
如果你想关闭已设置的 Force UDP 或 Force TCP 云代理,请调用 setCloudProxy (NONE_PROXY)
。
如果你想更改已设置的云代理类型,请先调用 setCloudProxy (NONE_PROXY)
,再调用 setCloudProxy 并传入你期望的 proxyType 值。
- 建议你在频道外调用该方法。
- 如果用户处于内网防火墙环境下,使用 Force UDP 云代理时,旁路推流和跨频道媒体流转发功能不可用。
- 使用 Force UDP 云代理时,调用 startAudioMixing [2/2] 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。
参数
- proxyType
-
云代理类型,详见 CLOUD_PROXY_TYPE。
该参数为必填参数,如果你不赋值,SDK 会报错。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 传入的参数无效。
- -7: SDK 尚未初始化。
setEncryptionMode
启用内置的加密方案。
virtual int setEncryptionMode(const char* encryptionMode) = 0;
详情
- 弃用:
- 请改用 enableEncryption 方法。
SDK 支持内置加密方案,默认支持 AES-128-GCM。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。
参数
- encryptionMode
-
加密模式:
- "
aes-128-xts
": 128 位 AES 加密,XTS 模式; - "
aes-128-ecb
": 128 位 AES 加密,ECB 模式; - "
aes-256-xts
": 256 位 AES 加密,XTS 模式; - "
sm4-128-ecb
": 128 位 SM4 加密,ECB 模式; - "
aes-128-gcm
": 128 位 AES 加密,GCM 模式; - "
aes-256-gcm
": 256 位 AES 加密,GCM 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-gcm
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionSecret
启用内置加密,并设置数据加密密码。
virtual int setEncryptionSecret(const char* secret) = 0;
详情
- 弃用:
- 请改用 enableEncryption 方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionProperty
设置插件的属性。
virtual int setExtensionProperty(
const char* provider, const char* extension,
const char* key, const char* value, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
详情
开启插件后,你可以调用该方法设置插件的属性。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
- type
- 媒体资源类型。详见 MEDIA_SOURCE_TYPE。
注意: 在该方法中,该参数仅支持以下两种设置:
- 默认值为 UNKNOWN_MEDIA_SOURCE。
- 如果要使用第二个摄像头采集视频,将该参数设置为 SECONDARY_CAMERA_SOURCE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionProviderProperty
设置插件服务商的属性。
virtual int setExtensionProviderProperty(
const char* provider, const char* key, const char* value) = 0;
详情
你可以调用该方法设置插件服务商的属性,并根据服务商的类型初始化相关参数。
该方法需要在 enableExtension 之后、且启用音频(enableAudio/enableLocalAudio)或启用视频(enableVideo/enableLocalVideo)之前调用。
参数
- provider
- 提供插件的服务商名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalAccessPoint
配置与声网私有媒体服务器 Native 接入模块的连接。
virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0;
详情
成功部署声网私有媒体服务器并在内网终端集成 RTC SDK v4.x 后,你可以调用该方法指定 Local Access Point,给 SDK 分配 Native 接入模块。
- 该方法仅在部署声网混合云方案后生效。你可以联系 sales@agora.io 了解和部署声网混合云。
- 该方法需要在加入频道前调用。
参数
- config
- Local Access Point 配置。详见 LocalAccessPointConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFile
设置日志文件
virtual int setLogFile(const char* filePath) = 0;
详情
- 弃用:
- 此方法已废弃,请改用 initialize 中的
logConfig
参数设置日志文件路径 。
设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。App 必须保证指定的目录存在而且可写。
如需调用本方法,请在调用 initialize 方法初始化 IRtcEngine 对象后立即调用,否则输出日志可能不完整。
参数
- filePath
- 日志文件的完整路径。该日志文件为 UTF-8 编码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFileSize
设置 SDK 输出的日志文件的大小。
virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0;
详情
- 弃用:
- 该方法已废弃,请改用 initialize 中的
logConfig
参数设置日志文件大小。
默认情况下,SDK 会生成 5 个 SDK 日志文件和 5 个 API 调用日志文件,规则如下:
- SDK 日志文件的名称分别为:
agorasdk.log
、agorasdk.1.log
、agorasdk.2.log
、agorasdk.3.log
、agorasdk.4.log
。 - API 调用日志文件的名称分别为:
agoraapi.log
、agoraapi.1.log
、agoraapi.2.log
、agoraapi.3.log
、agoraapi.4.log
。 - 每个 SDK 日志文件的默认大小为 1,024 KB;API 调用日志文件的默认大小为 2,048 KB。日志文件均为 UTF-8 编码。
- 最新的日志永远写在
agorasdk.log
和agoraapi.log
中。 - 当
agorasdk.log
写满后,SDK 会按照以下顺序对日志文件进行操作:- 删除
agorasdk.4.log
文件(如有)。 - 将
agorasdk.3.log
重命名为agorasdk.4.log
。 - 将
agorasdk.2.log
重命名为agorasdk.3.log
。 - 将
agorasdk.1.log
重命名为agorasdk.2.log
。 - 新建
agorasdk.log
文件。
- 删除
agoraapi.log
文件的覆盖规则与agorasdk.log
相同。
该方法仅用于设置 agorasdk.log
文件的大小,对agoraapi.log
不生效。
参数
- fileSizeInKBytes
- 单个
agorasdk.log
日志文件的大小,单位为 KB,取值范围为 [128,20480],默认值为 2,048 KB。如果你将fileSizeInKByte
设为小于 128 KB,SDK 会自动调整到 128 KB;如果你将fileSizeInKByte
设为大于 20,480 KB,SDK 会自动调整到 20,480 KB。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogFilter
设置日志输出等级。
virtual int setLogFilter(unsigned int filter) = 0;
详情
- 弃用:
- 请改用 initialize 中的 logConfig。
该方法设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 LOG_FILTER_OFF、LOG_FILTER_CRITICAL、LOG_FILTER_ERROR、LOG_FILTER_WARN、LOG_FILTER_INFO 和 LOG_FILTER_DEBUG。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 LOG_FILTER_WARN 级别,就可以看到在 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR 和 LOG_FILTER_WARN 级别的日志信息。
参数
- filter
-
日志过滤等级。详见 LOG_FILTER_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogLevel
设置 SDK 的日志输出级别。
virtual int setLogLevel(commons::LOG_LEVEL level) = 0;
详情
- 弃用:
- 该方法已经废弃。请改用 RtcEngineContext 设置日志输出级别。
选择一个级别,你就可以看到该级别的日志信息。
参数
- level
- 日志级别: LOG_LEVEL。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setParameters [1/2]
SDK 的 JSON 配置信息,用于提供技术预览或特别定制功能。
virtual int setParameters(const char* parameters) = 0;
- 自从
- v4.1.0
请联系技术支持获取 JSON 配置方式。
参数
- parameters
- JSON 字符串形式的参数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setParameters [2/2]
通过 JSON 配置 SDK 提供技术预览或特别定制功能。
virtual int setParameters(const char* parameters) = 0;
详情
请联系技术支持获取 JSON 配置方式。
参数
- parameters
- JSON 字符串形式的参数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startEchoTest [1/3]
开始语音通话回路测试。
virtual int startEchoTest() = 0;
详情
- 弃用:
- 该方法已废弃,请改用 startEchoTest [3/3]。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在 10 秒后回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest [1/3] 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest [2/3]
开始语音通话回路测试。
virtual int startEchoTest(int intervalInSeconds) = 0;
详情
- 弃用:
- 该方法自 v4.0.1 废弃,请改用 startEchoTest [3/3]。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest [2/3] 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
- intervalInSeconds
- 设置返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest [3/3]
开始音视频通话回路测试。
virtual int startEchoTest(const EchoTestConfiguration& config) = 0;
详情
为测试用户本地发流、收流是否正常,你可以调用该方法进行音视频通话回路测试,即测试系统的音视频设备和用户的上下行网络是否正常。
- 该方法在加入频道前后均可调用。在频道内调用时,需确保当前没有发布音视频流。
- 调用该方法后,必须调用 stopEchoTest 结束测试,否则该用户无法进行下一次音视频通话回路测试, 也无法加入频道。
- 直播场景下,该方法仅能由主播调用。
参数
- config
- 音视频通话回路测试的配置。详见 EchoTestConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startLastmileProbeTest
开始通话前网络质量探测。
virtual int startLastmileProbeTest(const LastmileProbeConfig& config) = 0;
详情
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- onLastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- onLastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 调用该方法后,在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 LastmileProbeConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEchoTest
停止语音通话回路测试。
virtual int stopEchoTest() = 0;
返回值
- 0: 方法调用成功。
-
< 0: 方法调用失败。
- -5(ERR_REFUSED): 停止测试失败,可能是测试不在运行中。
stopLastmileProbeTest
停止通话前网络质量探测。
virtual int stopLastmileProbeTest() = 0;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
onConnectionBanned
onConnectionInterrupted
网络连接中断回调。
virtual void onConnectionInterrupted() {}
- 弃用:
- 请改用 onConnectionStateChanged 回调。
- onConnectionInterrupted 回调一定是发生在成功加入频道后,且 SDK 刚失去和服务器连接超过 4 秒时触发。
- onConnectionLost 回调是无论是否成功加入频道,只要 10 秒内和服务器无法建立连接都会触发。
onConnectionLost
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
virtual void onConnectionLost()
SDK 在调用 joinChannel [2/2] 后,无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。
onConnectionStateChanged
网络连接状态已改变回调。
virtual void onConnectionStateChanged(CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason) { (void)state; (void)reason; }
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
参数
- state
-
当前网络连接状态。详见 CONNECTION_STATE_TYPE。
- reason
-
引起当前网络连接状态改变的原因。详见 CONNECTION_CHANGED_REASON_TYPE。
onEncryptionError
内置加密出错回调。
virtual void onEncryptionError(ENCRYPTION_ERROR_TYPE errorType) { (void)errorType; }
调用 enableEncryption 开启加密后, 如果发流端、收流端出现加解密出错,SDK 会触发该回调。
参数
- errorType
- 错误类型,详见 ENCRYPTION_ERROR_TYPE。
onExtensionError
插件出错回调。
virtual void onExtensionError(const char* provider, const char* extension, int error, const char* message) { (void)provider; (void)extension; (void)error; (void)message; }
当调用 enableExtension(
启用插件失败或者插件运行出错时, 插件会触发该回调并上报错误码和错误原因。true
)
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- error
- 错误码。详见插件服务商提供的插件文档。
- message
- 错误原因。详见插件服务商提供的插件文档。
onExtensionEvent
插件事件回调。
virtual void onExtensionEvent(const char* provider, const char* extension, const char* key, const char* value) { (void)provider; (void)extension; (void)key; (void)value; }
为监听插件事件,你需要注册该回调。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
onExtensionStarted
插件启用回调。
virtual void onExtensionStarted(const char* provider, const char* extension) { (void)provider; (void)extension; }
当调用 enableExtension(
启用插件成功时,插件会触发该回调。true
)
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件名称。
onExtensionStopped
插件禁用回调。
virtual void onExtensionStopped(const char* provider, const char* extension) { (void)provider; (void)extension; }
当调用 enableExtension(
禁用插件成功时,插件会触发该回调。false
)
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件名称。
onLastmileProbeResult
通话前网络上下行 Last mile 质量探测报告回调。
virtual void onLastmileProbeResult(const LastmileProbeResult& result) { (void)result; }
在调用 startLastmileProbeTest 之后,SDK 会在约 30 秒内返回该回调。
参数
- result
- 上下行 Last mile 质量探测结果。 详见: LastmileProbeResult。
onLastmileQuality
网络上下行 last mile 质量报告回调。
virtual void onLastmileQuality(int quality) { (void)quality; }
该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到声网边缘服务器的网络状态。
加入频道前,调用 startLastmileProbeTest 之后,SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。
参数
- quality
- Last mile 网络质量。详见 QUALITY_TYPE 。
onLocalUserRegistered
本地用户成功注册 User Account 回调。
virtual void onLocalUserRegistered(uid_t uid, const char* userAccount) { (void)uid; (void)userAccount; }
本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account,或调用 joinChannelWithUserAccount [2/2] 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
参数
- uid
- 本地用户的 ID。
- userAccount
- 本地用户的 User Account。
onNetworkQuality
通话中每个用户的网络上下行 last mile 质量报告回调。
virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { (void)uid; (void)txQuality; (void)rxQuality; }
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到声网边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
UNKNOWN
;用户不收流时,rxQuality 为 UNKNOWN
。参数
- uid
-
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。如果当 uid 为 0 时,返回的是本地用户的网络质量。
- txQuality
- 该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。 详见 QUALITY_TYPE。
- rxQuality
- 该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 QUALITY_TYPE。
onNetworkTypeChanged
本地网络类型发生改变回调。
virtual void onNetworkTypeChanged(NETWORK_TYPE type) { (void)type; }
本地网络连接类型发生改变时,SDK 会触发该回调,并在回调中明确当前的网络连接类型。你可以通过该回调获取正在使用的网络类型;当连接中断时,该回调能辨别引起中断的原因是网络切换还是网络条件不好。
参数
- type
-
本地网络连接类型。详见 NETWORK_TYPE。
onPermissionError
获取设备权限出错回调。
virtual void onPermissionError(PERMISSION_TYPE permissionType) { (void)permissionType; }
无法获取设备权限时,SDK 会触发该回调,报告哪个设备的权限无法获取。
参数
- permissionType
- 设备权限类型。详见 PERMISSION_TYPE。
onProxyConnected
代理连接状态回调。
virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { (void)channel; (void)uid; (void)proxyType; (void)localProxyIp; (void)elapsed; }
通过该回调你可以监听 SDK 连接代理的状态。例如,当用户调用 setCloudProxy 设置代理并成功加入频道后,SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 joinChannel [2/2] 到触发该回调经过的时间等。
参数
- channel
- 频道名称。
- uid
- 用户 ID
- proxyType
- 连接上的代理类型。详见 PROXY_TYPE。
- localProxyIp
- 预留参数,暂不支持。
- elapsed
- 从调用 joinChannel [2/2] 到 SDK 触发该回调的经过的时间(毫秒)。
onReceiveAudioPacket
本地用户收到音频包回调。
virtual bool onReceiveAudioPacket(Packet& packet) = 0;
参数
- packet
- 收到的音频包,详见 Packet 。
返回值
true
: 成功接收音频包。false
: 丢弃音频包。
onReceiveVideoPacket
本地用户收到视频包回调。
virtual bool onReceiveVideoPacket(Packet& packet) = 0;
参数
- packet
- 收到的视频包,详见 Packet 。
返回值
true
: 成功接收视频包。false
: 丢弃视频包。
onSendAudioPacket
已发送音频包回调。
virtual bool onSendAudioPacket(Packet& packet) = 0;
参数
- packet
- 发送的音频包,详见 Packet 。
返回值
true
: 成功发送音频包。false
: 丢弃音频包。
onSendVideoPacket
已发送视频包回调。
virtual bool onSendVideoPacket(Packet& packet) = 0;
参数
- packet
- 发送的视频包,详见 Packet 。
返回值
true
: 成功发送视频包;false
: 丢弃视频包。
onStreamMessage
接收到对方数据流消息的回调。
virtual void onStreamMessage(uid_t userId, int streamId, const char* data, size_t length, uint64_t sentTs) { (void)userId; (void)streamId; (void)data; (void)length; (void)sentTs; }
该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- userId
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- data
- 接收到的数据。
- length
- 数据长度,单位为字节。
- sentTs
- 数据流发出的时间。
onStreamMessageError
接收对方数据流消息发生错误的回调。
virtual void onStreamMessageError(uid_t userId, int streamId, int code, int missed, int cached) { (void)userId; (void)streamId; (void)code; (void)missed; (void)cached; }
该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- userId
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- code
- 发生错误的错误码。
- missed
- 丢失的消息数量。
- cached
- 数据流中断时,后面缓存的消息数量。
onUplinkNetworkInfoUpdated
上行网络信息变化回调。
virtual void onUplinkNetworkInfoUpdated(const UplinkNetworkInfo& info) { (void)info; }
只有当上行网络信息发生变化时,SDK 才会触发该回调。
参数
- info
- 上行网络信息,详见 UplinkNetworkInfo。