1.2.1.7 DNS Module
The Domain Name Service associates host names (i.e., www.microchip.com) with IP addresses (i.e., 10.0.54.2). The DNS Client module provides DNS resolution capabilities to the stack. As illustrated in the figure, a typical resolution process is as follows:
The DNS Client, also known as the DNS Resolver, will try to resolve the IP address from its local resources, which includes the Name to Address mappings in the local DNS cache. DNS clients are capable of caching the previous DNS query results and this module supports a maximum number of cached entries configured with the DNS_CLIENT_CACHE_ENTRIES parameter. Each cache entry is capable of storing the maximum number of IPv4 and IPv6 address, which is configured using the DNS_CLIENT_CACHE_PER_IPV4_ADDRESS and DNS_CLIENT_CACHE_PER_IPV6_ADDRESS parameters. The DNS resolver will use these available local resources and if it cannot find the IP Address corresponding to the requested DNS Record type, it will then query a DNS server for the IP Address.
The DNS server will directly answer the query if it is the authoritative server for the particular domain (ex.: www.microchip.com); otherwise, it will check its local cache of the previous queries. If it cannot find the IP Address, it will then query the DNS servers on the Internet.
Next, the DNS Server will query one of the root servers requesting a list of Authoritative servers for the .COM domain. The Root server will respond with the list of servers addresses hosting the .COM domain.
The Authoritative DNS server will then respond with the IP Address or a list of IP Address (if more than one server hosts the website www.microchip.com) for www.microchip.com.
The address that the DNS server returns back to the DNS client is then passed to the DNS application, which initially requested the IP Address information.
DNS resolver clients are both internal stack modules (SNTP, for example), as well as applications using the TCP/IP stack.
Abstraction Model
DNS is part of the Application Layer. Following is a description of how the DNS Client works and how it should be used.
By default, the DNS client is enabled and included in the TCP/IP stackbuild.
The DNS Client module will use a UDP socket on port number 53 to contact the DNS server.
The DNS client can be enabled/disabled dynamically at run time.
When the TCP/IP commands module is built in the stack, commands for manipulation of the DNS module are available:
The DNS module can be enabled using the command "dns eth0 on".
The DNS client module can be disabled from the command prompt using "dns eth0 off".
In the above examples the first Ethernet interface is used. Any valid network interface can be used.
Applications or demonstrations such as berkeley_tcp_client, berkeley_udp_client, tcpip_tcp_client, and tcpip_udp_client, use the TCPIP_DNS_Resolve function with Host name and Record type as arguments to resolve the domain host name. The DNS module supports the Record type of "A" for IPv4 addresses and "AAAA" for IPv6.
The resolved domain name and the mapped IPv4 or IPv6 address will be stored in a table with the expiration time, which is calculated from the DNS server response.
The server supplied IPv4 and IPv6 addresses will be cached internally (see the DNS_CLIENT_CACHE_PER_IPV4_ADDRESS and DNS_CLIENT_CACHE_PER_IPV6_ADDRESS parameters).
The TCPIP_DNS_IsResolved function will return DNS_RES_OK if the domain name resolve is successful.
The TCPIP_DNS_GetNumberOfIPAddresses function can be used to obtain the number of the IPv4 or IPv6 addresses present in the DNS Resolver tables.
The DNS Resolver table (cache) stores the dcorresponding name, the IP address and the expiration time returned by the server.
The functions, TCPIP_DNS_GetIPv4Address and TCPIP_DNS_GetIPv6Address, can be used to obtain the IPv4 or Ipv6 addresses for a resolved name entry.
Library Interface
| Name | Description |
|---|---|
| General Functions | |
| TCPIP_DNS_HandlerDeRegister | Deregisters a previously registered DNS client handler. |
| TCPIP_DNS_HandlerRegister | Registers a DNS client Handler. |
| TCPIP_DNS_IsEnabled | Determines if the DNS client is enabled on that specified interface. |
| TCPIP_DNS_ClientInfoGet | Get the current DNS client parameters. |
| TCPIP_DNS_ClientTask | Standard TCP/IP stack module task function. |
| TCPIP_DNS_Disable | Disables the DNS Client for the specified interface. |
| TCPIP_DNS_Enable | Enables the DNS Client for the specified interface. |
| TCPIP_DNS_EntryQuery | Queries a DNS Resolver specific entry. |
| TCPIP_DNS_GetIPAddressesNumber | Get the count of resolved IPv4 and/or IPv6 address for a host name. |
| TCPIP_DNS_GetIPv4Addresses | Get IPV4 addresses for a DNS resolved name. |
| TCPIP_DNS_GetIPv6Addresses | Get IPV6 addresses for a DNS resolved name. |
| TCPIP_DNS_IsNameResolved | Determines if the DNS resolution is complete and provides the host IP address. |
| TCPIP_DNS_IsResolved | Determines if the DNS resolution is complete and provides the host IP address. |
| TCPIP_DNS_RemoveAll | Removes all the cached entries from DNS resolver. |
| TCPIP_DNS_RemoveEntry | Remove a hostname from the DNS Hash entry. |
| TCPIP_DNS_Resolve | Begins resolution of an address. |
| TCPIP_DNS_Send_Query | Forces resolution of an address. |
| Data Types and Constants | |
| TCPIP_DNS_EVENT_HANDLER | Notification handler that can be called when a specific entry is resolved and entry is timed out. |
| TCPIP_DNS_EVENT_TYPE | This enumeration is used to notify DNS client applications. |
| TCPIP_DNS_HANDLE | DNS client handle. |
| TCPIP_DNS_RESULT | DNS client result codes. |
| TCPIP_DNS_CLIENT_INFO | General DNS client info. |
| TCPIP_DNS_CLIENT_MODULE_CONFIG | Provides a place holder for DNS client configuration. |
| TCPIP_DNS_ENABLE_FLAGS | Flags for enabling the DNS service on an interface. |
| TCPIP_DNS_ENTRY_QUERY | DNS module query data for both IPv4 and IPv6 . |
| TCPIP_DNS_RESOLVE_TYPE | DNS query record type. |
| TCPIP_DNS_CLIENT_ADDRESS_TYPE | This parameter can be used to choose ithe type of IP connection for the DNS client: IPv4 or IPv6. Currently only IPv4 is supported and this parameter is not used. Reserved for future development |
| TCPIP_DNS_CLIENT_CACHE_DEFAULT_TTL_VAL | Default TTL time for a solved entry in the cache This value will be used when the DNS server TTL value for an entry is 0 |
| TCPIP_DNS_CLIENT_CACHE_ENTRIES | Number of DNS resolver entries |
| TCPIP_DNS_CLIENT_CACHE_ENTRY_TMO | DNS client cache entry time-out. If this symbol is zero then the entry time-out will be the one specified by the DNS server when the name was solved. Otherwise this value will be used as the cache entry time-out. Default should be 0. |
| TCPIP_DNS_CLIENT_CACHE_PER_IPV4_ADDRESS | Maximum and default number of IPv4 answers to be considered while processing DNS response from server for a query. |
| TCPIP_DNS_CLIENT_CACHE_PER_IPV6_ADDRESS | Maximum and default number of IPv6 answers to be considered while processing DNS response from server for a query. |
| TCPIP_DNS_CLIENT_CACHE_UNSOLVED_ENTRY_TMO | Time-out for the a unsolved name, in seconds. The name resolution will be aborted if the TMO elapsed and the name could not be solved Should be greater than TCPIP_DNS_CLIENT_LOOKUP_RETRY_TMO |
| TCPIP_DNS_CLIENT_LOOKUP_RETRY_TMO | Retry lookup for a unsolved entry in the cache, in seconds. If the TCPIP_DNS_CLIENT_LOOKUP_RETRY_TMO seconds elapsed and the name has not been solved then the name entry will be marked with server timeout and the resolution will be retried. Should be less than TCPIP_DNS_CLIENT_CACHE_UNSOLVED_ENTRY_TMO |
| TCPIP_DNS_CLIENT_MAX_HOSTNAME_LEN | Max DNS host name size Use an appropriate value, depending on the names that need to be solved |
| TCPIP_DNS_CLIENT_MAX_SELECT_INTERFACES | Max number of interfaces to take part in the DNS selection algorithm Should be always greater than 1: |
| the | default interface should always be considered for DNS resolution |
| Depending | on how many active interfaces select those to be considered for DNS resolution |
| TCPIP_DNS_CLIENT_SERVER_TMO | When the DNS Client connected to the DNS Server this is the elapsed time after which an the communication is considered to have timed failed if there was no reply from the server In seconds |
| TCPIP_DNS_CLIENT_TASK_PROCESS_RATE | DNS Client task processing rate, in milliseconds. The DNS Client module will process a timer event with this rate for processing its own state machine, etc. The default value is 200 milliseconds. The lower the rate (higher the frequency) the higher the module priority and higher module performance can be obtained The value cannot be lower than the TCPIP_STACK_TICK_RATE. |
| TCPIP_DNS_CLIENT_USER_NOTIFICATION | allow DNS client user notification if enabled, the TCPIP_DNS_HandlerRegister/TCPIP_DNS_HandlerDeRegister functions exist and can be used |