Perform DNS Queries with HTTPDNS SDK to Reduce Latency - HTTPDNS - Alibaba Cloud - HTTPDNS

Perform pre-resolution

After the app starts and the SDK is initialized, call this operation to specify frequently accessed domain names. The SDK resolves these domain names in advance, reducing latency for subsequent resolution requests.

If called during runtime, the SDK resolves the domain names in the specified list and refreshes the cached results. This forces an update and is typically used after specific business actions to refresh domain name resolution and force rescheduling.

Operation definition

- (void)setPreResolveHosts:(NSArray *)hosts;

Class

HttpDnsService

Parameter description

Parameter	Type	Required or not	Description
hosts	NSArray *	Required	The domain names that you want to pre-resolve. Important The domain names to be pre-resolved must be pure domain name strings and cannot contain protocol headers (such as `http://`), paths, or ports. Otherwise, resolution exceptions will occur. Wildcard domain names are not supported. Correct example: `@[@"www.example.com", @"api.example.com", @"img.example.com"]` Incorrect example: `@[@"http://www.example.com:443/path", @"*.example.com"]`

Synchronous non-blocking domain name resolution operation

The synchronous non-blocking operation resolves a domain name without blocking the current thread, but may return an empty result.

This operation queries only the cache and returns the cached resolution result. If no result exists in the cache or the cached result has expired (TTL), domain name resolution runs in a worker thread. After successful resolution, the cache is updated for subsequent use.

Operation definition

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType;

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey;

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(HttpdnsRequest *)request;

Note

This operation is added in HTTPDNS SDK V3.0.0.

Class

HttpDnsService

Parameter definition

Parameter	Type	Required or not	Remarks
host	NSString *	Required	The domain name that you want to resolve
queryIpType	HttpdnsQueryIPType	Required	The type of the IP addresses to which you want to resolve the domain name. Use `HttpdnsQueryIPType` Valid values: v4: IPv4 addresses. v6: IPv6 addresses. both: both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the device network environment. By default, the domain name is resolved to IPv4 addresses. If the environment supports IPv6, the SDK attempts to resolve the domain name to IPv6 addresses.
sdnsParams	NSDictionary<NSString , NSString > *	Not required	The software-defined resolution parameters.
cacheKey	NSString *	Not required	The software-defined cache key.
request	HttpdnsRequest *	Required	For more information, see Resolution-related data structures.

Return description

Type	Description
HttpdnsResult *	The resolution result. For more information, see the section Resolution-related data structures.

Synchronous domain name resolution operation

The synchronous resolution operation blocks the current thread until a valid resolution result is obtained and returned.

This operation first queries the cache and immediately returns the cached result if valid. If no valid result is found, it blocks the calling thread and performs resolution in a worker thread. The resolution result is returned upon completion, or a null value if the timeout is reached.

Note

This operation is added in HTTPDNS SDK V3.0.0.
To prevent app stuttering caused by misuse of this operation in the main thread, this operation performs detection. If the operation detects that the calling thread is the main thread, it automatically downgrades to the implementation logic of the resolveHostSyncNonBlocking operation.
The default timeout period for this operation is 2 seconds. If no valid result is obtained within the timeout period, nil is returned. You can use a request object to specify a custom timeout period.

Operation definition

- (nullable HttpdnsResult *)resolveHostSync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType;

- (nullable HttpdnsResult *)resolveHostSync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey;

- (nullable HttpdnsResult *)resolveHostSync:(HttpdnsRequest *)request;

Class

HttpDnsService

Parameter definition

Parameter	Type	Required or not	Remarks
host	NSString *	Yes	The domain name that you want to resolve
queryIpType	HttpdnsQueryIPType	Yes	The type of the IP addresses to which you want to resolve the domain name. Use `HttpdnsQueryIPType` Valid values: v4: IPv4 addresses. v6: IPv6 addresses. both: both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the current network environment of the device. By default, the domain name is resolved to IPv4 addresses. If the current network environment supports IPv6, the SDK attempts to resolve the domain name to IPv6 addresses.
sdnsParams	NSDictionary<NSString , NSString > *	No	The software-defined resolution parameters.
cacheKey	NSString *	No	The software-defined cache key.
request	HttpdnsRequest *	Yes	For more information, see Resolution-related data structures.

Return description

Type	Description
HttpdnsResult *	The resolution result. For more information, see Resolution-related data structures.

Asynchronous domain name resolution operation

The asynchronous resolution operation resolves a domain name without blocking the current thread and returns the result through a callback.

This operation first queries the cache and immediately returns the cached result through the callback if valid. If no valid result is found, it performs resolution in a worker thread and returns the result through the callback upon completion or timeout.

Operation definition

- (void)resolveHostAsync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType completionHandler:(void (^)(HttpdnsResult * nullable))handler;

- (void)resolveHostAsync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey completionHandler:(void (^)(HttpdnsResult * nullable))handler;

- (void)resolveHostAsync:(HttpdnsRequest *)request completionHandler:(void (^)(HttpdnsResult * nullable))handler;

Note

This operation is added in HTTPDNS SDK V3.0.0.
The default timeout period for this operation is 2 seconds. If no valid result is retrieved within the timeout period, nil is returned. You can use a request object to specify a custom timeout period.

Class

HttpDnsService

Parameter definition

Parameter	Type	Required or not	Description
host	NSString *	Required	The domain name that you want to resolve
queryIpType	HttpdnsQueryIPType	Required	The type of the IP addresses to which you want to resolve the domain name. Use `HttpdnsQueryIPType` Valid values: v4: IPv4 addresses. v6: IPv6 addresses. both: both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the current network environment of the device. By default, the domain name is resolved to IPv4 addresses. If the current network environment supports IPv6, the SDK attempts to resolve the domain name to IPv6 addresses.
handler	(void (^)(HttpdnsResult * nullable))	Required	The callback.
sdnsParams	NSDictionary<NSString , NSString > *	Not required	The software-defined resolution parameters.
cacheKey	NSString *	Not required	The software-defined cache key.
request	HttpdnsRequest *	Required	For more information, see Resolution-related data structures.

Callback result description

Type	Description
HttpdnsResult *	The resolution result. For more information, see Resolution-related data structures.

Operation for domain name cache clearance

Call this operation to clear cached DNS records of domain names, enabling resolution results to update within seconds. For example, if the domain name xxx.com resolves to ip1 and attacks occur on ip1, you can migrate traffic to ip2 as follows:

First, modify the IP address of the domain name to ip2 in the DNS console.
Then, go to the HTTPDNS console and manually submit a refresh action for this domain name to trigger a refresh on the server side.
Manually call this operation to clear the local cache of the xxx.com domain name.
If a request is initiated after the cache is cleared from the app, the server re-sends a request to the authoritative server to obtain ip2 in the latest DNS record. This way, ip2 is used as the actual IP address for resolution.

You can clear the cache of specific domain names or all domain names.

Important

This operation is supported only in HTTPDNS SDK V2.0.4 and later. The newly added cleanAllHostCache operation is supported in V3.1.0 and later.
The operation clears both the memory cache and the local persistent sandbox cache.

Operation definition

- (void)cleanHostCache:(NSArray <NSString *>*)hostArray;

- (void)cleanAllHostCache;

Parameter description

Parameter	Type	Required or not	Description
hostArray	NSArray <NSString >	Required	An array consisting of the domain name whose DNS record you want to clear from the local cache. If you want to clear all data, set this parameter to nil or an empty array

Resolution-related data structures

The HTTPDNS iOS SDK resolution operations use two data structures: HttpdnsRequest and HttpdnsResult.

HttpdnsRequest

Wraps the request parameters for domain name resolution.

Parameter	Type	Required or not	Description
host	NSString *	Required	The domain name that you want to resolve.
queryIpType	HttpdnsQueryIPType	Required	The type of the IP addresses to which you want to resolve the domain name. Use `HttpdnsQueryIPType` Valid values: v4: IPv4 addresses. v6: IPv6 addresses. both: both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the current network environment of the device. By default, the domain name is resolved to IPv4 addresses. If the current network environment supports IPv6, the SDK attempts to resolve the domain name to IPv6 addresses.
resolveTimeoutInSecond	double	Not required	The timeout period for resolution. For synchronous operations, this parameter specifies the maximum wait time. For asynchronous operations, this parameter specifies the maximum wait time for callback. Default value: 2. Valid values: 0.5 to 5. Unit: seconds
sdnsParams	NSDictionary<NSString , NSString > *	Not required	The software-defined resolution parameters.
cacheKey	NSString *	Not required	The software-defined cache key.

HttpdnsResult

Wraps the result returned after domain name resolution. An empty value is returned in the following scenarios:

The domain name cannot be resolved to an IP address. For example, no IP addresses are returned for recursive resolution.
The domain name is not added in the HTTPDNS console, and the server cannot resolve the domain name.
The resolution fails due to reasons such as a network exception.
When you use the synchronous non-blocking operation, the system first returns an empty value if no record is immediately found in the local cache.

Parameter	Type	Description
host	NSString *	The domain name that is resolved
ips	NSArray<NSString >	The IPv4 addresses that are returned.
ipv6s	NSArray<NSString >	The IPv6 addresses that are returned.
lastUpdatedTimeInterval	NSTimeInterval	The time when the IPv4 addresses were last updated. Unix timestamp. Unit: seconds
ttl	NSTimeInterval	The TTL of the IPv4 addresses. Unit: seconds