网络探测

即对客户端设备进行网络诊断以获设备的网络状况，可以通过以下类、接口来设置 ICMPPing 、TCPPing 、MTR 等任务进行获取。当应用在后台时，触发网络探测任务将不执行。

网络探测类

类名	说明
NBSTaskCondition	网络探测任务执行条件类
NBSDiagnosisTask	网络探测任务基类
TCPPingDiagnosisTask	TCPPing 网络探测任务类
ICMPPingDiagnosisTask	ICMPPing 网络探测类
MTRDiagnosisTask	MTR 网络探测类
DownloadDiagnosisTask	Download网络探测类

NBSTaskCondition

网络探测任务执行条件类，用于创建网络探测任务条件;可以设置场景、执行域名、错误码等属性。

接口

@interface NBSTaskCondition : NSObject<NBSSerializable>
NBS_NO_INIT
  
/**
* 触发场景:如网络错误后触发
*/
@property (nonatomic, assign) NBSDiagnosisTaskScene scene;

/**
* 当网络请求完成或出错时，uri只有符合patternDomain中的才会执行，不设置则默认不受此限制
*/
@property (nonatomic, strong) NSArray <NSString *>*patternDomains;

/**
* 包含在patternErrorCodes中的请求错误才会执行，不设置则默认不受此限制
*/
@property (nonatomic, strong) NSArray <NSNumber *>*patternErrorCodes;

- (instancetype)initWithScene:(NBSDiagnosisTaskScene)scene;

@end

示例

 NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"]; //请求出错码
// 901 - 未知主机错误
// 902 - 建联失败错误
// 903 - 请求超时错误
// 906 - 非法响应内容错误
// 908 - SSL证书校验错误
NSArray *patternErrorCode = @[@404,@502,@902,@903];
// 示例1， 创建请求错误后的condition //创建一个场景为NBSDiagnosisTaskSceneAfterNetError的condition
NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetError]; //设置condition执行条件域名、uri(只支持?前的uri)等「可配制通配符*，如 『*qq.com、 qq.com*、*qq.com*』;但不支持只设置*」;若不设置，则不受限制 
condition.patternDomains = domainArray;
//设置触发错误条件:设置触发405、502、建联失败、请求超时错误时执行网络探测任务「若不设置 patternErrorCodes，则所有请求错误都满足触发条件」
condition.patternErrorCodes = patternErrorCode;

//示例2， 创建请求结束后的condition //创建一个场景为NBSDiagnosisTaskSceneAfterNetFinished的condition
NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetFinished]; 
//设置condition执行条件域名、uri(只支持?前的uri)等「可配制通配符*，如 『*qq.com、 qq.com*、*qq.com*』;但不支持只设置*」;若不设置，则不受限制 
condition.patternDomains = domainArray;

NBSDiagnosisTask

网络探测任务基类，可以设置网络执行条件、任务执行频率等属性。

@interface NBSDiagnosisTask : NSObject<NBSSerializable>
/**
* 主机地址
*/
@property (nonatomic, copy) NSString *host;

/**
* 匹配条件 
*/
@property (nonatomic, strong) NBSTaskCondition *condition;

/**
* 执行间隔，默认60秒，即60秒内相同任务最多执行一次 
*/
@property (nonatomic, assign) NSInteger execFrequency;
@end

TCPPingDiagnosisTask

TCPPing 网络探测任务类，用于创建 TCPPing 网络探测任务。

接口

 @interface NBSTCPPingDiagnosisTask : NBSDiagnosisTask
 NBS_NO_INIT

 /**
 * 端口 
 */
 @property (nonatomic ,assign) NSInteger port;
 
 /**
 * 一次tcpping任务重复的次数，默认3次
 */
 @property (nonatomic, assign) NSInteger repeat;
 
 + (instancetype)tcppingTaskWithName:(NSString *)name
                               host:(NSString *)host
                               port:(NSInteger)port;
                               
 + (instancetype)tcppingTaskWithName:(NSString *)name
                               host:(NSString *)host
                               port:(NSInteger)port
                               condition:(nullable NBSTaskCondition *)condition;
 @end

示例

任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

 //创建一个带condition条件的tcpPing 任务(任务名为tcpPing_task，执行域名和端口分别为 www.baidu.com:443 )
 // name⻓度限制为 64，超出则截取。
 NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];
 
 //创建一个不带condition条件的tcpPing 任务(任务名为tcpPing_task，执行域名和端口分别为 www.baidu.com、443 )
 // name⻓度限制为 64，超出则截取。
 NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443];
 
 //一次tcpPing任务ping的次数，默认为 3次;可根据需求设置「范围为 3 - 100」
 tcpPing.repeat = 5;
 
 //tcpPing任务执行频率，，默认 60s ; 可根据需要设置「范围 > 1」;「注: startDiagnosisTask接口添加的任务不受该配置影响」
 tcpPing.execFrequency = 30;
 

ICMPPingDiagnosisTask

ICMPPing 网络探测类，用于创建 ICMPPing 网络探测任务。

接口

@interface NBSICMPPingDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT

/**
* 一次icmpping任务重复的次数，默认3次
*/
@property (nonatomic, assign) NSInteger repeat;

+ (instancetype)icmppingTaskWithName:(NSString *)name
                                host:(NSString *)host;
                                
+ (instancetype)icmppingTaskWithName:(NSString *)name
                                host:(NSString *)host
                                condition:(nullable NBSTaskCondition *)condition;
@end

示例

任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

//创建一个带condition条件的icmpPing 任务(任务名为icmpPing_task，执行域名为 www.baidu.com )
// name⻓度限制为 64，超出则截取。
NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];

//创建一个不带condition条件的icmpPing 任务(任务名为icmpPing_task，执行域名为 www.baidu.com )
// name⻓度限制为 64，超出则截取。
NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com"];

//一次icmpPing任务ping的次数，默认为 3次;可根据需求设置「范围为 3 - 100」 
icmpPing.repeat = 5;

//icmpPing任务执行频率，，默认 60s ; 可根据需要设置「范围 > 1」;「注: startDiagnosisTask接口添加的任务不受该配置影响」 
icmpPing.execFrequency = 30;

MTRDiagnosisTask

MTR 网络探测类，用于创建 MTR 网络探测任务。

接口

@interface NBSMTRDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT
  
+ (instancetype)mtrTaskWithName:(NSString *)name
                           host:(NSString *)host;
                           
+ (instancetype)mtrTaskWithName:(NSString *)name
                           host:(NSString *)host
                           condition:(nullable NBSTaskCondition *)condition;
@end

示例

任务完整示例「任务创建到添加任务队列」⻅「立即执行」或「循环执行」。

//创建一个带condition条件的 MTR 任务(任务名为mtr_task，执行域名为www.baidu.com ) // name⻓度限制为 64，超出则截取。
NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com" condition:condition];

//创建一个不带condition条件的 MTR 任务(任务名为mtr_task，执行域名为www.baidu.com ) // name⻓度限制为 64，超出则截取。
NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com"];

//MTR 任务执行频率，，默认 60s ; 可根据需要设置「范围 > 1」;「注:startDiagnosisTask接 口添加的任务不受该配置影响」
mtr.execFrequency = 30;

DownloadDiagnosisTask

Download 网络探测类，用于创建 Download 网络探测任务「 Download 网络探测任务只支持立即执行，即只能通过调用 startDiagnosisTask 添加」。

接口

@interface NBSDownloadDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT

/**
* 下载地址 
*/
@property (nonatomic, copy) NSString *url;
+ (instancetype)downloadTaskWithName:(NSString *)name
                                 url:(NSString *)url;
@end

示例

任务完整示例「任务创建到添加任务队列」⻅「立即执行」。

// 创建一个任务名为 download_task ，执行URL为 https://www.baidu.com 的 download 任务 
// name⻓度限制为 64，超出则截取。
NBSDownloadDiagnosisTask *download = [NBSDownloadDiagnosisTask downloadTaskWithName:@"download_task" url:@"https://www.baidu.com"];

任务类型

任务类型	说明
立即执行	任务立即执行，执行完后该任务消失
循环执行	任务轮循执行，满触发条件执行完后该任务，任务不消失

立即执行

添加 NBSDiagnosisTask 后会加入到立即执行队列，执行完后该任务消失。

接口

/**
*@brief 将拨测任务加入执行队列中，异步执行，该接口将会忽略task设置的condition属性 
*/
+ (void)startDiagnosisTask:(NBSDiagnosisTask *)task;

示例

该示例为:当触发 startTask 方法时，会立即执行 TCPPing、ICMPPing、MTR、Download 网络探测任务。

- (void)startTask
{
  //创建一个任务名为 tcpPing_task ，执行域名为 www.baidu.com , 端口为 443 的 TCPPing 任务
  NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443];
  
  //创建一个任务名为 icmpPing_task， 执行域名为 www.baidu.com 的 ICMPPing 任务
  NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com"];
 
  //创建一个任务名为 mtr_task ， 执行域名为 www.baidu.com 的 MTR 任务
  NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com"];
  
  //创建一个任务名为 download_task ，执行URL为 https://www.baidu.com 的 Download 任务
  NBSDownloadDiagnosisTask *download = [NBSDownloadDiagnosisTask downloadTaskWithName:@"download_task" url:@"https://www.baidu.com"];
  
  //将创建好的 tcpPing 、icmpPing、mtr、download 任务加入到执行队列 
  [NBSAppAgent startDiagnosisTask:tcpPing];
  [NBSAppAgent startDiagnosisTask:icmpPing];
  [NBSAppAgent startDiagnosisTask:mtr];
  [NBSAppAgent startDiagnosisTask:download];
}

循环执行

添加 NBSDiagnosisTask 后会加入到轮循执行队列，每当满足触发的条件时会执行相应网络探测任务「执行频率会受网络探测任务中execFrequency 属性限制」。

接口

/**
*@brief 添加本地任务至拨测模块，场景触发后，符合condition条件的任务会自动执行 
*/
+ (void)addDiagnosisTask:(NBSDiagnosisTask *)task;

示例

请求错误后轮循任务

该示例为：当请求 URL「URL能匹配执行条件域名」出现 404、502、建联失败、请求超时错误时，会执行 TCPPing、ICMPPing、MTR 网络探测任务。

 - (void)loopTaskNetError
{
   //执行条件域名、uri(只支持?前的uri)等「可配制通配符*，如 『*qq.com、qq.com*、 *qq.com*』;但不支持只设置*」
    NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"];

    // 请求出错码
    // 901 - 未知主机错误 
    // 902 - 建联失败错误 
    // 903 - 请求超时错误 
    // 906 - 非法响应内容错误
    // 908 - SSL证书校验错误
    NSArray *patternErrorCode = @[@404,@502,@902,@903]; //创建一个场景为请求错误后执行的网络探测任务执行条件 
    NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetError]; //为执行条件增加域名限制，若不设置，则不受限制
    condition.patternDomains = domainArray; //为执行条件增加出错码条件:设置触发404、502、建联失败、请求超时错误时执行网络探测任务「若不设置patternErrorCodes，则所有请求错误都满足触发条件」 
    condition.patternErrorCodes = patternErrorCode;
   
   //创建一个任务名为 tcpPing_task ，执行域名为 www.baidu.com , 端口为 443 的 TCPPing 任务
    NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];
   
   //创建一个任务名为 icmpPing_task， 执行域名为 www.baidu.com 的 ICMPPing 任务
    NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];
   
    //创建一个任务名为 mtr_task ， 执行域名为 www.baidu.com 的 MTR 任务
    NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task"  host:@"www.baidu.com" condition:condition];
   
   //将创建好的 tcpPing 、icmpPing、mtr 任务加入到轮循执行任务队列中 「注:轮循执行任务 不支持加入 Download 任务，若加入了 Download 任务也不会执行」
    [NBSAppAgent addDiagnosisTask:tcpPing];
    [NBSAppAgent addDiagnosisTask:icmpPing];
    [NBSAppAgent addDiagnosisTask:mtr];
}

请求结束后轮循任务

该示例为：当请求 URL「URL能匹配执行条件域名」正常结束后，会执行 TCPPing、ICMPPing、 MTR 网络探测任务。

- (void)loopTaskNetFinish
{
   //执行条件域名、uri(只支持?前的uri)等「可配制通配符*，如 『*qq.com、qq.com*、 *qq.com*』;但不支持只设置*」
    NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"];
    //创建一个场景为请求结束后执行的网络探测执行条件
    NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetFinished];
    //为执行条件增加域名限制，若不设置，则不受限制
    condition.patternDomains = domainArray;
  
   //创建一个任务名为 tcpPing_task ，执行域名为 www.baidu.com , 端口为 443 的 TCPPing 任务
    NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];
  
    //创建一个任务名为 icmpPing_task， 执行域名为 www.baidu.com 的 ICMPPing 任务
    NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];
  
    //创建一个任务名为 mtr_task ， 执行域名为 www.baidu.com 的 MTR 任务
    NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com" condition:condition];
    //将创建好的 tcpPing、icmpPing、mtr 任务加入到轮循执行任务队列中 「注:轮循执行任务不 支持加入 Download 任务，若加入了Download任务也不会执行」
    [NBSAppAgent addDiagnosisTask:tcpPing];
    [NBSAppAgent addDiagnosisTask:icmpPing];
    [NBSAppAgent addDiagnosisTask:mtr];
}

网络探测数据回传

网络探测数据回传即将执行的网络探测任务结果通过代理进行回传，您可以使用该结果进行相应开发。网络探测接口数据通过 NBSDiagnosisTaskDelegate 中的 - (void)diagnosisTask: (NBSDiagnosisTask *)task didReceiveResult:(NBSDiagnosisTaskResult *)result; 方法进行回传;具体信息⻅ NBSDiagnosisTaskResult.h 。

示例

#import "ExtensionUtil.h"

@interface ExtensionUtil()<NBSDiagnosisTaskDelegate>
  
@end
  
@implementation ExtensionUtil
  
- (void)networkTask
{
    NBSTCPPingDiagnosisTask *tcp = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcp" host:@"www.tingyun.com" port:80];
    tcp.delegate = self;
  
    NBSICMPPingDiagnosisTask *icmp = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmp" host:@"www.tingyun.com"];
    icmp.delegate = self;
  
    NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr" host:@"www.tingyun.com"];
    mtr.delegate = self;
  
    [NBSAppAgent addDiagnosisTask:tcp];
    [NBSAppAgent addDiagnosisTask:icmp];
    [NBSAppAgent addDiagnosisTask:mtr];
}

#pragma mark diagnosisDelegate

- (void)diagnosisTask:(NBSDiagnosisTask *)task didReceiveResult:
(NBSDiagnosisTaskResult *)result
{
    if(task.taskType == NBSDiagnosisTaskTCPPing)
    {
        NBSTCPPingDiagnosisTaskResult *tcpResult = (NBSTCPPingDiagnosisTaskResult *)result;
        ...
    }else if ( task.taskType == NBSDiagnosisTaskICMPPing)
    {
        NBSICMPPingDiagnosisTaskResult *icmpResult = (NBSICMPPingDiagnosisTaskResult *)result;
        ...
    }else if (task.taskType == NBSDiagnosisTaskMTR)
    {
        NBSMTRDiagnosisTaskResult *mtrResult = (NBSMTRDiagnosisTaskResult*)result;
        ...
    }else {
        NBSDownloadDiagnosisTaskResult *downResult = (NBSDownloadDiagnosisTaskResult *)result;
        ...
    } 
}

网络探测

网络探测类​

NBSTaskCondition​

NBSDiagnosisTask​

TCPPingDiagnosisTask​

ICMPPingDiagnosisTask​

MTRDiagnosisTask​

DownloadDiagnosisTask​

任务类型​

立即执行​

循环执行​

网络探测数据回传​

网络探测类

NBSTaskCondition

NBSDiagnosisTask

TCPPingDiagnosisTask

ICMPPingDiagnosisTask

MTRDiagnosisTask

DownloadDiagnosisTask

任务类型

立即执行

循环执行

网络探测数据回传