Mbed OS Reference
Loading...
Searching...
No Matches
DNS Class Referenceabstract

Base class for DNS provider. More...

#include <DNS.h>

Inheritance diagram for DNS:
NetworkInterface NetworkStack CellularInterface EMACInterface EthInterface InterfaceNanostack L3IPInterface MeshInterface PPPInterface WiFiInterface OnboardNetworkStack AT_CellularStack

Public Types

typedef mbed::Callback< void(nsapi_value_or_error_t result, SocketAddress *address)> hostbyname_cb_t
 Hostname translation callback for gethostbyname_async. More...
 

Public Member Functions

virtual nsapi_error_t gethostbyname (const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)=0
 Translate a hostname to an IP address with specific version using network interface name. More...
 
virtual nsapi_value_or_error_t getaddrinfo (const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name=NULL)=0
 Translate a hostname to the multiple IP addresses with specific version using network interface name. More...
 
virtual nsapi_value_or_error_t gethostbyname_async (const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)=0
 Translate a hostname to an IP address (asynchronous) More...
 
virtual nsapi_value_or_error_t getaddrinfo_async (const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name=NULL)=0
 Translate a hostname to the multiple IP addresses (asynchronous) More...
 
virtual nsapi_error_t gethostbyname_async_cancel (int id)=0
 Cancel asynchronous hostname translation. More...
 
virtual nsapi_error_t add_dns_server (const SocketAddress &address, const char *interface_name=NULL)=0
 Add a domain name server to list of servers to query. More...
 

Detailed Description

Base class for DNS provider.

Definition at line 28 of file DNS.h.

Member Typedef Documentation

◆ hostbyname_cb_t

Hostname translation callback for gethostbyname_async.

The callback is called after DNS resolution completes, or a failure occurs.

Callback should not take more than 10ms to execute, otherwise it might prevent underlying thread processing. A portable user of the callback should not make calls to network operations due to stack size limitations. The callback should not perform expensive operations such as socket recv/send calls or blocking operations.


result : Negative error code on failure or value that represents the number of DNS records
address : On success, destination for the host SocketAddress.

Definition at line 80 of file DNS.h.

Member Function Documentation

◆ gethostbyname()

virtual nsapi_error_t gethostbyname ( const char *  host,
SocketAddress address,
nsapi_version_t  version = NSAPI_UNSPEC,
const char *  interface_name = NULL 
)
pure virtual

Translate a hostname to an IP address with specific version using network interface name.

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolve using a UDP socket on the stack.

Parameters
hostHostname to resolve.
addressPointer to a SocketAddress to store the result.
versionIP version of address to resolve, NSAPI_UNSPEC indicates version is chosen by the stack (defaults to NSAPI_UNSPEC).
interface_nameNetwork interface name
Returns
NSAPI_ERROR_OK on success, negative error code on failure.

Implemented in Nanostack, RM1000_AT_CellularStack, NetworkInterface, and NetworkStack.

◆ getaddrinfo()

virtual nsapi_value_or_error_t getaddrinfo ( const char *  hostname,
SocketAddress hints,
SocketAddress **  res,
const char *  interface_name = NULL 
)
pure virtual

Translate a hostname to the multiple IP addresses with specific version using network interface name.

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolve using a UDP socket on the stack.

Parameters
hostnameHostname to resolve.
hintsPointer to a SocketAddress with query parameters.
resPointer to a SocketAddress array to store the result..
interface_nameNetwork interface name
Returns
number of results on success, negative error code on failure.

Implemented in NetworkInterface, and NetworkStack.

◆ gethostbyname_async()

virtual nsapi_value_or_error_t gethostbyname_async ( const char *  host,
hostbyname_cb_t  callback,
nsapi_version_t  version = NSAPI_UNSPEC,
const char *  interface_name = NULL 
)
pure virtual

Translate a hostname to an IP address (asynchronous)

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolved using a UDP socket on the stack.

The call is non-blocking. The result of the DNS operation is returned by the callback. If this function returns failure, the callback will not be called. If it is successful, (the IP address was found from the DNS cache), the callback will be called before the function returns.

Parameters
hostHostname to resolve.
callbackCallback that is called to return the result.
versionIP version of address to resolve. NSAPI_UNSPEC indicates that the version is chosen by the stack (defaults to NSAPI_UNSPEC).
interface_nameNetwork interface name
Returns
NSAPI_ERROR_OK on immediate success, negative error code on immediate failure or a positive unique ID that represents the hostname translation operation and can be passed to cancel.

Implemented in Nanostack, NetworkInterface, and NetworkStack.

◆ getaddrinfo_async()

virtual nsapi_value_or_error_t getaddrinfo_async ( const char *  hostname,
SocketAddress hints,
hostbyname_cb_t  callback,
const char *  interface_name = NULL 
)
pure virtual

Translate a hostname to the multiple IP addresses (asynchronous)

The hostname may be either a domain name or an IP address. If the hostname is an IP address, no network transactions will be performed.

If no stack-specific DNS resolution is provided, the hostname will be resolved using a UDP socket on the stack.

The call is non-blocking. Result of the DNS operation is returned by the callback. If this function returns failure, callback will not be called. In case that IP addresses are found from DNS cache, callback will be called before function returns.

Parameters
hostnameHostname to resolve.
hintsPointer to a SocketAddress with query parameters.
callbackCallback that is called to return the result.
interface_nameNetwork interface name
Returns
NSAPI_ERROR_OK on immediate success, negative error code on immediate failure or a positive unique ID that represents the hostname translation operation and can be passed to cancel.

Implemented in NetworkInterface, and NetworkStack.

◆ gethostbyname_async_cancel()

virtual nsapi_error_t gethostbyname_async_cancel ( int  id)
pure virtual

Cancel asynchronous hostname translation.

When translation is canceled, callback is not called.

Parameters
idUnique ID of the hostname translation operation returned by gethostbyname_async.
Returns
NSAPI_ERROR_OK on success, negative error code on failure.

Implemented in NetworkInterface, and NetworkStack.

◆ add_dns_server()

virtual nsapi_error_t add_dns_server ( const SocketAddress address,
const char *  interface_name = NULL 
)
pure virtual

Add a domain name server to list of servers to query.

Parameters
addressDNS server host address.
interface_nameNetwork interface name
Returns
NSAPI_ERROR_OK on success, negative error code on failure.

Implemented in NetworkInterface, and NetworkStack.