All Products
Search

This Product

    HTTPDNS:Domain name resolution operations

    Document Center

    HTTPDNS:Domain name resolution operations

    Last Updated:Jul 22, 2025

    This topic describes the operations related to domain name resolution.

    Perform pre-resolution

    After the app starts and the SDK is initialized, you can call this operation to specify frequently accessed domain names that you may use later. This allows the SDK to resolve these domain names in advance, reducing the latency of subsequent domain name resolution requests.

    If you call this operation during runtime, the SDK resolves the domain names in the specified list and refreshes the resolution results in the cache. This is equivalent to forcing an update. This operation is typically used after certain business actions occur when you want to refresh the current domain name resolution and force domain name 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

    If you use the synchronous non-blocking operation to resolve a domain name, the current thread is not blocked, but an empty result may be returned.

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

    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

    If you use the synchronous resolution operation to resolve a domain name, the current thread is blocked until a valid resolution result is obtained and returned.

    This operation first queries the cache. If a valid resolution result exists in the cache, the cached resolution result is immediately returned. If no valid resolution result is found, the operation blocks the current thread that makes the resolution call and performs domain name resolution in a worker thread. After the domain name resolution is complete, the resolution result is returned. If the timeout is reached, a null value is returned.

    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

    If you use the asynchronous resolution operation to resolve a domain name, the current thread is not blocked, and the resolution result is returned through a callback.

    This operation first queries the cache. If a valid resolution result exists in the cache, the cached resolution result is immediately returned through the callback. If no valid resolution result is found, the operation performs domain name resolution in a worker thread. After the domain resolution is complete or the timeout is reached, the resolution result is returned through the callback.

    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

    If you use HTTPDNS, you can call this operation to clear the cached DNS records of domain names. This way, the resolution results can be updated within seconds. For example, if the domain name xxx.com is resolved to the IP address ip1 and attacks occur on ip1, you can perform the following steps to migrate the traffic from ip1 to ip2:

    1. First, modify the IP address of the domain name to ip2 in the DNS console.

    2. Then, go to the HTTPDNS console and manually submit a refresh action for this domain name to trigger a refresh on the server side.

    3. Manually call this operation to clear the local cache of the xxx.com domain name.

    4. 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.

    Call this operation to 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 domain name resolution operations provided by the HTTPDNS iOS SDK mainly involve two custom structures: HttpdnsRequest and HttpdnsResult.

    HttpdnsRequest

    The resolution request class that wraps request parameters related to 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

    The resolution result class that wraps the result returned after a domain name is successfully resolved. The following list describes the scenarios in which an empty value is returned:

    • 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