DNS Resolve Library

DNS resolving library. More...

Data Structures
struct	dns_addrinfo
	Address info struct is passed to callback that gets all the results. More...
struct	dns_resolve_context
	DNS resolve context structure. More...

Macros
#define	DNS_MAX_NAME_SIZE   20
	Max size of the resolved name.

Typedefs
typedef void(*	dns_resolve_cb_t) (enum dns_resolve_status status, struct dns_addrinfo *info, void *user_data)
	DNS resolve callback.

Enumerations
enum	dns_query_type { DNS_QUERY_TYPE_A = 1 , DNS_QUERY_TYPE_AAAA = 28 }
	DNS query type enum. More...
enum	dns_resolve_status {   DNS_EAI_BADFLAGS = -1 , DNS_EAI_NONAME = -2 , DNS_EAI_AGAIN = -3 , DNS_EAI_FAIL = -4 ,   DNS_EAI_NODATA = -5 , DNS_EAI_FAMILY = -6 , DNS_EAI_SOCKTYPE = -7 , DNS_EAI_SERVICE = -8 ,   DNS_EAI_ADDRFAMILY = -9 , DNS_EAI_MEMORY = -10 , DNS_EAI_SYSTEM = -11 , DNS_EAI_OVERFLOW = -12 ,   DNS_EAI_INPROGRESS = -100 , DNS_EAI_CANCELED = -101 , DNS_EAI_NOTCANCELED = -102 , DNS_EAI_ALLDONE = -103 ,   DNS_EAI_IDN_ENCODE = -105 }
	Status values for the callback. More...
enum	dns_resolve_context_state { DNS_RESOLVE_CONTEXT_ACTIVE , DNS_RESOLVE_CONTEXT_DEACTIVATING , DNS_RESOLVE_CONTEXT_INACTIVE }

Functions
int	dns_resolve_init (struct dns_resolve_context *ctx, const char *dns_servers_str[], const struct sockaddr *dns_servers_sa[])
	Init DNS resolving context.
int	dns_resolve_init_default (struct dns_resolve_context *ctx)
	Init DNS resolving context with default Kconfig options.
int	dns_resolve_close (struct dns_resolve_context *ctx)
	Close DNS resolving context.
int	dns_resolve_reconfigure (struct dns_resolve_context *ctx, const char *servers_str[], const struct sockaddr *servers_sa[])
	Reconfigure DNS resolving context.
int	dns_resolve_cancel (struct dns_resolve_context *ctx, uint16_t dns_id)
	Cancel a pending DNS query.
int	dns_resolve_cancel_with_name (struct dns_resolve_context *ctx, uint16_t dns_id, const char *query_name, enum dns_query_type query_type)
	Cancel a pending DNS query using id, name and type.
int	dns_resolve_name (struct dns_resolve_context *ctx, const char *query, enum dns_query_type type, uint16_t *dns_id, dns_resolve_cb_t cb, void *user_data, int32_t timeout)
	Resolve DNS name.
struct dns_resolve_context *	dns_resolve_get_default (void)
	Get default DNS context.
static int	dns_get_addr_info (const char *query, enum dns_query_type type, uint16_t *dns_id, dns_resolve_cb_t cb, void *user_data, int32_t timeout)
	Get IP address info from DNS.
static int	dns_cancel_addr_info (uint16_t dns_id)
	Cancel a pending DNS query.

Detailed Description

DNS resolving library.

Macro Definition Documentation

DNS_MAX_NAME_SIZE

#define DNS_MAX_NAME_SIZE   20

#include <zephyr/net/dns_resolve.h>

Max size of the resolved name.

Typedef Documentation

dns_resolve_cb_t

dns_resolve_cb_t

#include <zephyr/net/dns_resolve.h>

DNS resolve callback.

The DNS resolve callback is called after a successful DNS resolving. The resolver can call this callback multiple times, one for each resolved address.

Parameters

status	The status of the query: DNS_EAI_INPROGRESS returned for each resolved address DNS_EAI_ALLDONE mark end of the resolving, info is set to NULL in this case DNS_EAI_CANCELED if the query was canceled manually or timeout happened DNS_EAI_FAIL if the name cannot be resolved by the server DNS_EAI_NODATA if there is no such name other values means that an error happened.
info	Query results are stored here.
user_data	The user data given in dns_resolve_name() call.

Enumeration Type Documentation

dns_query_type

enum dns_query_type

#include <zephyr/net/dns_resolve.h>

DNS query type enum.

Enumerator
DNS_QUERY_TYPE_A	IPv4 query.
DNS_QUERY_TYPE_AAAA	IPv6 query.

dns_resolve_context_state

enum dns_resolve_context_state

#include <zephyr/net/dns_resolve.h>

Enumerator
DNS_RESOLVE_CONTEXT_ACTIVE
DNS_RESOLVE_CONTEXT_DEACTIVATING
DNS_RESOLVE_CONTEXT_INACTIVE

dns_resolve_status

enum dns_resolve_status

#include <zephyr/net/dns_resolve.h>

Status values for the callback.

Enumerator
DNS_EAI_BADFLAGS	Invalid value for ‘ai_flags’ field.
DNS_EAI_NONAME	NAME or SERVICE is unknown.
DNS_EAI_AGAIN	Temporary failure in name resolution.
DNS_EAI_FAIL	Non-recoverable failure in name res.
DNS_EAI_NODATA	No address associated with NAME.
DNS_EAI_FAMILY	‘ai_family’ not supported
DNS_EAI_SOCKTYPE	‘ai_socktype’ not supported
DNS_EAI_SERVICE	SRV not supported for ‘ai_socktype’.
DNS_EAI_ADDRFAMILY	Address family for NAME not supported.
DNS_EAI_MEMORY	Memory allocation failure.
DNS_EAI_SYSTEM	System error returned in ‘errno’.
DNS_EAI_OVERFLOW	Argument buffer overflow.
DNS_EAI_INPROGRESS	Processing request in progress.
DNS_EAI_CANCELED	Request canceled.
DNS_EAI_NOTCANCELED	Request not canceled.
DNS_EAI_ALLDONE	All requests done.
DNS_EAI_IDN_ENCODE	IDN encoding failed.

Function Documentation

dns_cancel_addr_info()

static int dns_cancel_addr_info ( uint16_t  dns_id )

inlinestatic

#include <zephyr/net/dns_resolve.h>

Cancel a pending DNS query.

This releases DNS resources used by a pending query.

Parameters

dns_id

DNS id of the pending query

Returns

0 if ok, <0 if error.

dns_get_addr_info()

static int dns_get_addr_info ( const char *  query, enum dns_query_type  type, uint16_t *  dns_id, dns_resolve_cb_t  cb, void *  user_data, int32_t  timeout  )

inlinestatic

#include <zephyr/net/dns_resolve.h>

Get IP address info from DNS.

This function can be used to resolve e.g., IPv4 or IPv6 address. Note that this is asynchronous call, the function will return immediately and system will call the callback after resolving has finished or timeout has occurred. We might send the query to multiple servers (if there are more than one server configured), but we only use the result of the first received response. This variant uses system wide DNS servers.

Parameters

query	What the caller wants to resolve.
type	What kind of data the caller wants to get.
dns_id	DNS id is returned to the caller. This is needed if one wishes to cancel the query. This can be set to NULL if there is no need to cancel the query.
cb	Callback to call after the resolving has finished or timeout has happened.
user_data	The user data.
timeout	The timeout value for the connection. Possible values: SYS_FOREVER_MS: the query is tried forever, user needs to cancel it manually if it takes too long time to finish >0: start the query and let the system timeout it after specified ms

Returns

0 if resolving was started ok, < 0 otherwise

dns_resolve_cancel()

int dns_resolve_cancel	(	struct dns_resolve_context *	ctx,
		uint16_t	dns_id
	)

#include <zephyr/net/dns_resolve.h>

Cancel a pending DNS query.

This releases DNS resources used by a pending query.

Parameters

ctx	DNS context
dns_id	DNS id of the pending query

Returns

0 if ok, <0 if error.

dns_resolve_cancel_with_name()

int dns_resolve_cancel_with_name	(	struct dns_resolve_context *	ctx,
		uint16_t	dns_id,
		const char *	query_name,
		enum dns_query_type	query_type
	)

#include <zephyr/net/dns_resolve.h>

Cancel a pending DNS query using id, name and type.

This releases DNS resources used by a pending query.

Parameters

ctx	DNS context
dns_id	DNS id of the pending query
query_name	Name of the resource we are trying to query (hostname)
query_type	Type of the query (A or AAAA)

Returns

0 if ok, <0 if error.

dns_resolve_close()

int dns_resolve_close

(

struct dns_resolve_context *

ctx

)

#include <zephyr/net/dns_resolve.h>

Close DNS resolving context.

This releases DNS resolving context and marks the context unusable. Caller must call the dns_resolve_init() again to make context usable.

Parameters

ctx	DNS context

Returns

0 if ok, <0 if error.

dns_resolve_get_default()

struct dns_resolve_context * dns_resolve_get_default

(

void

)

#include <zephyr/net/dns_resolve.h>

Get default DNS context.

The system level DNS context uses DNS servers that are defined in project config file. If no DNS servers are defined by the user, then resolving DNS names using default DNS context will do nothing. The configuration options are described in subsys/net/lib/dns/Kconfig file.

Returns

Default DNS context.

dns_resolve_init()

int dns_resolve_init	(	struct dns_resolve_context *	ctx,
		const char *	dns_servers_str[],
		const struct sockaddr *	dns_servers_sa[]
	)

#include <zephyr/net/dns_resolve.h>

Init DNS resolving context.

This function sets the DNS server address and initializes the DNS context that is used by the actual resolver. DNS server addresses can be specified either in textual form, or as struct sockaddr (or both). Note that the recommended way to resolve DNS names is to use the dns_get_addr_info() API. In that case user does not need to call dns_resolve_init() as the DNS servers are already setup by the system.

Parameters

ctx	DNS context. If the context variable is allocated from the stack, then the variable needs to be valid for the whole duration of the resolving. Caller does not need to fill the variable beforehand or edit the context afterwards.
dns_servers_str	DNS server addresses using textual strings. The array is NULL terminated. The port number can be given in the string. Syntax for the server addresses with or without port numbers: IPv4 : 10.0.9.1 IPv4 + port : 10.0.9.1:5353 IPv6 : 2001:db8::22:42 IPv6 + port : [2001:db8::22:42]:5353
dns_servers_sa	DNS server addresses as struct sockaddr. The array is NULL terminated. Port numbers are optional in struct sockaddr, the default will be used if set to 0.

Returns

0 if ok, <0 if error.

dns_resolve_init_default()

int dns_resolve_init_default

(

struct dns_resolve_context *

ctx

)

#include <zephyr/net/dns_resolve.h>

Init DNS resolving context with default Kconfig options.

Parameters

ctx	DNS context.

Returns

0 if ok, <0 if error.

dns_resolve_name()

int dns_resolve_name	(	struct dns_resolve_context *	ctx,
		const char *	query,
		enum dns_query_type	type,
		uint16_t *	dns_id,
		dns_resolve_cb_t	cb,
		void *	user_data,
		int32_t	timeout
	)

#include <zephyr/net/dns_resolve.h>

Resolve DNS name.

This function can be used to resolve e.g., IPv4 or IPv6 address. Note that this is asynchronous call, the function will return immediately and system will call the callback after resolving has finished or timeout has occurred. We might send the query to multiple servers (if there are more than one server configured), but we only use the result of the first received response.

Parameters

ctx	DNS context
query	What the caller wants to resolve.
type	What kind of data the caller wants to get.
dns_id	DNS id is returned to the caller. This is needed if one wishes to cancel the query. This can be set to NULL if there is no need to cancel the query.
cb	Callback to call after the resolving has finished or timeout has happened.
user_data	The user data.
timeout	The timeout value for the query. Possible values: SYS_FOREVER_MS: the query is tried forever, user needs to cancel it manually if it takes too long time to finish >0: start the query and let the system timeout it after specified ms

Returns

0 if resolving was started ok, < 0 otherwise

dns_resolve_reconfigure()

int dns_resolve_reconfigure	(	struct dns_resolve_context *	ctx,
		const char *	servers_str[],
		const struct sockaddr *	servers_sa[]
	)

#include <zephyr/net/dns_resolve.h>

Reconfigure DNS resolving context.

Reconfigures DNS context with new server list.

Parameters

ctx	DNS context
servers_str	DNS server addresses using textual strings. The array is NULL terminated. The port number can be given in the string. Syntax for the server addresses with or without port numbers: IPv4 : 10.0.9.1 IPv4 + port : 10.0.9.1:5353 IPv6 : 2001:db8::22:42 IPv6 + port : [2001:db8::22:42]:5353
servers_sa	DNS server addresses as struct sockaddr. The array is NULL terminated. Port numbers are optional in struct sockaddr, the default will be used if set to 0.

Returns

0 if ok, <0 if error.