how to perform custom domain name resolution using the Android SDK - HTTPDNS

Introduction

The APIs described in this document are for use with custom resolution functions. Use these APIs when basic resolution scenarios do not meet your requirements.

You must configure the common parameters that are required for each custom domain name resolution request. For more information, see Set global parameters for custom resolution.

Custom synchronous resolution API

When you use the custom synchronous resolution API to resolve a domain name, the current thread is blocked until a valid resolution result is returned.

This API first queries the cache using the `cacheKey`. If an active resolution result exists in the cache, the API immediately returns the cached result. If no active result is found, the API blocks the calling thread and performs domain name resolution in a worker thread. After the resolution is complete, the result is returned. If the request times out, a null value is returned.

Important

The overall duration of the synchronous resolution operation is controlled by the timeout configuration. If the resolution fails within the timeout period, an empty resolution result is immediately returned.

`getHttpDnsResultForHostSync`

API definition

HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType requestIpType, Map<String, String> params, String cacheKey)

Version introduced

2.4.0

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
host	String	Yes	The domain name to resolve.
requestIpType	RequestIpType	Yes	The IP address type to resolve. We recommend that you set this to RequestIpType.both. This is an enumeration. It specifies the IP address type to resolve. v4: Resolve to IPv4 addresses. v6: Resolve to IPv6 addresses. both: Resolve to both IPv4 and IPv6 addresses. auto: The software development kit (SDK) determines the address type based on the current network stack of the device. By default, the domain name is resolved to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve the domain name to IPv6 addresses.
params	Map<String, String>	Yes	Extra parameters for domain name resolution. This corresponds to the event.parameters parameter in the custom resolution function on the server.
cacheKey	String	Yes	The local cache key for the domain name. If extra parameters change and the server must resolve the domain name again, you must also change the cacheKey.

Return value

Type	Description
HTTPDNSResult	The resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
val httpDnsResult = dnsService?.getHttpDnsResultForHostSync(host, RequestIpType.auto, params, cacheKey)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
HTTPDNSResult httpDnsResult = httpdns.getHttpDnsResultForHostSync(host, RequestIpType.auto, params, cacheKey);

Custom asynchronous resolution API

When you use the custom asynchronous resolution API to resolve a domain name, the current thread is not blocked. The resolution result is returned through a callback.

This API first queries the cache. If an active resolution result exists in the cache, the API immediately returns the cached result through the callback. If no active result is found, the API performs domain name resolution in a worker thread. After the resolution is complete or the request times out, the result is returned through the callback.

Important

For a synchronous parsing interface, the total parsing time is controlled by the timeout configuration. If parsing is not completed within the configured timeout period, the interface immediately returns an empty result.

`getHttpDnsResultForHostAsync`

API definition

void getHttpDnsResultForHostAsync(String host, RequestIpType requestIpType, Map<String, String> params, String cacheKey, HttpDnsCallback callback)

Version introduced

2.4.0

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
host	String	Yes	The domain name to resolve.
requestIpType	RequestIpType	Yes	The IP address type to resolve. We recommend that you set this to RequestIpType.both. This is an enumeration. It specifies the IP address type to resolve. v4: Resolve to IPv4 addresses. v6: Resolve to IPv6 addresses. both: Resolve to both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the current network stack of the device. By default, the domain name is resolved to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve the domain name to IPv6 addresses.
params	Map<String, String>	Yes	Extra parameters for domain name resolution. This corresponds to the event.parameters parameter in the custom resolution function on the server.
cacheKey	String	Yes	The local cache key for the domain name. If extra parameters change and the server must resolve the domain name again, you must also change the cacheKey.
callback	HttpDnsCallback	Yes	The callback class for the resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
dnsService?.getHttpDnsResultForHostAsync(host, RequestIpType.auto, params, cacheKey, HttpDnsCallback {
    httpDnsResult = it
})

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
httpdns.getHttpDnsResultForHostAsync(host, RequestIpType.auto, params, cacheKey, new HttpDnsCallback() {
  void onHttpDnsCompleted(HTTPDNSResult result) {
  }      
});

Custom synchronous non-blocking resolution API

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

This API only queries the cache and returns the resolution result from the cache. If no resolution result exists in the cache or the cached result has expired, domain name resolution is performed in a worker thread. After a successful resolution, the cache is updated for the next call.

`getHttpDnsResultForHostSyncNonBlocking`

API definition

HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType requestIpType, Map<String, String> params, String cacheKey)

Version introduced

2.4.0

Class

HttpDnsService

Parameters

Parameter	Type	Required	Description
host	String	Yes	The domain name to resolve.
requestIpType	RequestIpType	Yes	The IP address type to resolve. We recommend that you set this to RequestIpType.both. This is an enumeration. It specifies the IP address type to resolve. v4: Resolve to IPv4 addresses. v6: Resolve to IPv6 addresses. both: Resolve to both IPv4 and IPv6 addresses. auto: The SDK determines the address type based on the current network stack of the device. By default, the domain name is resolved to IPv4 addresses. If the current network stack supports IPv6, the SDK also attempts to resolve the domain name to IPv6 addresses.
params	Map<String, String>	Yes	Extra parameters for domain name resolution. This corresponds to the event.parameters parameter in the custom resolution function on the server.
cacheKey	String	Yes	The local cache key for the domain name. If extra parameters change and the server must resolve the domain name again, you must also change the cacheKey.

Return value

Type	Description
HTTPDNSResult	The resolution result.

Sample code

Kotlin

val httpdns = HttpDns.getService(accountID)
val httpDnsResult = dnsService?.getHttpDnsResultForHostSyncNonBlocking(host, RequestIpType.auto, params, cacheKey)

Java

HttpDnsService httpdns = HttpDns.getService(accountID);
HTTPDNSResult httpDnsResult = httpdns.getHttpDnsResultForHostSyncNonBlocking(host, RequestIpType.auto, params, cacheKey);