网络状况
本章节介绍有关网络状况的功能。针对网络状况,网易云信提供了网络探测和网络状况回调这两个功能。 网络探测是一个辅助的网络情况测试工具,可以探测音视频通话网络的连通性、丢包率和延迟等信息。目前支持选择音频通话和视频通话这两种通话模式的探测,视频通话的网络探测支持选择相应的清晰度进行探测。另外,网络探测会占用网络带宽资源,建议在通话开始之前使用以免影响通话质量。 网络状况回调是通话过程中,SDK定时会通知上层当前的网络状况。值得注意的是,这个网络状况是基于当前的实际通话情况的。比如,当前正进行的是音频通话,上报的网络情况是良好,那只是说明当前的网络情况可以很好地满足音频通话,并不能说明当前进行视频通话也会很流畅。
网络探测
该接口提供用户进行udp的网络探测。本接口是通话前探测,通话过程中使用通话中的网络状态回调,不建议频繁使用此接口。
API原型
C++
static uint64_t static void NetDetect(NetDetectCallback cb)
static uint64_t NetDetectEx(int32_t ms_limit, nim::NIMNetDetectType type, nim::NIMNetDetectVideoQuality quality_type, NetDetectCallback cb)
File:nim_cpp_vchat.h
Namespace:NIM
Class:VChat
C#
public static ulong DetectNetwork(NIMVChatNetDetectJsonEx json, nim_vchat_opt_cb_func cb)
Namespace:NIM
Class:VChatAPI
C
uint64_t nim_vchat_net_detect(const char json_extension, nim_vchat_opt_cb_func cb, const void user_data)
File:nim_vchat.h
参数说明
- 网络探测接口参数
参数 | 类型 | 说明 |
---|---|---|
room_name | string | 房间名 |
createRoomInfo(c#) | Json | Json string 扩展 填写期望的时间限制及探测类型 |
json_extension | string | Json string 扩展,见网络探测扩展参数 |
cb | function | 回调函数 |
user_data | void* | 无效扩展 |
- 网络探测扩展参数
键常量名 | 键常量值 | 值类型 | 说明 |
---|---|---|---|
kNIMNetDetectAppKey | app_key | string | 用户的app key |
kNIMNetDetectTimeLimit | time | int32 | 毫秒级的探测时长限制 |
kNIMNetDetectType | type | int32 | 探测类型NIMNetDetectType |
kNIMNetDetectQualityType | quality_type | int32 | kNIMNetDetectTypeVideo时有效,默认为0,视频探测类型NIMNetDetectVideoQuality |
- 网络探测回调扩展参数
键常量名 | 键常量值 | 值类型 | 说明 |
---|---|---|---|
kNIMNetDetectTaskId | task_id | uint64 | 任务id |
kNIMNetDetectLoss | loss | int | 丢包率百分比 |
kNIMNetDetectRttmax | rttmax | int | rtt 最大值 |
kNIMNetDetectRttmin | rttmin | int | rtt 最小值 |
kNIMNetDetectRttavg | rttavg | int | rtt 平均值 |
kNIMNetDetectRttmdev | rttmdev | int | rtt 偏差值 mdev |
kNIMNetDetectDetail | detailinfo | string | 扩展信息 |
- NIMNetDetectType探测类型
枚举定义 | 值 | 说明 |
---|---|---|
kNIMNetDetectTypeAudio | 0 | 默认值,音频探测 |
kNIMNetDetectTypeVideo | 1 | 视频探测 |
- NIMNetDetectVideoQuality视频探测类型
枚举定义 | 值 | 说明 |
---|---|---|
kNIMNDVideoQualityDefault | 0 | 探测模拟视频数据480P |
kNIMNDVideoQualityLow | 1 | 探测模拟视频数据176*144 |
kNIMNDVideoQualityMedium | 2 | 探测模拟视频数据352*288 |
kNIMNDVideoQualityHigh | 3 | 探测模拟视频数据480*320 |
kNIMNDVideoQuality480p | 4 | 探测模拟视频数据640*480 |
kNIMNDVideoQuality720p | 5 | 探测模拟视频数据1280*720 |
kNIMNDVideoQuality540p | 6 | 探测模拟视频数据960*540 |
返回值说明
返回探测任务id。
- 回调错误码
值 | 说明 |
---|---|
200 | 成功 |
0 | 流程错误 |
400 | 非法请求格式 |
417 | 请求数据不对 |
606 | ip为内网ip |
607 | 频率超限 |
20001 | 探测类型错误 |
20002 | ip错误 |
20003 | sock错误 |
示例
C++
void NetDetectCallback(int, NetDetectCbInfo) { //... } void foo() { nim::VChat::NetDetect(&NetDetectCallback);//音频默认探测 nim::VChat::NetDetectEx(0, nim::kNIMNetDetectTypeVideo, nim::kNIMNDVideoQualityDefault, &NetDetectCallback);//扩展视频探测 }
C#
private void OnNetDetection(bool ret, int code, string json_extension, IntPtr user_data)
{
DemoTrace.WriteLine(string.Format("网络测试:{0} code = {1},result = {2}", ret, code, json_extension));
}
void foo()
{
NIMVChatNetDetectJsonEx json;
NIM.VChatAPI.DetectNetwork(json, OnNetDetection);
}
C
static void CallbackNetDetect(bool ret, int rescode, const char *json_params, const void *user_data) { if (ret) { Json::Reader reader; Json::Value values; if (reader.parse(PCharToString(json_params), values) && values.isObject()) { int loss = values[kNIMNetDetectLoss].asInt(); int rtt_max = values[kNIMNetDetectRttmax].asInt(); int rtt_min = values[kNIMNetDetectRttmin].asInt(); int rtt_avg = values[kNIMNetDetectRttavg].asInt(); int rtt_mdev = values[kNIMNetDetectRttmdev].asInt(); std::string expand_info = values[kNIMNetDetectDetail].asString(); } } } typedef void(*nim_vchat_net_detect)(const char *json_extension, nim_vchat_opt_cb_func cb, const void *user_data); void foo() { nim_vchat_net_detect func = (nim_vchat_net_detect) GetProcAddress(hInst, "nim_vchat_net_detect"); Json::FastWriter fs; Json::Value value; value[nim::kNIMNetDetectTimeLimit] = 5000;//可选,如果有超时要求的可以填上超时时间限制 value[nim::kNIMNetDetectType] = kNIMVChatVideoQualitySuper;//分辨率 value[nim::kNIMNetDetectQualityType] = kNIMVChatVideoQualitySuper;// std::string json_value = fs.write(value); func(json_value.c_str(), &CallbackNetDetect, NULL); }
特殊说明
在返回的字段中,loss、rttavg、rttmdev这三个值最能反应当前客户端的实际网络情况。由这三个值可以计算出当前的网络状况指数:
网络状况指数 = (loss/20)*50% +(rttavg/1200)*25% +(rttmdev/150)*25%
经过我们的反复测试,现提供三个网络状况指数节点
网络状况指数节点 | loss(%) | rttavg(ms) | rttmdev(ms) | 网络状况指数 |
---|---|---|---|---|
A | 3 | 500 | 50 | 0.2625 |
B | 10 | 800 | 80 | 0.55 |
C | 20 | 1200 | 150 | 1 |
备注:
当网络状况指数≤0.2625时,网络状况非常好,音视频通话流畅;
当0.2625<网络状况指数≤0.55时,网络状况好,音视频通话偶有卡顿;
当0.55<网络状况指数≤1时,网络状况差,音频通话流畅;
当网络状况指数>1时,网络状况非常差,音频通话偶有卡顿。
当前通话网络状况回调
API介绍
该回调会在通话过程中实时返回通话成员的网络状态。
API原型
C#
NIMVChatSessionStatus.onSessionNetStatus
public delegate void onSessionNetStatusHandler(long channel_id, int status, string uid)
Namespace:NIM
Class:VChatAPI
C++/C
typedef void (*nim_vchat_cb_func)(enum NIMVideoChatSessionType type, int64 channel_id, int code, const char *json_extension, const void *user_data)
NIMVideoChatSessionType::kNIMVideoChatSessionTypeNetStatus
File:nim_vchat_def.h
参数说明
- C#
参数 | 类型 | 说明 |
---|---|---|
channel_id | long | 频道id |
status | int | 状态码见NIMVideoChatSessionNetStat |
- C++/C
参数 | 类型 | 说明 |
---|---|---|
type | enum | 回调类型kNIMVideoChatSessionTypeNetStatus |
channel_id | int64 | 频道id |
code | int | 错误码NIMVideoChatSessionNetStat |
json_extension | string | Json string 扩展,返回kNIMVChatUid |
user_data | void* | 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- NIMVideoChatSessionNetStat
枚举定义 | 值 | 说明 |
---|---|---|
kNIMVChatNetStatusVideoClose | -1 | 网络状态极差,视频强制关闭 |
kNIMVideoChatSessionNetStatGood | 0 | 网络状态好 |
kNIMVideoChatSessionNetStatPoor | 1 | 网络状态较差 |
kNIMVideoChatSessionNetStatBad | 2 | 网络状态很差 |
示例
C#
private static void OnSessionNetStatus(long channel_id, int status,string uid) { DemoTrace.WriteLine("SessionNetStatus channel_id:" + channel_id.ToString() + " status:" + status.ToString() + " uid:" + uid); }
C++/C
void VChatCb(nim::NIMVideoChatSessionType type, __int64 channel_id, int code, const char *json, const void*) { switch (type) { case nim::kNIMVideoChatSessionTypeNetStatus:{ Json::Value valus; Json::Reader reader; if (reader.parse(json, valus)) { std::string uid = valus[nim::kNIMVChatUid].asString(); code;//网络状态 } }break; //··· } }
特殊说明
网络状态返回中,会返回所有成员的网络状态变化情况,其中可以根据扩展字段解析出对应的成员uid。针对网络状态,本人状态一般指本人上行网络情况,他人的网络状态指本地接收对方数据的下行网络情况。