wget2: DNS resolver functions

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Functions
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_cache * | wget_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] | dns | Pointer 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] | dns | The wget_dns instance to set the timeout
  [in] | timeout | The 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] | dns | A `wget_dns` instance, created by wget_dns_init().
  [in] | cache | A `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] | dns | A `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] | ip | IP address of name
  [in] | name | Domain name, part of the cache's lookup key
  [in] | port | Port 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] | dns | A `wget_dns` instance, created by wget_dns_init().
  [in] | host | Hostname
  [in] | port | TCP destination port
  [in] | family | Protocol family AF_INET or AF_INET6
  [in] | preferred_family | Preferred 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] | dns | A `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] | dns | A `wget_dns` instance, created by wget_dns_init().
  [in] | fn | A `wget_dns_stats_callback` callback function to receive resolve statistics data
  [in] | ctx | Context data given to `fn`

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