Network Diagnosis

That is, perform network diagnosis on client devices to obtain the network status of the device, which can be achieved by setting up tasks such as ICMPPing, TCPPing, MTR, etc., through the following classes and interfaces.

Network Diagnosis Classes

Class Name	Description
NBSTaskCondition	Network diagnosis task condition class
NBSDiagnosisTask	Network diagnosis task base class
TCPPingDiagnosisTask	TCPPing network diagnosis task class
ICMPPingDiagnosisTask	ICMPPing network diagnosis class
MTRDiagnosisTask	MTR network diagnosis class
DownloadDiagnosisTask	Download network diagnosis class

NBSTaskCondition

Network diagnosis task condition class, used to create network diagnosis task conditions; can set properties such as scene, execution domain, error codes, etc.

Interface

@interface NBSTaskCondition : NSObject<NBSSerializable>
NBS_NO_INIT
  
/**
* Trigger scene: such as triggering after network error*
*/
@property (nonatomic, assign) NBSDiagnosisTaskScene scene;

/**
* When network requests complete or error, uri will only execute if it matches patternDomain, if not set, no restriction by default
*/
@property (nonatomic, strong) NSArray <NSString *>*patternDomains;

/**
* Request errors included in patternErrorCodes will execute, if not set, no restriction by default
*/
@property (nonatomic, strong) NSArray <NSNumber *>*patternErrorCodes;

- (instancetype)initWithScene:(NBSDiagnosisTaskScene)scene;

@end

Example

 NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"]; //Request error codes
// 901 - Unknown host error
// 902 - Connection failure error
// 903 - Request timeout error
// 906 - Invalid response content error
// 908 - SSL certificate verification error
NSArray *patternErrorCode = @[@404,@502,@902,@903];
// Example 1, create condition after request error //Create a condition with scene NBSDiagnosisTaskSceneAfterNetError
NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetError]; //Set condition execution condition domains, uri (only supports uri before ?), etc. "Can configure wildcards *, such as '*qq.com, qq.com*, *qq.com*'; but does not support setting * only"; if not set, no restriction 
condition.patternDomains = domainArray;
//Set trigger error conditions: set to trigger network diagnosis tasks when 405, 502, connection failure, request timeout errors occur "If patternErrorCodes is not set, all request errors meet the trigger conditions"
condition.patternErrorCodes = patternErrorCode;

//Example 2, create condition after request finished //Create a condition with scene NBSDiagnosisTaskSceneAfterNetFinished
NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetFinished]; 
//Set condition execution condition domains, uri (only supports uri before ?), etc. "Can configure wildcards *, such as '*qq.com, qq.com*, *qq.com*'; but does not support setting * only"; if not set, no restriction 
condition.patternDomains = domainArray;

NBSDiagnosisTask

Network diagnosis task base class, can set network execution conditions, task execution frequency, etc.

@interface NBSDiagnosisTask : NSObject<NBSSerializable>
/**
* Host address
*/
@property (nonatomic, copy) NSString *host;

/**
* Match condition 
*/
@property (nonatomic, strong) NBSTaskCondition *condition;

/**
* Execution interval, default 60 seconds, i.e., the same task executes at most once within 60 seconds 
*/
@property (nonatomic, assign) NSInteger execFrequency;
@end

TCPPingDiagnosisTask

TCPPing network diagnosis task class, used to create TCPPing network diagnosis tasks.

Interface

@interface NBSTCPPingDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT

/**
* Port 
*/
@property (nonatomic ,assign) NSInteger port;

/**
* Number of repeats for one tcpping task, default 3 times
*/
@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

Example

Complete task example "Task creation to adding to task queue" see "Immediate Execution" or "Loop Execution".

//Create a tcpPing task with condition (task name tcpPing_task, execution domain and port are www.baidu.com, 443 respectively)
// name length limit is 64, truncated if exceeded.
NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];

//Create a tcpPing task without condition (task name tcpPing_task, execution domain and port are www.baidu.com, 443 respectively)
// name length limit is 64, truncated if exceeded.
NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443];

//Number of pings for one tcpPing task, default 3 times; can be set according to needs "range 3 - 100" 
tcpPing.repeat = 5;

//tcpPing task execution frequency, default 60s; can be set as needed "range > 1"; "Note: tasks added via startDiagnosisTask interface are not affected by this configuration"
tcpPing.execFrequency = 30;

ICMPPingDiagnosisTask

ICMPPing network diagnosis class, used to create ICMPPing network diagnosis tasks.

Interface

@interface NBSICMPPingDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT

/**
* Number of repeats for one icmpping task, default 3 times
*/
@property (nonatomic, assign) NSInteger repeat;

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

Example

Complete task example "Task creation to adding to task queue" see "Immediate Execution" or "Loop Execution".

//Create an icmpPing task with condition (task name icmpPing_task, execution domain www.baidu.com)
// name length limit is 64, truncated if exceeded.
NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];

//Create an icmpPing task without condition (task name icmpPing_task, execution domain www.baidu.com)
// name length limit is 64, truncated if exceeded.
NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com"];

//Number of pings for one icmpPing task, default 3 times; can be set according to needs "range 3 - 100" 
icmpPing.repeat = 5;

//icmpPing task execution frequency, default 60s; can be set as needed "range > 1"; "Note: tasks added via startDiagnosisTask interface are not affected by this configuration" 
icmpPing.execFrequency = 30;

MTRDiagnosisTask

MTR network diagnosis class, used to create MTR network diagnosis tasks.

Interface

@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

Example

Complete task example "Task creation to adding to task queue" see "Immediate Execution" or "Loop Execution".

//Create an MTR task with condition (task name mtr_task, execution domain www.baidu.com) // name length limit is 64, truncated if exceeded.
NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com" condition:condition];

//Create an MTR task without condition (task name mtr_task, execution domain www.baidu.com) // name length limit is 64, truncated if exceeded.
NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com"];

//MTR task execution frequency, default 60s; can be set as needed "range > 1"; "Note: tasks added via startDiagnosisTask interface are not affected by this configuration"
mtr.execFrequency = 30;

DownloadDiagnosisTask

Download network diagnosis class, used to create Download network diagnosis tasks "Download network diagnosis tasks only support immediate execution, i.e., can only be added by calling startDiagnosisTask".

Interface

@interface NBSDownloadDiagnosisTask : NBSDiagnosisTask
NBS_NO_INIT

/**
* Download address 
*/
@property (nonatomic, copy) NSString *url;
+ (instancetype)downloadTaskWithName:(NSString *)name
                                 url:(NSString *)url;
@end

Example

Complete task example "Task creation to adding to task queue" see "Immediate Execution".

// Create a task named download_task, executing URL https://www.baidu.com download task 
// name length limit is 64, truncated if exceeded.
NBSDownloadDiagnosisTask *download = [NBSDownloadDiagnosisTask downloadTaskWithName:@"download_task" url:@"https://www.baidu.com"];

Task Types

Task Type	Description
Immediate Execution	Task executes immediately, disappears after execution
Loop Execution	Task executes in loop, disappears after meeting trigger conditions, task does not disappear

Immediate Execution

After adding NBSDiagnosisTask, it will be added to the immediate execution queue, and the task disappears after execution.

Interface

/**
*@brief Add the diagnosis task to the execution queue, execute asynchronously, this interface will ignore the condition property set by task 
*/
+ (void)startDiagnosisTask:(NBSDiagnosisTask *)task;

Example

This example: when the startTask method is triggered, it will immediately execute TCPPing, ICMPPing, MTR, Download network diagnosis tasks.

- (void)startTask
{
  //Create a task named tcpPing_task, execution domain www.baidu.com:port 443 TCPPing task
  NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443];
  
  //Create a task named icmpPing_task, execution domain www.baidu.com ICMPPing task
  NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com"];
 
  //Create a task named mtr_task, execution domain www.baidu.com MTR task
  NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com"];
  
  //Create a task named download_task, executing URL https://www.baidu.com Download task
  NBSDownloadDiagnosisTask *download = [NBSDownloadDiagnosisTask downloadTaskWithName:@"download_task" url:@"https://www.baidu.com"];
  
  //Add the created tcpPing, icmpPing, mtr, download tasks to the execution queue 
  [NBSAppAgent startDiagnosisTask:tcpPing];
  [NBSAppAgent startDiagnosisTask:icmpPing];
  [NBSAppAgent startDiagnosisTask:mtr];
  [NBSAppAgent startDiagnosisTask:download];
}

Loop Execution

After adding NBSDiagnosisTask, it will be added to the loop execution queue, and whenever the trigger conditions are met, the corresponding network diagnosis tasks will be executed "Execution frequency is limited by the execFrequency property in the network diagnosis task".

Interface

/**
*@brief Add local task to diagnosis module, after scene trigger, tasks that meet condition conditions will execute automatically 
*/
+ (void)addDiagnosisTask:(NBSDiagnosisTask *)task;

Example

Loop task after request error

This example: when the request URL "URL that can match the execution condition domain" has 404, 502, connection failure, request timeout errors, TCPPing, ICMPPing, MTR network diagnosis tasks will be executed.

 - (void)loopTaskNetError
{
  //Execution condition domains, uri (only supports uri before ?), etc. "Can configure wildcards *, such as '*qq.com, qq.com*, *qq.com*'; but does not support setting * only"
  NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"];

  // Request error codes
  // 901 - Unknown host error 
  // 902 - Connection failure error 
  // 903 - Request timeout error 
  // 906 - Invalid response content error
  // 908 - SSL certificate verification error
  NSArray *patternErrorCode = @[@404,@502,@902,@903]; //Create a network diagnosis task execution condition with scene after request error 
  NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetError]; //Add domain restriction to execution condition, if not set, no restriction
  condition.patternDomains = domainArray; //Add error code condition to execution condition: set to trigger network diagnosis tasks when 404, 502, connection failure, request timeout errors occur "If patternErrorCodes is not set, all request errors meet the trigger conditions" 
  condition.patternErrorCodes = patternErrorCode;
   
  //Create a task named tcpPing_task, execution domain www.baidu.com, port 443 TCPPing task
  NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];
   
  //Create a task named icmpPing_task, execution domain www.baidu.com ICMPPing task
  NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];
   
  //Create a task named mtr_task, execution domain www.baidu.com MTR task
  NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com" condition:condition];
   
  //Add the created tcpPing, icmpPing, mtr tasks to the loop execution task queue "Note: loop execution tasks do not support adding Download tasks, if Download tasks are added, they will not execute"
  [NBSAppAgent addDiagnosisTask:tcpPing];
  [NBSAppAgent addDiagnosisTask:icmpPing];
  [NBSAppAgent addDiagnosisTask:mtr];
}

Loop task after request finished

This example: when the request URL "URL that can match the execution condition domain" finishes normally, TCPPing, ICMPPing, MTR network diagnosis tasks will be executed.

- (void)loopTaskNetFinish
{
  //Execution condition domains, uri (only supports uri before ?), etc. "Can configure wildcards *, such as '*qq.com, qq.com*, *qq.com*'; but does not support setting * only"
  NSArray *domainArray = @[@"www.baidu.com",@"*qq*",@"https://www.tingyun.com"];
  //Create a network diagnosis execution condition with scene after request finished
  NBSTaskCondition *condition = [[NBSTaskCondition alloc] initWithScene:NBSDiagnosisTaskSceneAfterNetFinished];
  //Add domain restriction to execution condition, if not set, no restriction
  condition.patternDomains = domainArray;
  
  //Create a task named tcpPing_task, execution domain www.baidu.com, port 443 TCPPing task
  NBSTCPPingDiagnosisTask *tcpPing = [NBSTCPPingDiagnosisTask tcppingTaskWithName:@"tcpPing_task" host:@"www.baidu.com" port:443 condition:condition];
  
  //Create a task named icmpPing_task, execution domain www.baidu.com ICMPPing task
  NBSICMPPingDiagnosisTask *icmpPing = [NBSICMPPingDiagnosisTask icmppingTaskWithName:@"icmpPing_task" host:@"www.baidu.com" condition:condition];
  
  //Create a task named mtr_task, execution domain www.baidu.com MTR task
  NBSMTRDiagnosisTask *mtr = [NBSMTRDiagnosisTask mtrTaskWithName:@"mtr_task" host:@"www.baidu.com" condition:condition];
  //Add the created tcpPing, icmpPing, mtr tasks to the loop execution task queue "Note: loop execution tasks do not support adding Download tasks, if Download tasks are added, they will not execute"
  [NBSAppAgent addDiagnosisTask:tcpPing];
  [NBSAppAgent addDiagnosisTask:icmpPing];
  [NBSAppAgent addDiagnosisTask:mtr];
}

Network Diagnosis Data Callback

Network diagnosis data callback will transmit the results of executed network diagnosis tasks through the delegate, you can use this result for corresponding development. Network diagnosis interface data is transmitted through the - (void)diagnosisTask: (NBSDiagnosisTask *)task didReceiveResult:(NBSDiagnosisTaskResult *)result; method in NBSDiagnosisTaskDelegate; for details see NBSDiagnosisTaskResult.h.

Example

#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;
        ...
    } 
}

Network Diagnosis

Network Diagnosis Classes​

NBSTaskCondition​

NBSDiagnosisTask​

TCPPingDiagnosisTask​

ICMPPingDiagnosisTask​

MTRDiagnosisTask​

DownloadDiagnosisTask​

Task Types​

Immediate Execution​

Loop Execution​

Network Diagnosis Data Callback​

Network Diagnosis Classes

NBSTaskCondition

NBSDiagnosisTask

TCPPingDiagnosisTask

ICMPPingDiagnosisTask

MTRDiagnosisTask

DownloadDiagnosisTask

Task Types

Immediate Execution

Loop Execution

Network Diagnosis Data Callback