wget2  2.0.0
DNS resolver functions

Data Structures

struct  wget_dns_stats_data
 
struct  wget_dns_st
 

Functions

int wget_dns_init (wget_dns **dns)
 
void wget_dns_free (wget_dns **dns)
 
void wget_dns_set_timeout (wget_dns *dns, int timeout)
 
void wget_dns_set_cache (wget_dns *dns, wget_dns_cache *cache)
 
wget_dns_cachewget_dns_get_cache (wget_dns *dns)
 
int wget_dns_cache_ip (wget_dns *dns, const char *ip, const char *name, uint16_t port)
 
struct addrinfo * wget_dns_resolve (wget_dns *dns, const char *host, uint16_t port, int family, int preferred_family)
 
void wget_dns_freeaddrinfo (wget_dns *dns, struct addrinfo **addrinfo)
 
void wget_dns_set_stats_callback (wget_dns *dns, wget_dns_stats_callback *fn, void *ctx)
 

Detailed Description

DNS Resolver functions.

Function Documentation

◆ wget_dns_init()

int wget_dns_init ( wget_dns **  dns)
Parameters
[out]dnsPointer to return newly allocated and initialized wget_dns instance
Returns
WGET_E_SUCCESS if OK, WGET_E_MEMORY if out-of-memory or WGET_E_INVALID if the mutex initialization failed.

Allocates and initializes a wget_dns instance.

◆ wget_dns_free()

void wget_dns_free ( wget_dns **  dns)
Parameters
[in/out]dns Pointer to wget_dns instance that will be freed and NULLified.

Free the resources allocated by wget_dns_init().

◆ wget_dns_set_timeout()

void wget_dns_set_timeout ( wget_dns dns,
int  timeout 
)
Parameters
[in]dnsThe wget_dns instance to set the timeout
[in]timeoutThe timeout value.

Set the timeout (in milliseconds) for the DNS queries.

This is the maximum time to wait until we get a response from the server.

Warning: For standard getaddrinfo() a timeout can't be set in a portable way. So this functions currently is a no-op.

The following two values are special:

  • 0: No timeout, immediate.
  • -1: Infinite timeout. Wait indefinitely.

◆ wget_dns_set_cache()

void wget_dns_set_cache ( wget_dns dns,
wget_dns_cache cache 
)
Parameters
[in]dnsA wget_dns instance, created by wget_dns_init().
[in]cacheA wget_dns_cache instance

Enable or disable DNS caching for the DNS instance provided.

The DNS cache is kept internally in memory, and is used in wget_dns_resolve() to speed up DNS queries.

◆ wget_dns_get_cache()

wget_dns_cache* wget_dns_get_cache ( wget_dns dns)
Parameters
[in]dnsA wget_dns instance, created by wget_dns_init().
Returns
1 if DNS caching is enabled, 0 otherwise.

Tells whether DNS caching is enabled or not.

You can enable and disable DNS caching with wget_dns_set_caching().

◆ wget_dns_cache_ip()

int wget_dns_cache_ip ( wget_dns dns,
const char *  ip,
const char *  name,
uint16_t  port 
)
Parameters
[in]ipIP address of name
[in]nameDomain name, part of the cache's lookup key
[in]portPort number, part of the cache's lookup key
Returns
0 on success, < 0 on error

Assign an IP address to the name+port key in the DNS cache. The name should be lowercase.

◆ wget_dns_resolve()

struct addrinfo* wget_dns_resolve ( wget_dns dns,
const char *  host,
uint16_t  port,
int  family,
int  preferred_family 
)
Parameters
[in]dnsA wget_dns instance, created by wget_dns_init().
[in]hostHostname
[in]portTCP destination port
[in]familyProtocol family AF_INET or AF_INET6
[in]preferred_familyPreferred protocol family AF_INET or AF_INET6
Returns
A struct addrinfo structure (defined in libc's <netdb.h>). Must be freed by the caller with wget_dns_freeaddrinfo().

Resolve a host name into its IPv4/IPv6 address.

family: Desired address family for the returned addresses. This will typically be AF_INET or AF_INET6, but it can be any of the values defined in <socket.h>. Additionally, AF_UNSPEC means you don't care: it will return any address family that can be used with the specified host and port. If family is different than AF_UNSPEC and the specified family is not found, that's an error condition and thus wget_dns_resolve() will return NULL.

preferred_family: Tries to resolve addresses of this family if possible. This is only honored if family (see point above) is AF_UNSPEC.

The returned addrinfo structure must be freed with wget_dns_freeaddrinfo().

◆ wget_dns_freeaddrinfo()

void wget_dns_freeaddrinfo ( wget_dns dns,
struct addrinfo **  addrinfo 
)
Parameters
[in]dnsA wget_dns instance, created by wget_dns_init().
[in/out]addrinfo Value returned by c

Release addrinfo, previously returned by wget_dns_resolve(). If the underlying dns uses caching, just the reference/pointer is set to NULL.

◆ wget_dns_set_stats_callback()

void wget_dns_set_stats_callback ( wget_dns dns,
wget_dns_stats_callback *  fn,
void *  ctx 
)
Parameters
[in]dnsA wget_dns instance, created by wget_dns_init().
[in]fnA wget_dns_stats_callback callback function to receive resolve statistics data
[in]ctxContext data given to fn

Set callback function to be called once DNS statistics for a host are collected