Typedefs
typedef struct M_dns	M_dns_t

typedef enum M_dns_happyeb_status	M_dns_happyeb_status_t

typedef enum M_dns_result	M_dns_result_t

typedef void(*	M_dns_ghbn_callback_t) (const M_list_str_t ipaddrs, void cb_data, M_dns_result_t result)

Enumerations
enum	M_dns_happyeb_status { M_HAPPYEB_STATUS_GOOD = 0 , M_HAPPYEB_STATUS_UNKNOWN = 1 , M_HAPPYEB_STATUS_SLOW = 2 , M_HAPPYEB_STATUS_BAD = 3 }

enum	M_dns_result { M_DNS_RESULT_SUCCESS = 0 , M_DNS_RESULT_SUCCESS_CACHE = 1 , M_DNS_RESULT_SUCCESS_CACHE_EVICT = 2 , M_DNS_RESULT_SERVFAIL = 3 , M_DNS_RESULT_NOTFOUND = 4 , M_DNS_RESULT_TIMEOUT = 5 , M_DNS_RESULT_INVALID = 6 }

Functions
M_dns_t *	M_dns_create (M_event_t *event)

M_bool	M_dns_destroy (M_dns_t *dns)

M_bool	M_dns_set_query_timeout (M_dns_t *dns, M_uint64 timeout_ms)

M_bool	M_dns_set_cache_timeout (M_dns_t *dns, M_uint64 max_timeout_s)

void	M_dns_gethostbyname (M_dns_t dns, M_event_t event, const char hostname, M_io_net_type_t type, M_dns_ghbn_callback_t callback, void cb_data)

void	M_dns_happyeyeballs_update (M_dns_t dns, const char ipaddr, M_dns_happyeb_status_t status)

M_bool	M_dns_pton (int af, const char src, void dst)

M_bool	M_dns_ntop (int af, const void src, char addr, size_t addr_size)

Detailed Description

It's intended that a single global DNS object will be created to allow for caching. Aiding with caching, Happy eyeballs is used to aid in choosing the best server when DNS resolves multiple addresses.

Typedef Documentation

◆ M_dns_t

typedef struct M_dns M_dns_t

◆ M_dns_happyeb_status_t

typedef enum M_dns_happyeb_status M_dns_happyeb_status_t

◆ M_dns_result_t

typedef enum M_dns_result M_dns_result_t

◆ M_dns_ghbn_callback_t

typedef void(* M_dns_ghbn_callback_t) (const M_list_str_t *ipaddrs, void *cb_data, M_dns_result_t result)

Returned IP address list is cleaned up immediately after the callback returns, if persistence is needed, duplicate the list. The list is returned sorted in preference order:

List starts as alternating between ipv6 and ipv4 addresses in the order returned from the DNS server, such as ipv6-1, ipv4-1, ipv6-2, ipv4-2 and so on.
List then is updated with the happyeyeballs RFC6555/8305 status for prior connection attempts.
Finally the list is sorted by happyeyeballs status as the primary sort comparison, followed by the original order as per server preference.
Parameters

[in] ipaddrs Ip addresses resolved in string form, nor NULL if none

[in] cb_data Callback data provided to M_dns_gethostbyname()

[in] result Result code of DNS lookup

Enumeration Type Documentation

◆ M_dns_happyeb_status

enum M_dns_happyeb_status

RFC 6555/8305 Happy Eyeballs status codes

Enumerator
M_HAPPYEB_STATUS_GOOD	Successfully connected to server
M_HAPPYEB_STATUS_UNKNOWN	Don't know, probably not attempted
M_HAPPYEB_STATUS_SLOW	Don't know for sure its bad, but we started and a different connection finished first
M_HAPPYEB_STATUS_BAD	Recieved a connection error

◆ M_dns_result

enum M_dns_result

Result codes for DNS queries

Enumerator
M_DNS_RESULT_SUCCESS	DNS result successful
M_DNS_RESULT_SUCCESS_CACHE	DNS result successful, returned from cache
M_DNS_RESULT_SUCCESS_CACHE_EVICT	DNS result successful, evicting old cache
M_DNS_RESULT_SERVFAIL	DNS server failure
M_DNS_RESULT_NOTFOUND	DNS server returned a Not Found error
M_DNS_RESULT_TIMEOUT	Timeout resolving DNS name
M_DNS_RESULT_INVALID	Invalid use

Function Documentation

◆ M_dns_create()

M_dns_t * M_dns_create ( M_event_t * event )

Create a DNS resolver handle.

This resolver handle is responsible for caching DNS results as well as tracking which associated IP addresses resulted in successful or failed connections for optimizing future connection attempts. This DNS handle will be passed into functions that require DNS resolution like M_io_net_client_create().

It is recommended to create a single DNS resolver handle at startup and pass the same handle to all functions which need it, and destroy the handle at shutdown.

Returns: Initialized DNS handle

◆ M_dns_destroy()

M_bool M_dns_destroy ( M_dns_t * dns )

Destroys the memory associated with a DNS handle.

DNS uses reference counters, and will delay destruction until after last consumer is destroyed.

Parameters

[in] dns Handle initialized via M_dns_create().

Returns: M_TRUE on success, M_FALSE if handle is actively being used.

◆ M_dns_set_query_timeout()

M_bool M_dns_set_query_timeout	(	M_dns_t *	dns,
		M_uint64	timeout_ms
	)

Set the maximum query time before a timeout is returned.

In some cases, if a prior result is cached, the query may still return success rather than a timeout failure at the end of a timeout, but the result will be stale. If set to 0, will use the internal default of 5000ms (5s)

Parameters

[in]	dns	Initialized DNS object
[in]	timeout_ms	Timeout specified in milliseconds. If provided as 0, will use the default of 5000ms (5s).

Returns: M_TRUE if set successfully, M_FALSE otherwise

◆ M_dns_set_cache_timeout()

M_bool M_dns_set_cache_timeout	(	M_dns_t *	dns,
		M_uint64	max_timeout_s
	)

Set the maximum amount of time a DNS query can be cached for where results are served out of the cache rather than querying a remote DNS server.

Parameters

[in]	dns	Initialized DNS object
[in]	max_timeout_s	Specify the maximum timeout of the cached results, even if no DNS server is reachable. Stale results can no longer be delivered after this timeframe and will result in DNS errors being returned. If 0 is specified, will use the default of 3600s (1 hr).

Returns: M_TRUE if set successfully, M_FALSE otherwise

◆ M_dns_gethostbyname()

void M_dns_gethostbyname	(	M_dns_t *	dns,
		M_event_t *	event,
		const char *	hostname,
		M_io_net_type_t	type,
		M_dns_ghbn_callback_t	callback,
		void *	cb_data
	)

Request to resolve a DNS hostname to one or more IP addresses. When the resolution is complete, the callback passed in will be called. This function may call the callback immediately if the DNS result is cached. Once the supplied callback is called, the query will be automatically cleaned up.

Parameters

[in]	dns	Handle to DNS pointer created with M_dns_create()
[in]	event	Optional. Event handle to use to deliver the result callback to. This is useful to ensure the result is enqueued to the same event loop as requested which may limit need for possible external locking.
[in]	hostname	Hostname to look up.
[in]	type	Type of lookup to perform (IPv4, IPv6, or both/any)
[in]	callback	Callback to call on completion
[in]	cb_data	User data handle passed to callback on completion

◆ M_dns_happyeyeballs_update()

void M_dns_happyeyeballs_update	(	M_dns_t *	dns,
		const char *	ipaddr,
		M_dns_happyeb_status_t	status
	)

Notify the DNS subsystem of any updates to connection status on a given IP address. This will cause future results of M_dns_gethostbyname() to be sorted based on success or failure of past connections.

Parameters

[in]	dns	Handle to DNS pointer created with M_dns_create()
[in]	ipaddr	String form of IP address
[in]	status	Status of connection attempt.

◆ M_dns_pton()

M_bool M_dns_pton	(	int	af,
		const char *	src,
		void *	dst
	)

Convert the string form ip address of the given address family to its binary form.

Parameters

[in]	af	Address family of AF_INET or AF_INET6
[in]	src	Null-terminated string represenation of IP address
[out]	dst	Buffer of adequate size to hold AF_INET (32bits) or AF_INET6 (128bits) result

Returns: M_TRUE on success, M_FALSE on conversion failure

◆ M_dns_ntop()

M_bool M_dns_ntop	(	int	af,
		const void *	src,
		char *	addr,
		size_t	addr_size
	)

Convert the binary form of ip address of the given address family to its string form.

Parameters

[in]	af	Address family of AF_INET or AF_INET6
[in]	src	Buffer containing binary representation of ip address. 32bits for AF_INET, 128bits for AF_INET6.
[out]	addr	Destination buffer to write string represenation of ip address.
[in]	addr_size	Size of destination buffer

Returns: M_TRUE on success, M_FALSE on conversion failure.

[in]	ipaddrs	Ip addresses resolved in string form, nor NULL if none
[in]	cb_data	Callback data provided to M_dns_gethostbyname()
[in]	result	Result code of DNS lookup

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_dns_t

◆ M_dns_happyeb_status_t

◆ M_dns_result_t

◆ M_dns_ghbn_callback_t

Enumeration Type Documentation

◆ M_dns_happyeb_status

◆ M_dns_result

Function Documentation

◆ M_dns_create()

◆ M_dns_destroy()

◆ M_dns_set_query_timeout()

◆ M_dns_set_cache_timeout()

◆ M_dns_gethostbyname()

◆ M_dns_happyeyeballs_update()

◆ M_dns_pton()

◆ M_dns_ntop()