This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

DNS Resolve¶

Overview
Sample usage
API Reference

Overview ¶

The DNS resolver implements a basic DNS resolver according to IETF RFC1035 on Domain Implementation and Specification. Supported DNS answers are IPv4/IPv6 addresses and CNAME.

If a CNAME is received, the DNS resolver will create another DNS query. The number of additional queries is controlled by the :kconfig:`CONFIG_DNS_RESOLVER_ADDITIONAL_QUERIES` Kconfig variable.

The multicast DNS (mDNS) client resolver support can be enabled by setting :kconfig:`CONFIG_MDNS_RESOLVER` Kconfig option. See IETF RFC6762 for more details about mDNS.

The link-local multicast name resolution (LLMNR) client resolver support can be enabled by setting the :kconfig:`CONFIG_LLMNR_RESOLVER` Kconfig variable. See IETF RFC4795 for more details about LLMNR.

For more information about DNS configuration variables, see: subsys/net/lib/dns/Kconfig. The DNS resolver API can be found at include/net/dns_resolve.h.

Sample usage ¶

See DNS resolve sample application for details.

API Reference ¶

group dns_resolve

DNS resolving library.

Defines

DNS_MAX_NAME_SIZE¶: 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.

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.

Enums

enum dns_query_type¶

DNS query type enum

Values:

enumerator DNS_QUERY_TYPE_A = 1¶: IPv4 query

enumerator DNS_QUERY_TYPE_AAAA = 28¶: IPv6 query

enum dns_resolve_status¶

Status values for the callback.

Values:

enumerator DNS_EAI_BADFLAGS = -1¶: Invalid value for ai_flags field

enumerator DNS_EAI_NONAME = -2¶: NAME or SERVICE is unknown

enumerator DNS_EAI_AGAIN = -3¶: Temporary failure in name resolution

enumerator DNS_EAI_FAIL = -4¶: Non-recoverable failure in name res

enumerator DNS_EAI_NODATA = -5¶: No address associated with NAME

enumerator DNS_EAI_FAMILY = -6¶: ai_family not supported

enumerator DNS_EAI_SOCKTYPE = -7¶: ai_socktype not supported

enumerator DNS_EAI_SERVICE = -8¶: SRV not supported for ai_socktype

enumerator DNS_EAI_ADDRFAMILY = -9¶: Address family for NAME not supported

enumerator DNS_EAI_MEMORY = -10¶: Memory allocation failure

enumerator DNS_EAI_SYSTEM = -11¶: System error returned in errno

enumerator DNS_EAI_OVERFLOW = -12¶: Argument buffer overflow

enumerator DNS_EAI_INPROGRESS = -100¶: Processing request in progress

enumerator DNS_EAI_CANCELED = -101¶: Request canceled

enumerator DNS_EAI_NOTCANCELED = -102¶: Request not canceled

enumerator DNS_EAI_ALLDONE = -103¶: All requests done

enumerator DNS_EAI_IDN_ENCODE = -105¶: IDN encoding failed

enum dns_resolve_context_state¶

Values:

enumerator DNS_RESOLVE_CONTEXT_ACTIVE¶

enumerator DNS_RESOLVE_CONTEXT_DEACTIVATING¶

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

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.

int dns_resolve_close(struct dns_resolve_context *ctx)¶

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.

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

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.

int dns_resolve_cancel(struct dns_resolve_context *ctx, uint16_t dns_id)¶

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.

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.

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.

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.

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

struct dns_resolve_context *dns_resolve_get_default(void)¶

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.

static inline 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.

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

static inline int dns_cancel_addr_info(uint16_t dns_id)¶

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.

struct dns_addrinfo¶: #include <dns_resolve.h>

Address info struct is passed to callback that gets all the results.

struct dns_resolve_context¶

#include <dns_resolve.h>

DNS resolve context structure.

Public Members

struct sockaddr dns_server¶: DNS server information

struct net_context *net_ctx¶: Connection to the DNS server

uint8_t is_mdns¶: Is this server mDNS one

uint8_t is_llmnr¶: Is this server LLMNR one

struct k_mutex lock¶: Prevent concurrent access

k_timeout_t buf_timeout¶: This timeout is also used when a buffer is required from the buffer pools.

enum dns_resolve_context_state state¶: Is this context in use

struct dns_pending_query¶

#include <dns_resolve.h>

Result callbacks. We have multiple callbacks here so that it is possible to do multiple queries at the same time.

Contents of this structure can be inspected and changed only when the lock is held.

Public Members

struct k_work_delayable timer¶: Timeout timer

struct dns_resolve_context *ctx¶: Back pointer to ctx, needed in timeout handler

dns_resolve_cb_t cb¶

Result callback.

A null value indicates the slot is not in use.

void *user_data¶: User data

k_timeout_t timeout¶: TX timeout

const char *query¶

String containing the thing to resolve like www.example.com

This is set to a non-null value when the query is started, and is not used thereafter.

If the query completed at a point where the work item was still pending the pointer is cleared to indicate that the query is complete, but release of the query slot will be deferred until a request for a slot determines that the work item has been released.

enum dns_query_type query_type¶: Query type

uint16_t id¶: DNS id of this query

uint16_t query_hash¶: Hash of the DNS name + query type we are querying. This hash is calculated so we can match the response that we are receiving. This is needed mainly for mDNS which is setting the DNS id to 0, which means that the id alone cannot be used to find correct pending query.

DNS Resolve¶

Overview¶

Sample usage¶

API Reference¶

Overview ¶

Sample usage ¶

API Reference ¶