blob: 14dfb58b085c890d05ee7fd1afe8b6f512ce8507 [file] [log] [blame]
/** @file
* @brief DNS resolving library
*
* An API for applications to resolve a DNS name.
*/
/*
* Copyright (c) 2017 Intel Corporation
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef _DNS_RESOLVE_H
#define _DNS_RESOLVE_H
#include <net/net_ip.h>
#include <net/net_context.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief DNS resolving library
* @defgroup dns_resolve DNS Resolve Library
* @{
*/
/**
* DNS query type enum
*/
enum dns_query_type {
DNS_QUERY_TYPE_A = 1, /* IPv4 */
DNS_QUERY_TYPE_AAAA = 28 /* IPv6 */
};
#ifndef DNS_MAX_NAME_SIZE
#define DNS_MAX_NAME_SIZE 20
#endif
/* Make sure that we can compile things even if CONFIG_DNS_RESOLVER
* is not enabled.
*/
#if !defined(CONFIG_DNS_RESOLVER_MAX_SERVERS)
#define CONFIG_DNS_RESOLVER_MAX_SERVERS 1
#endif
#if !defined(CONFIG_DNS_NUM_CONCUR_QUERIES)
#define CONFIG_DNS_NUM_CONCUR_QUERIES 1
#endif
/**
* Address info struct is passed to callback that gets all the results.
*/
struct dns_addrinfo {
struct sockaddr ai_addr;
socklen_t ai_addrlen;
u8_t ai_family;
char ai_canonname[DNS_MAX_NAME_SIZE + 1];
};
/**
* Status values for the callback.
*/
enum dns_resolve_status {
DNS_EAI_BADFLAGS = -1, /* Invalid value for `ai_flags' field */
DNS_EAI_NONAME = -2, /* NAME or SERVICE is unknown */
DNS_EAI_AGAIN = -3, /* Temporary failure in name resolution */
DNS_EAI_FAIL = -4, /* Non-recoverable failure in name res */
DNS_EAI_NODATA = -5, /* No address associated with NAME */
DNS_EAI_FAMILY = -6, /* `ai_family' not supported */
DNS_EAI_SOCKTYPE = -7, /* `ai_socktype' not supported */
DNS_EAI_SERVICE = -8, /* SRV not supported for `ai_socktype' */
DNS_EAI_ADDRFAMILY = -9, /* Address family for NAME not supported */
DNS_EAI_MEMORY = -10, /* Memory allocation failure */
DNS_EAI_SYSTEM = -11, /* System error returned in `errno' */
DNS_EAI_OVERFLOW = -12, /* Argument buffer overflow */
DNS_EAI_INPROGRESS = -100, /* Processing request in progress */
DNS_EAI_CANCELED = -101, /* Request canceled */
DNS_EAI_NOTCANCELED = -102, /* Request not canceled */
DNS_EAI_ALLDONE = -103, /* All requests done */
DNS_EAI_IDN_ENCODE = -105, /* IDN encoding failed */
};
/**
* @typedef dns_resolve_cb_t
* @brief DNS resolve callback
*
* @details The DNS resolve callback is called after a successful
* DNS resolving. The resolver can call this callback multiple times, one
* for each resolved address.
*
* @param 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.
* @param info Query results are stored here.
* @param user_data The user data given in dns_resolve_name() call.
*/
typedef void (*dns_resolve_cb_t)(enum dns_resolve_status status,
struct dns_addrinfo *info,
void *user_data);
/**
* DNS resolve context structure.
*/
struct dns_resolve_context {
struct {
/** DNS server information */
struct sockaddr dns_server;
/** Connection to the DNS server */
struct net_context *net_ctx;
} servers[CONFIG_DNS_RESOLVER_MAX_SERVERS];
/** This timeout is also used when a buffer is required from the
* buffer pools.
*/
s32_t buf_timeout;
/** Result callbacks. We have multiple callbacks here so that it is
* possible to do multiple queries at the same time.
*/
struct dns_pending_query {
/** Timeout timer */
struct k_delayed_work timer;
/** Back pointer to ctx, needed in timeout handler */
struct dns_resolve_context *ctx;
/** Result callback */
dns_resolve_cb_t cb;
/** User data */
void *user_data;
/** TX timeout */
s32_t timeout;
/** String containing the thing to resolve like www.example.com
*/
const char *query;
/** Query type */
enum dns_query_type query_type;
/** DNS id of this query */
u16_t id;
} queries[CONFIG_DNS_NUM_CONCUR_QUERIES];
/** Is this context in use */
bool is_used;
};
/**
* @brief Init DNS resolving context.
*
* @details This function sets the DNS server address and initializes the
* DNS context that is used by the actual resolver.
* 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.
*
* @param 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.
* @param dns_servers DNS server addresses. 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
*
* @return 0 if ok, <0 if error.
*/
int dns_resolve_init(struct dns_resolve_context *ctx,
const char *dns_servers[]);
/**
* @brief Close DNS resolving context.
*
* @details This releases DNS resolving context and marks the context unusable.
* Caller must call the dns_resolve_init() again to make context usable.
*
* @param ctx DNS context
*
* @return 0 if ok, <0 if error.
*/
int dns_resolve_close(struct dns_resolve_context *ctx);
/**
* @brief Cancel a pending DNS query.
*
* @details This releases DNS resources used by a pending query.
*
* @param ctx DNS context
* @param dns_id DNS id of the pending query
*
* @return 0 if ok, <0 if error.
*/
int dns_resolve_cancel(struct dns_resolve_context *ctx,
u16_t dns_id);
/**
* @brief Resolve DNS name.
*
* @details 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.
*
* @param ctx DNS context
* @param query What the caller wants to resolve.
* @param type What kind of data the caller wants to get.
* @param 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.
* @param cb Callback to call after the resolving has finished or timeout
* has happened.
* @param user_data The user data.
* @param timeout The timeout value for the query. Possible values:
* K_FOREVER: 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
*
* @return 0 if resolving was started ok, < 0 otherwise
*/
int dns_resolve_name(struct dns_resolve_context *ctx,
const char *query,
enum dns_query_type type,
u16_t *dns_id,
dns_resolve_cb_t cb,
void *user_data,
s32_t timeout);
/**
* @brief Get default DNS context.
*
* @details 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.
*
* @return Default DNS context.
*/
struct dns_resolve_context *dns_resolve_get_default(void);
/**
* @brief Get IP address info from DNS.
*
* @details 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.
*
* @param query What the caller wants to resolve.
* @param type What kind of data the caller wants to get.
* @param 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.
* @param cb Callback to call after the resolving has finished or timeout
* has happened.
* @param user_data The user data.
* @param timeout The timeout value for the connection. Possible values:
* K_FOREVER: 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
*
* @return 0 if resolving was started ok, < 0 otherwise
*/
static inline int dns_get_addr_info(const char *query,
enum dns_query_type type,
u16_t *dns_id,
dns_resolve_cb_t cb,
void *user_data,
s32_t timeout)
{
return dns_resolve_name(dns_resolve_get_default(),
query,
type,
dns_id,
cb,
user_data,
timeout);
}
/**
* @brief Cancel a pending DNS query.
*
* @details This releases DNS resources used by a pending query.
*
* @param dns_id DNS id of the pending query
*
* @return 0 if ok, <0 if error.
*/
static inline int dns_cancel_addr_info(u16_t dns_id)
{
return dns_resolve_cancel(dns_resolve_get_default(), dns_id);
}
/**
* @}
*/
#if defined(CONFIG_DNS_RESOLVER)
/**
* @brief Initialize DNS subsystem.
*/
void dns_init_resolver(void);
#else
#define dns_init_resolver(...)
#endif /* CONFIG_DNS_RESOLVER */
#ifdef __cplusplus
}
#endif
#endif /* _DNS_RESOLVE_H */