CTL_STATUS_t ctl_dns_get_host_by_name(const char *hostname,
                                      CTL_NET_IPv4_ADDR_t *addr,
                                      CTL_TIME_t timeout);

ctl_dns_get_host_by_name writes the IP address of the host hostname into the address pointed to by ip_addr. If ms is zero this is a non-blocking lookup otherwise it is a blocking lookup.

The host name is validated and, if invalid, ctl_dns_get_host_by_name returns CTL_DNS_HOST_NAME_ERROR. If the network is not yet up (for instance, the network library has not received an IP address from a static configuration or by DHCP), ctl_dns_get_host_by_name returns CTL_NET_NOT_UP.

If the host address is in the DNS cache maintained by the network library, the address is written to ip_addr immediately and ctl_dns_get_host_by_name returns CTL_NO_ERROR.

If the host address is not in the DNS cache, the network library queues a DNS lookup. If this is a non-blocking call (i.e. ms is zero) then ctl_dns_get_host_by_name immediately returns the non-fatal status CTL_DNS_RESOLVE_IN_PROGRESS.

If this is a blocking call, ctl_dns_get_host_by_name waits for a response. If no response is received from a DNS server within timeout milliseconds, or all DNS servers are queried and time out, ctl_dns_get_host_by_name returns CTL_DNS_NAME_UNKNOWN.

Return Value

ctl_dns_get_host_by_name returns a standard status code.

Thread Safety

ctl_dns_get_host_by_name is thread-safe.