DESCRIPTION

These functions
are used to manipulate a previously allocated and
initialized context, see getdns_context (3) for more details
on the functions used to allocate, initialized and destroy
contexts and for a more detailed discussion of the
getdns_context in general.

getdns_context_set_append_name
Specifies whether to append a suffix supplied via
getdns_context_set_suffix (3) to the query string before the
API starts resolving a name.

getdns_context_set_context_update_callback
sets a function that will be called if changes to the system
files (for example /etc/resolv.conf and /etc/hosts).

getdns_context_set_dns_transport
specifies the transport used for DNS lookups, the default is
to use UDP and fall back to TCP as needed.

getdns_context_set_dnssec_trust_anchors
allows the caller to specify trust anchors as alternatives
to the default trust anchors

getdns_context_set_dnssec_allowed_skew
set the number of seconds skew allowed in either direction
when checking an RRSIGs expiration and inception fields, the
default is 0.

getdns_context_set_limit_outstanding_queries
specifies the maximum number of outstanding DNS queries, the
API will queue queries over this limit until current queries
are answers and will then automatically issue the queries on
the queue.

getdns_context_set_dns_root_servers
provides an alternate set of addresses to use to look up the
top level domains. The default (if this function is not
called) is the list of IANA root servers (think of this as
the root hints).

getdns_context_set_follow_redirects
specifies whether or not DNS queries follow redirects (CNAME
and DNAME), the default behavior is to follow redirects and
return the eventual target.

getdns_context_set_namespaces
sets the namespaces to be used by the resolver, the default
is DNS and then local files. Future implementations will
support netbios, mdns, and nis.

getdns_context_set_resolution_type
specifies whether DNS queries are performed with
non-recursive lookups or as a stub resolver.

getdns_context_set_suffix
Append suffixes to domain names prior to executing the
lookup based on getdns_context_set_append_name.

getdns_context_set_timeout
specifies the number of milliseconds the API will wait for a
response.

context

a previously allocated and
initialized getdns_context

callback

a callback function that will be called when changes are
made

to the system files
(/etc/resolv.conf and /etc/hosts) for contexts created with
set_from_os = 1. When this function is called the
changed_item parameter indicates which item in the context
has changed.

root_addresses

This is a list of getdns_dict
types that each identify a

single root server to use to
look up top level domains. Each dictionary includes two
names, address_type , a bindata containing the string
"IPv4" or "IPv6" and address_data
a bindata containing the IP address.

transport

may be one of
GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP,

GETDNS_CONTEXT_UDP_ONLY,
GETDNS_CONTEXT_TCP_ONLY,
GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need
more information on what each of these means reread the
mnemonic and take a guess ;)

followredir

If set to
GETDNS_REDIRECTS_FOLLOW (the default) then the

eventual target of the redirect
is returned. If set to GETDNS_REDIRECTS_DO_NOT_FOLLOW then
the CNAME or DNAME is returned and NOT the eventual
target.

limit

the maximum number of concurrent
outstanding (unanswered) DNS

queries, if exceeded the API
will queue queries and issue them as the number of
outstanding queries drops. A value of 0 indicates that there
is no limit.

namespaces

The namespaces array contains an
ordered list of namespaces

that will be queried.
Important: this context setting is ignored for the
getdns_general and getdns_general_sync functions; it is used
for the other functions. The values are
GETDNS_CONTEXT_NAMESPACE_DNS,
GETDNS_CONTEXT_NAMESPACE_LOCALNAMES,
GETDNS_CONTEXT_NAMESPACE_NETBIOS,
GETDNS_CONTEXT_NAMESPACE_MDNS, and
GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done,
the API does the lookups in the order given and stops when
it gets the first result; a different method with the same
result would be to run the queries in parallel and return
when it gets the first result. Because lookups might be done
over different mechanisms because of the different
namespaces, there can be information leakage that is similar
to that seen with getaddrinfo(). The default is determined
by the OS.

restype

can be set to either
GETDNS_CONTEXT_RECURSIVE (the default) or

GETDNS_CONTEXT_STUB (requires
that forwarders be specified by the caller).

seconds_skew

the number of seconds skew
allowed in either direction

when checking an RRSIGs
expiration and inception fields.

suffixes

A list of bindatas that are
strings that are to be appended

based on
getdns_context_set_append_name. The values here follow the
rules in section 2.1 of RFC 4343 to allow non-ASCII octets
and special characters in labels.

timeout

the number of milliseconds the
API will wait for a response,

after which the callback will
be invoked (or the synchronous function will return) with a
timeout error.

trust_anchors

list of bindatas that are the
DNSSEC trust anchors

expressed as RDATA from the
DNSKEY resource records, the default are supplied by the
IANA root.

when_to_append

The value is

•

GETDNS_APPEND_NAME_ALWAYS,

•

GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,

•

GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE,
or

•

GETDNS_APPEND_NAME_NEVER.

RETURN VALUES

Upon successful
completion the functions return GETDNS_RETURN_GOOD ,
otherwise the following error values are returned:

GETDNS_RETURN_BAD_CONTEXT
if the context pointer is invalid

GETDNS_RETURN_CONTEXT_UPDATE_FAIL
if there was a problem updating the context