Alibaba Cloud DNS:iOS SDK development guide

DNSResolver *resolver = [DNSResolver share];
// setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
// andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
// andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
[resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
// Specify domains for automatic cache updates. The array can contain a maximum of 10 domains.
[resolver setKeepAliveDomains:@[@"your_domain_1", @"your_domain_2"]];
// Pre-resolve domains that you expect to use later.
[resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
// All domains are pre-resolved.
}];

// setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
// andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
// andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
[[DNSResolver share] setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];

[DNSResolver share].scheme = DNSResolverSchemeHttps;

[DNSResolver share].cacheEnable=NO;

// The array can contain a maximum of 10 domains.
[[DNSResolver share] setKeepAliveDomains:@[@"www.taobao.com",@"www.aliyun.com"]];

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.
   
   DNSResolver *resolver = [DNSResolver share];
   // setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
   // andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
   // andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   resolver.cacheEnable = YES;
   // Pre-resolve domains that you expect to use later.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // All domains are pre-resolved.
       
   }];
   
   return YES;
}

[DNSResolver share].ipv6Enable = YES;

[DNSResolver share].shortEnable = YES;

[DNSResolver share].cacheCountLimit = 200;

[DNSResolver share].speedTestEnable=YES;

[DNSResolver share].speedPort = 80;

[DNSResolver share].speedTestIpv6PreferMs = 0;

[DNSResolver share].ispEnable = YES;

[DNSResolver share].maxNegativeCache = 30;

[DNSResolver share].maxCacheTTL= 3600;

[DNSResolver share].immutableCacheEnable = NO;// Immutable cache is disabled by default.

[DNSResolver share].maxConcurrentResolveCount = 10;

/// Pre-resolves domain information. Call this method at app startup. The results are stored in the cache to accelerate subsequent resolutions.
/// Automatically detects the network environment (IPv4-only, IPv6-only, or dual-stack) to get an IP suitable for the current network.
/// @param domainArray An array of domain names.
/// @param complete A callback that is executed after resolution is complete.
- (void)preloadDomains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Gets an array of IP addresses for a domain. This method automatically detects the network environment (IPv4-only, IPv6-only, or dual-stack) to get a suitable IP.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IP over the network. If caching is disabled, it always fetches the IP over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all IP addresses.
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Gets an array of IP addresses directly from the cache without waiting. This method automatically detects the network environment (IPv4-only, IPv6-only, or dual-stack).
/// Returns nil if the cache is empty. If the cache is not empty and `enable` is set to YES, it returns the cached data. If the data is expired, it asynchronously updates the cache. If the cache is not empty and `enable` is set to NO, it returns nil for expired entries and asynchronously updates the cache.
/// @param domain The domain name.
/// @param enable Specifies whether to return expired IP addresses.
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// Gets an array of IPv4 information objects for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IPs over the network. If caching is disabled, it always fetches the IPs over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all domain information objects.
- (void)getIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Gets an array of IPv6 information objects for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IPs over the network. If caching is disabled, it always fetches the IPs over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all domain information objects.
- (void)getIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(NSArray<DNSDomainInfo *> *domainInfoArray))complete;

/// Gets a random IPv4 information object for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IP over the network. If caching is disabled, it always fetches the IP over the network.
/// @param domain The domain name.
/// @param complete A callback that returns one random domain information object.
- (void)getRandomIpv4InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Gets a random IPv6 information object for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IP over the network. If caching is disabled, it always fetches the IP over the network.
/// @param domain The domain name.
/// @param complete A callback that returns one random domain information object.
- (void)getRandomIpv6InfoWithDomain:(NSString *)domain complete:(void(^)(DNSDomainInfo *domainInfo))complete;

/// Gets an array of IPv4 addresses for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IPs over the network. If caching is disabled, it always fetches the IPs over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all IP addresses.
- (void)getIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Gets an array of IPv6 addresses for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IPs over the network. If caching is disabled, it always fetches the IPs over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all IP addresses.
- (void)getIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

/// Gets a random IPv4 address for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IP over the network. If caching is disabled, it always fetches the IP over the network.
/// @param domain The domain name.
/// @param complete A callback that returns one random IP address.
- (void)getRandomIpv4DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Gets a random IPv6 address for a domain.
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IP over the network. If caching is disabled, it always fetches the IP over the network.
/// @param domain The domain name.
/// @param complete A callback that returns one random IP address.
- (void)getRandomIpv6DataWithDomain:(NSString *)domain complete:(void(^)(NSString *data))complete;

/// Pre-resolves IPv4 information for domains. Call this at app startup. The results are stored in the cache to accelerate subsequent resolutions.
/// @param domainArray An array of domain names.
/// @param complete A callback that is executed after resolution is complete.
- (void)preloadIpv4Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Pre-resolves IPv6 information for domains. Call this at app startup. The results are stored in the cache to accelerate subsequent resolutions.
/// @param domainArray An array of domain names.
/// @param complete A callback that is executed after resolution is complete.
- (void)preloadIpv6Domains:(NSArray<NSString *> *)domainArray complete:(void(^)(void))complete;

/// Gets an array of IPv4 addresses directly from the cache without waiting.
/// Returns nil if the cache is empty. If the cache is not empty and `enable` is set to YES, it returns the cached data. If the data is expired, it asynchronously updates the cache. If the cache is not empty and `enable` is set to NO, it returns nil for expired entries and asynchronously updates the cache.
/// @param domain The domain name.
/// @param enable Specifies whether to return expired IP addresses.
- (NSArray<NSString *> *)getIpv4ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// Gets an array of IPv6 addresses directly from the cache without waiting.
/// Returns nil if the cache is empty. If the cache is not empty and `enable` is set to YES, it returns the cached data. If the data is expired, it asynchronously updates the cache. If the cache is not empty and `enable` is set to NO, it returns nil for expired entries and asynchronously updates the cache.
/// @param domain The domain name.
/// @param enable Specifies whether to return expired IP addresses.
- (NSArray<NSString *> *)getIpv6ByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

/// Collects request statistics.
-(NSArray *)getRequestReportInfo;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Override point for customization after application launch.
   // Initialization method
   DNSResolver *resolver = [DNSResolver share];
   // setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
   // andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
   // andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Specify domains for automatic cache updates. The array can contain a maximum of 10 domains.
	 [resolver setKeepAliveDomains:@[@"your_domain_1",@"your_domain_2"]];
   // Pre-resolve domains to get resolution results in advance and store them in the cache.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // All domains are pre-resolved.
       
   }];
   return YES;
}

/// Gets an array of IP addresses for a domain. This method automatically adapts to the network environment (IPv4-only, IPv6-only, or dual-stack).
/// If caching is enabled, it returns data from the cache first. If the cache is empty or expired, it fetches the IPs over the network. If caching is disabled, it always fetches the IPs over the network.
/// @param domain The domain name.
/// @param complete A callback that returns all IP addresses.
- (void)getIpsDataWithDomain:(NSString *)domain complete:(void(^)(NSArray<NSString *> *dataArray))complete;

[[DNSResolver share] getIpsDataWithDomain:@"www.taobao.com" complete:^(NSArray<NSString *> *dataArray) {
    // dataArray is the array of IP addresses for www.taobao.com.
   if (dataArray.count > 0) {
       //TODO: Use an IP address for the URL connection.
   }    
}];

/// Gets an array of IP addresses directly from the cache without waiting. This method automatically adapts to the network environment (IPv4-only, IPv6-only, or dual-stack).
/// Returns nil if the cache is empty. If the cache is not empty and `enable` is set to YES, it returns the cached data. If the data is expired, it asynchronously updates the cache. If the cache is not empty and `enable` is set to NO, it returns nil for expired entries and asynchronously updates the cache.
/// @param domain The domain name.
/// @param enable Specifies whether to return expired IP addresses.
- (NSArray<NSString *> *)getIpsByCacheWithDomain:(NSString *)domain andExpiredIPEnabled:(BOOL)enable;

NSArray *result = [[DNSResolver share] getIpsByCacheWithDomain:@"your_domain" andExpiredIPEnabled:YES];
// Use the cached result.
if (result.count > 0) {
   //TODO: Use an IP address for the URL connection.
   
}

/// `hostArray` is an array of hostnames to clear from the cache. To clear all data, pass nil or an empty array.
-(void)clearHostCache:(NSArray <NSString *>*)hostArray;

[[DNSResolver share] clearHostCache:@[@"domain1", @"domain2"]];

/// Collects request statistics.
-(NSArray *)getRequestReportInfo;

NSArray *array = [[DNSResolver share] getRequestReportInfo];

 (
      {
         avgRtt = "1";                                // Average domain resolution time (ms)
         cacheDnsNum = 0;                             // Number of cache hits                       
         domain = "www.taobao.com";                   // The resolved domain
         gobackLocaldnsNum = 0;                       // Number of fallbacks to local DNS
         localErro = 0;                               // Number of local DNS resolution failures
         maxRtt = "60";                               // Maximum domain resolution time (ms)
         noPermissionErro = 0;                        // Number of authentication failures
         noResponseErro = 0;                          // Number of no-response errors          
         requestPDnsNum = 1;                          // Number of recursive queries
         sp = "China Mobile";                         // ISP name
         successNum = 1;                              // Number of successful resolutions
         timeoutErro = 0;                             // Number of network timeout errors
         type = 28;                                   // IP type: 1 for IPv4, 28 for IPv6
         urlParameterErro = 0;                        // Number of URL parameter format errors
         urlPathErro = 0;                             // Number of URL path errors
      }
         ......
 );

//******** For IPv4-only scenarios *******
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   DNSResolver *resolver = [DNSResolver share];
   // setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
   // andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
   // andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Enable caching. Default is YES.
   resolver.cacheEnable = YES;
   // Pre-resolve IPv4 information for domains that you expect to use later.
   [resolver preloadIpv4Domains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // All domains are pre-resolved.
   }];
   return YES;
}

//******** For dual-stack scenarios that support IPv6 *******
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   DNSResolver *resolver = [DNSResolver share];
   // setAccountId:@"******": Replace the asterisks with the Account ID from the Access Configuration page in the console.
   // andAccessKeyId:@"********": Replace the asterisks with the AccessKey ID of the key that you created on the Access Configuration page.
   // andAccesskeySecret:@"********": Replace the asterisks with the AccessKey Secret of the key that you created on the Access Configuration page.
   [resolver setAccountId:@"******" andAccessKeyId:@"********" andAccesskeySecret:@"********"];
   // Enable caching. Default is YES.
   resolver.cacheEnable = YES;
   // Enable domain resolution over IPv6 networks. Default is NO.
   resolver.ipv6Enable = YES;
   // Enable IP speed test. Default is NO.
   resolver.speedTestEnable = YES;
   // Pre-resolve domains. This automatically detects the network (IPv4-only, IPv6-only, or dual-stack) and gets a suitable IP.
   [resolver preloadDomains:@[@"domain1", @"domain2", @"domain3"] complete:^{
       // All domains are pre-resolved.
   }];
   return YES;
}

    //******** For IPv4-only scenarios *******
      __weak typeof(self) ws = self;
    // Prioritize getting the IP from the cache, allowing stale but usable records.
    NSArray<NSString *> *cachedIPs = [[DNSResolver share] getIpv4ByCacheWithDomain:domain andExpiredIPEnabled:YES];
    if (cachedIPs && cachedIPs.count > 0) {
        NSString *ip = cachedIPs.firstObject;
        NSLog(@"Fast cache hit. Domain %@ resolved to IP: %@", domain, ip);
        [self requestWithIP:ip domain:domain]; // Connect directly using the IP.
    } else {
        // Cache miss. Perform an asynchronous resolution.
        [[DNSResolver share] getIpv4DataWithDomain:domain complete:^(NSArray<NSString *> *resolvedIPs) {
            if (resolvedIPs && resolvedIPs.count > 0) {
                NSString *ip = resolvedIPs.firstObject;
                NSLog(@"Async resolution complete. Domain %@ resolved to IP: %@", domain, ip);
                [ws requestWithIP:ip domain:domain]; // Connect directly using the IP.
            } else {
                NSLog(@"Domain resolution failed. Falling back to original domain.");
                [ws requestWithIP:domain domain:domain]; // Fallback: Use the original domain.
            }
        }];
    }

    //******** For dual-stack scenarios that support IPv6 *******
      __weak typeof(self) ws = self;
    // Prioritize getting the IP from the cache, allowing stale but usable records.
    NSArray<NSString *> *cachedIPs = [[DNSResolver share] getIpsByCacheWithDomain:domain andExpiredIPEnabled:YES];
    if (cachedIPs && cachedIPs.count > 0) {
        NSString *ip = cachedIPs.firstObject;
        NSLog(@"Fast cache hit. Domain %@ resolved to IP: %@", domain, ip);
        [self requestWithIP:ip domain:domain]; // Connect directly using the IP.
    } else {
        // Cache miss. Perform an asynchronous resolution.
        [[DNSResolver share] getIpsDataWithDomain:domain complete:^(NSArray<NSString *> *resolvedIPs) {
            if (resolvedIPs && resolvedIPs.count > 0) {
                NSString *ip = resolvedIPs.firstObject;
                NSLog(@"Async resolution complete. Domain %@ resolved to IP: %@", domain, ip);
                [ws requestWithIP:ip domain:domain]; // Connect directly using the IP.
            } else {
                NSLog(@"Domain resolution failed. Falling back to original domain.");
                [ws requestWithIP:domain domain:domain]; // Fallback: Use the original domain.
            }
        }];
    }

1. Usar somente DNS de cloud pública

Este modo destina-se a usuários SaaS padrão que não implantaram um DNS on-premises.

DNSResolver *resolver = [DNSResolver share];
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];

2. Usar somente DNS on-premises (implantação privada)

Este modo destina-se a clientes que dependem inteiramente do seu DNS on-premises.

DNSResolver *resolver = [DNSResolver share];
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Optional: Disable certificate validation (for test environments only).
// [resolver setEnableCertificateValidation:NO];

3. Nuvem pública como primária, on-premises como backup

Se o HTTPDNS público primário da Alibaba Cloud falhar, a resolução fará failover automaticamente para o DNS on-premises.

DNSResolver *resolver = [DNSResolver share];

// Primary: Public cloud DNS
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];
    
// Backup: On-premises DNS
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Optional: Disable certificate validation (for test environments only).
// [resolver setEnableCertificateValidation:NO];

4. On-premises como primário, nuvem pública como backup

Se o DNS on-premises primário falhar, a resolução fará failover automaticamente para o HTTPDNS público da Alibaba Cloud.

DNSResolver *resolver = [DNSResolver share];

// Primary: On-premises DNS
[resolver setFusionDNSWithIPv4:@[@"1.1.X.X", @"2.2.X.X"]
                            IPv6:nil
                           Host:nil
                           Port:@"443"
              HealthCheckDomain:@"check.example.com"
                    accessKeyId:@"your_fusion_ak"
                accesskeySecret:@"your_fusion_sk"];
// Optional: Disable certificate validation (for test environments only).
// [resolver setEnableCertificateValidation:NO];

// Backup: Public cloud DNS
[resolver setAccountId:@"******" 
        andAccessKeyId:@"********" 
    andAccesskeySecret:@"********"];

1. Configuração de DNS on-premises

/** This is related to on-premises DNS for private deployments. Do not call this method if you only use public DNS.
 *
 * Sets the on-premises DNS server address and authentication information.
 * Use this interface to pass your private DNS server's address and authentication credentials.
 * The SDK will use this information to initiate requests.
 * @param ipv4 An array of IPv4 addresses (can be nil).
 * @param ipv6 An array of IPv6 addresses (can be nil).
 * @param host An array of hostnames (can be nil).
 * @param port The service port (for example, @"443"). If nil, the default port is used.
 * @param healthCheckDomain The domain for health checks after a circuit break. If a resolution service fails more than three consecutive times, the circuit is tripped, and the service IP enters a healthCheck state. Subsequent requests will not use this service. A timer then probes this healthCheckDomain every minute to check if the service is available. If a probe succeeds, the service state is restored to alive and can receive requests again.
 * @param accessKeyId Your private accessKeyId for authentication.
 * @param accesskeySecret Your private accesskeySecret for authentication.
 */
- (void)setFusionDNSWithIPv4:(NSArray<NSString *> * _Nullable)ipv4
                        IPv6:(NSArray<NSString *> * _Nullable)ipv6
                        Host:(NSArray<NSString *> * _Nullable)host
                        Port:(NSString * _Nullable)port
           HealthCheckDomain:(NSString * _Nonnull)healthCheckDomain
                 accessKeyId:(NSString * _Nonnull)accessKeyId
             accesskeySecret:(NSString * _Nonnull)accesskeySecret;

2. Validação de certificado TLS

/** This is related to on-premises DNS for private deployments. Do not call this method if you only use public DNS.
 *
 * Enable or disable certificate validation for on-premises DNS. The default is YES. If your server is not configured with a domain or IP certificate, you can set this to NO for testing. For production environments, set this to YES to avoid security risks.
 * @param enable YES to enable (default), NO to disable.
 */
- (void)setEnableCertificateValidation:(BOOL)enable;

3. Limiar de failover automático

/** When both public cloud DNS and on-premises DNS are configured, this sets the number of primary DNS failures that trigger an automatic failover to the backup DNS. If only one type of DNS is configured, do not call this method.
 *
 * Sets the number of primary DNS failures before automatically failing over to the backup DNS. If only one type of DNS is configured, do not call this method.
 * @param fallbackThreshold The number of failures. The default is 4 when public cloud DNS is primary, and 2 when on-premises DNS is primary.
 * The valid range is [0-4]. A value of 0 means failover occurs immediately. The maximum is 4.
 */
- (void)setFallbackThreshold:(NSInteger)fallbackThreshold;