Hostname resolution

Hostname resolution, DNS & DNS64 helper functions. More...

Collaboration diagram for Hostname resolution:

Typedefs
typedef struct dnsServer *	dns_index
	Opaque dns_index type which holds the DNS server that was used for a request. More...
typedef void(*	dns_callback) (ca_error aError, const otIp6Address *aAddress, dns_index aIndex, void *aContext)
	The callback used to report results from the host resolution to the requesting layer. More...

Functions
void	DNS_Init (otInstance *aInstance)
	Initialise the DNS utilities. More...
ca_error	DNS_HostToIpv6 (otInstance *aInstance, char *host, dns_callback aCallback, void *aContext)
	Resolve a hostname to an IPv6 address, running DNS queries if necessary. More...
ca_error	DNS_AddServer (otIp6Address *aAddress, uint8_t aPreference, bool aUseDns64)
	Add a DNS server with the given preference, to be used for DNS requests. More...
void	DNS_RegisterServiceFail (dns_index aIndex)
	Register the fact that a DNS server returned an address that could not be contacted. More...
void	DNS_RegisterSuccess (dns_index aIndex)
	Register a successful use of a service resolved with DNS and increase the preference of the corresponding DNS server. More...

Detailed Description

Hostname resolution, DNS & DNS64 helper functions.

Typedef Documentation

dns_callback

typedef void(* dns_callback) (ca_error aError, const otIp6Address *aAddress, dns_index aIndex, void *aContext)

The callback used to report results from the host resolution to the requesting layer.

Warning

The values of aAddress and aIndex are only valid if aError equals CA_ERROR_SUCCESS

Parameters

aError	The status of the host resolution CA_ERROR_SUCCESS: Successful host resolution, result in aAddress CA_ERROR_TIMEOUT: Host resolution failed due to no response from any server (Do you have network connectivity?) CA_ERROR_NOT_FOUND: Received an empty DNS response, hostname could not be resolved CA_ERROR_FAIL: Miscellaneous failure
aAddress	The IPv6 address resolved, only valid if aError is CA_ERROR_SUCCESS
aIndex	The DNS server that was used to obtain the response, only valid if aError is CA_ERROR_SUCCESS
aContext	The context pointer that was provided to the request function

dns_index

typedef struct dnsServer* dns_index

Opaque dns_index type which holds the DNS server that was used for a request.

Function Documentation

DNS_AddServer()

ca_error DNS_AddServer	(	otIp6Address *	aAddress,
		uint8_t	aPreference,
		bool	aUseDns64
	)

Add a DNS server with the given preference, to be used for DNS requests.

Will overwrite servers with lower preference if all slots are full.

Remarks

If aAddress is a NAT64 address, then aUseDns64 should probably be used. If aDns64 is used, then a NAT64 address should probably be used. The result of this is that if the server can be reached, then there is probably valid connectivity.

Parameters

aAddress	DNS server address
aPreference	Preference value, MUST be greater than 1. Higher is more preferred. Default value is 6, but dynamically changes.
aUseDns64	Boolean parameter to force an IPv4 request which will be mapped with DNS64.

Return values

CA_ERROR_SUCCESS	DNS server successfully added
CA_ERROR_NO_BUFFER	No slots for DNS server are available with a lower preference

DNS_HostToIpv6()

ca_error DNS_HostToIpv6	(	otInstance *	aInstance,
		char *	host,
		dns_callback	aCallback,
		void *	aContext
	)

Resolve a hostname to an IPv6 address, running DNS queries if necessary.

This request is non-blocking, and results will be provided via callback.

Parameters

aInstance	The initialised OpenThread instance to use.
host	Host string - can be an IPv6 address, an IPv4 address, or a hostname to be resolved by DNS.
aCallback	Callback to be called when the resolution is complete (if this function returns CA_ERROR_SUCCESS)
aContext	Context to provide to the callback

Returns

ca-error value for request status

Return values

CA_ERROR_SUCCESS	Request successful (Callback will be called with results/future error)
CA_ERROR_NO_BUFFER	No buffer could be allocated for the internal state.
CA_ERROR_NOT_FOUND	No configured DNS server could be found
CA_ERROR_INVALID_ARGS	Invalid hostname
CA_ERROR_FAIL	DNS request failed in OpenThread stack

DNS_Init()

void DNS_Init

(

otInstance *

aInstance

)

Initialise the DNS utilities.

Parameters

aInstance

Initialised openthread instance.

DNS_RegisterServiceFail()

void DNS_RegisterServiceFail

(

dns_index

aIndex

)

Register the fact that a DNS server returned an address that could not be contacted.

Parameters

aIndex

The dns server index provided to the dns callback

DNS_RegisterSuccess()

void DNS_RegisterSuccess

(

dns_index

aIndex

)

Register a successful use of a service resolved with DNS and increase the preference of the corresponding DNS server.

Parameters

aIndex

The dns server index provided to the dns callback