Creating, destroying, configuring and reading configuration from getdns_contexts

Macros

#define GETDNS_LOG_EMERG_TEXT   "System is unusable"
 
#define GETDNS_LOG_ALERT_TEXT   "Action must be taken immediately"
 
#define GETDNS_LOG_CRIT_TEXT   "Critical conditions"
 
#define GETDNS_LOG_ERR_TEXT   "Error conditions"
 
#define GETDNS_LOG_WARNING_TEXT   "Warning conditions"
 
#define GETDNS_LOG_NOTICE_TEXT   "Normal, but significant, condition"
 
#define GETDNS_LOG_INFO_TEXT   "Informational message"
 
#define GETDNS_LOG_DEBUG_TEXT   "Debug-level message"
 
#define GETDNS_LOG_UPSTREAM_STATS   4096
 
#define GETDNS_LOG_UPSTREAM_STATS_TEXT   "Log messages about upstream statistics"
 

Typedefs

typedef enum getdns_loglevel_type getdns_loglevel_type
 
typedef void(* getdns_logfunc_type) (void *userarg, uint64_t log_systems, getdns_loglevel_type, const char *, va_list ap)
 

Enumerations

enum  getdns_loglevel_type {
  GETDNS_LOG_EMERG = 0, GETDNS_LOG_ALERT = 1, GETDNS_LOG_CRIT = 2, GETDNS_LOG_ERR = 3,
  GETDNS_LOG_WARNING = 4, GETDNS_LOG_NOTICE = 5, GETDNS_LOG_INFO = 6, GETDNS_LOG_DEBUG = 7
}
 

Functions

getdns_return_t getdns_context_create (getdns_context **context, int set_from_os)
 
getdns_return_t getdns_context_create_with_memory_functions (getdns_context **context, int set_from_os, void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *))
 
getdns_return_t getdns_context_create_with_extended_memory_functions (getdns_context **context, int set_from_os, void *userarg, void *(*malloc)(void *userarg, size_t), void *(*realloc)(void *userarg, void *, size_t), void(*free)(void *userarg, void *))
 
void getdns_context_destroy (getdns_context *context)
 
getdns_return_t getdns_context_set_context_update_callback (getdns_context *context, void(*value)(getdns_context *context, getdns_context_code_t changed_item))
 
getdns_return_t getdns_context_set_resolution_type (getdns_context *context, getdns_resolution_t value)
 
getdns_return_t getdns_context_set_namespaces (getdns_context *context, size_t namespace_count, getdns_namespace_t *namespaces)
 
getdns_return_t getdns_context_set_dns_transport (getdns_context *context, getdns_transport_t value)
 
getdns_return_t getdns_context_set_dns_transport_list (getdns_context *context, size_t transport_count, getdns_transport_list_t *transports)
 
getdns_return_t getdns_context_set_idle_timeout (getdns_context *context, uint64_t timeout)
 
getdns_return_t getdns_context_set_limit_outstanding_queries (getdns_context *context, uint16_t limit)
 
getdns_return_t getdns_context_set_timeout (getdns_context *context, uint64_t timeout)
 
getdns_return_t getdns_context_set_follow_redirects (getdns_context *context, getdns_redirects_t value)
 
getdns_return_t getdns_context_set_dns_root_servers (getdns_context *context, getdns_list *addresses)
 
getdns_return_t getdns_context_set_append_name (getdns_context *context, getdns_append_name_t value)
 
getdns_return_t getdns_context_set_suffix (getdns_context *context, getdns_list *value)
 
getdns_return_t getdns_context_set_dnssec_trust_anchors (getdns_context *context, getdns_list *value)
 
getdns_return_t getdns_context_set_dnssec_allowed_skew (getdns_context *context, uint32_t value)
 
getdns_return_t getdns_context_set_upstream_recursive_servers (getdns_context *context, getdns_list *upstream_list)
 
getdns_return_t getdns_context_set_edns_maximum_udp_payload_size (getdns_context *context, uint16_t value)
 
getdns_return_t getdns_context_set_edns_extended_rcode (getdns_context *context, uint8_t value)
 
getdns_return_t getdns_context_set_edns_version (getdns_context *context, uint8_t value)
 
getdns_return_t getdns_context_set_edns_do_bit (getdns_context *context, uint8_t value)
 
getdns_return_t getdns_context_set_memory_functions (getdns_context *context, void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *))
 
getdns_return_t getdns_context_set_extended_memory_functions (getdns_context *context, void *userarg, void *(*malloc)(void *userarg, size_t sz), void *(*realloc)(void *userarg, void *ptr, size_t sz), void(*free)(void *userarg, void *ptr))
 
getdns_return_t getdns_context_set_update_callback (getdns_context *context, void *userarg, void(*value)(getdns_context *, getdns_context_code_t, void *))
 
getdns_return_t getdns_context_set_return_dnssec_status (getdns_context *context, int enabled)
 
getdns_return_t getdns_context_set_tls_authentication (getdns_context *context, getdns_tls_authentication_t value)
 
getdns_return_t getdns_context_set_round_robin_upstreams (getdns_context *context, uint8_t value)
 
getdns_return_t getdns_context_set_tls_backoff_time (getdns_context *context, uint16_t value)
 
getdns_return_t getdns_context_set_tls_connection_retries (getdns_context *context, uint16_t value)
 
getdns_return_t getdns_context_set_edns_client_subnet_private (getdns_context *context, uint8_t value)
 
getdns_return_t getdns_context_set_tls_query_padding_blocksize (getdns_context *context, uint16_t value)
 
getdns_return_t getdns_context_unset_edns_maximum_udp_payload_size (getdns_context *context)
 
getdns_return_t getdns_context_set_logfunc (getdns_context *context, void *userarg, uint64_t system, getdns_loglevel_type level, getdns_logfunc_type func)
 
getdns_return_t getdns_context_set_appdata_dir (getdns_context *context, const char *appdata_dir)
 
getdns_return_t getdns_context_set_trust_anchors_url (getdns_context *context, const char *url)
 
getdns_return_t getdns_context_set_trust_anchors_verify_CA (getdns_context *context, const char *verify_CA)
 
getdns_return_t getdns_context_set_trust_anchors_verify_email (getdns_context *context, const char *verify_email)
 
getdns_return_t getdns_context_set_resolvconf (getdns_context *context, const char *resolvconf)
 
getdns_return_t getdns_context_set_hosts (getdns_context *context, const char *hosts)
 
getdns_return_t getdns_context_set_tls_ca_path (getdns_context *context, const char *tls_ca_path)
 
getdns_return_t getdns_context_set_tls_ca_file (getdns_context *context, const char *tls_ca_file)
 
getdns_return_t getdns_context_set_tls_cipher_list (getdns_context *context, const char *cipher_list)
 
getdns_return_t getdns_context_set_tls_curves_list (getdns_context *context, const char *curves_list)
 
getdns_return_t getdns_context_get_resolution_type (getdns_context *context, getdns_resolution_t *value)
 
getdns_return_t getdns_context_get_namespaces (getdns_context *context, size_t *namespace_count, getdns_namespace_t **namespaces)
 
getdns_return_t getdns_context_get_dns_transport (getdns_context *context, getdns_transport_t *value)
 
getdns_return_t getdns_context_get_dns_transport_list (getdns_context *context, size_t *transport_count, getdns_transport_list_t **transports)
 
getdns_return_t getdns_context_get_limit_outstanding_queries (getdns_context *context, uint16_t *limit)
 
getdns_return_t getdns_context_get_timeout (getdns_context *context, uint64_t *timeout)
 
getdns_return_t getdns_context_get_idle_timeout (getdns_context *context, uint64_t *timeout)
 
getdns_return_t getdns_context_get_follow_redirects (getdns_context *context, getdns_redirects_t *value)
 
getdns_return_t getdns_context_get_dns_root_servers (getdns_context *context, getdns_list **addresses)
 
getdns_return_t getdns_context_get_append_name (getdns_context *context, getdns_append_name_t *value)
 
getdns_return_t getdns_context_get_suffix (getdns_context *context, getdns_list **value)
 
getdns_return_t getdns_context_get_dnssec_trust_anchors (getdns_context *context, getdns_list **value)
 
getdns_return_t getdns_context_get_dnssec_allowed_skew (getdns_context *context, uint32_t *value)
 
getdns_return_t getdns_context_get_upstream_recursive_servers (getdns_context *context, getdns_list **upstream_list)
 
getdns_return_t getdns_context_get_edns_maximum_udp_payload_size (getdns_context *context, uint16_t *value)
 
getdns_return_t getdns_context_get_edns_extended_rcode (getdns_context *context, uint8_t *value)
 
getdns_return_t getdns_context_get_edns_version (getdns_context *context, uint8_t *value)
 
getdns_return_t getdns_context_get_edns_do_bit (getdns_context *context, uint8_t *value)
 
getdns_return_t getdns_context_get_edns_client_subnet_private (getdns_context *context, uint8_t *value)
 
getdns_return_t getdns_context_get_tls_query_padding_blocksize (getdns_context *context, uint16_t *value)
 
getdns_return_t getdns_context_get_tls_authentication (getdns_context *context, getdns_tls_authentication_t *value)
 
getdns_return_t getdns_context_get_round_robin_upstreams (getdns_context *context, uint8_t *value)
 
getdns_return_t getdns_context_get_tls_backoff_time (getdns_context *context, uint16_t *value)
 
getdns_return_t getdns_context_get_tls_connection_retries (getdns_context *context, uint16_t *value)
 
getdns_return_t getdns_context_get_update_callback (getdns_context *context, void **userarg, void(**value)(getdns_context *, getdns_context_code_t, void *))
 
getdns_return_t getdns_context_get_trust_anchors_url (getdns_context *context, const char **url)
 
getdns_return_t getdns_context_get_trust_anchors_verify_CA (getdns_context *context, const char **verify_CA)
 
getdns_return_t getdns_context_get_trust_anchors_verify_email (getdns_context *context, const char **verify_email)
 
getdns_return_t getdns_context_get_resolvconf (getdns_context *context, const char **resolvconf)
 
getdns_return_t getdns_context_get_hosts (getdns_context *context, const char **hosts)
 
getdns_return_t getdns_context_get_tls_ca_path (getdns_context *context, const char **tls_ca_path)
 
getdns_return_t getdns_context_get_tls_ca_file (getdns_context *context, const char **tls_ca_file)
 
getdns_return_t getdns_context_get_tls_cipher_list (getdns_context *context, const char **cipher_list)
 
getdns_return_t getdns_context_get_tls_curves_list (getdns_context *context, const char **curves_list)
 
getdns_return_t getdns_context_config (getdns_context *context, const getdns_dict *config_dict)
 

Detailed Description

Macro Definition Documentation

◆ GETDNS_LOG_EMERG_TEXT

#define GETDNS_LOG_EMERG_TEXT   "System is unusable"

Definition at line 534 of file getdns_extra.h.

◆ GETDNS_LOG_ALERT_TEXT

#define GETDNS_LOG_ALERT_TEXT   "Action must be taken immediately"

Definition at line 535 of file getdns_extra.h.

◆ GETDNS_LOG_CRIT_TEXT

#define GETDNS_LOG_CRIT_TEXT   "Critical conditions"

Definition at line 536 of file getdns_extra.h.

◆ GETDNS_LOG_ERR_TEXT

#define GETDNS_LOG_ERR_TEXT   "Error conditions"

Definition at line 537 of file getdns_extra.h.

◆ GETDNS_LOG_WARNING_TEXT

#define GETDNS_LOG_WARNING_TEXT   "Warning conditions"

Definition at line 538 of file getdns_extra.h.

◆ GETDNS_LOG_NOTICE_TEXT

#define GETDNS_LOG_NOTICE_TEXT   "Normal, but significant, condition"

Definition at line 539 of file getdns_extra.h.

◆ GETDNS_LOG_INFO_TEXT

#define GETDNS_LOG_INFO_TEXT   "Informational message"

Definition at line 540 of file getdns_extra.h.

◆ GETDNS_LOG_DEBUG_TEXT

#define GETDNS_LOG_DEBUG_TEXT   "Debug-level message"

Definition at line 541 of file getdns_extra.h.

◆ GETDNS_LOG_UPSTREAM_STATS

#define GETDNS_LOG_UPSTREAM_STATS   4096

Definition at line 543 of file getdns_extra.h.

◆ GETDNS_LOG_UPSTREAM_STATS_TEXT

#define GETDNS_LOG_UPSTREAM_STATS_TEXT   "Log messages about upstream statistics"

Definition at line 544 of file getdns_extra.h.

Typedef Documentation

◆ getdns_loglevel_type

◆ getdns_logfunc_type

typedef void(* getdns_logfunc_type) (void *userarg, uint64_t log_systems, getdns_loglevel_type, const char *, va_list ap)

Definition at line 546 of file getdns_extra.h.

Enumeration Type Documentation

◆ getdns_loglevel_type

Enumerator
GETDNS_LOG_EMERG 
GETDNS_LOG_ALERT 
GETDNS_LOG_CRIT 
GETDNS_LOG_ERR 
GETDNS_LOG_WARNING 
GETDNS_LOG_NOTICE 
GETDNS_LOG_INFO 
GETDNS_LOG_DEBUG 

Definition at line 523 of file getdns_extra.h.

Function Documentation

◆ getdns_context_create()

getdns_return_t getdns_context_create ( getdns_context **  context,
int  set_from_os 
)

creates a new getdns context with default settings. If used multi-threaded, user must define appropriate OpenSSL callback locking functions (e.g. CRYPTO_THREADID_set_call) depending on the library version used.

Parameters
contextcontext that can be used immediately with other API calls
set_from_osset to 1 to initialize the context with os defaults
Returns
GETDNS_RETURN_GOOD on success

◆ getdns_context_create_with_memory_functions()

getdns_return_t getdns_context_create_with_memory_functions ( getdns_context **  context,
int  set_from_os,
void *(*)(size_t)  malloc,
void *(*)(void *, size_t)  realloc,
void(*)(void *)  free 
)

creates a new getdns context with default settings using custom memory functions. If used multi-threaded, user must define appropriate OpenSSL callback locking functions (e.g. CRYPTO_THREADID_set_call) depending on the library version used.

Parameters
contextcontext that can be used immediately with other API calls
set_from_osset to 1 to initialize the context with os defaults
malloccustom malloc function
realloccustom realloc function
freecustom free function
Returns
GETDNS_RETURN_GOOD on success

◆ getdns_context_create_with_extended_memory_functions()

getdns_return_t getdns_context_create_with_extended_memory_functions ( getdns_context **  context,
int  set_from_os,
void *  userarg,
void *(*)(void *userarg, size_t)  malloc,
void *(*)(void *userarg, void *, size_t)  realloc,
void(*)(void *userarg, void *)  free 
)

creates a new getdns context with default settings using extended custom memory functions. If used multi-threaded, user must define appropriate OpenSSL callback locking functions (e.g. CRYPTO_THREADID_set_call) depending on the library version used.

Parameters
contextcontext that can be used immediately with other API calls
set_from_osset to 1 to initialize the context with os defaults
userargparameter passed to the custom malloc, realloc and free functions
malloccustom malloc function
realloccustom realloc function
freecustom free function
Returns
GETDNS_RETURN_GOOD on success

◆ getdns_context_destroy()

void getdns_context_destroy ( getdns_context context)

destroy the context. All outstanding requests will be cancelled with the getdns_cancel_callback() function.

◆ getdns_context_set_context_update_callback()

getdns_return_t getdns_context_set_context_update_callback ( getdns_context context,
void(*)(getdns_context *context, getdns_context_code_t changed_item)  value 
)

An application can be notified when the context is changed. Note that this implementation has an extended version of this function in which an additional userarg parameter can be registered: getdns_context_set_update_callback .

See also
Context code values and texts
Parameters
contextThe context for which to monitor changes
valueThe callback function that will be called when any context is changed. A update callback function can be deregistered by passing NULL.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_resolution_type()

getdns_return_t getdns_context_set_resolution_type ( getdns_context context,
getdns_resolution_t  value 
)

Specify whether DNS queries are performed with recursive lookups or as a stub resolver. The default value is GETDNS_RESOLUTION_RECURSING.

See also
getdns_context_get_resolution_type
Resolution types and texts
Parameters
contextThe context to configure
valueGETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown resolution types
GETDNS_RETURN_NOT_IMPLEMENTED when getdns was compiled for stub resolution only and recursing resolution type was requested.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_namespaces()

getdns_return_t getdns_context_set_namespaces ( getdns_context context,
size_t  namespace_count,
getdns_namespace_t namespaces 
)

Sets the ordered list of namespaces that will be queried. This context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other funtions. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result

See also
getdns_context_get_namespaces
Namespace types and texts
Parameters
contextThe context to configure
namespace_countThe number of values in the namespaces list.
namespacesAn ordered list of namespaces that will be queried. The values are: GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES, GETDNS_NAMESPACE_NETBIOS, GETDNS_NAMESPACE_MDNS, and GETDNS_NAMESPACE_NIS.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown namespace types
GETDNS_RETURN_NOT_IMPLEMENTED when unsupported namespaces were given. Currently this implementation supports only GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES and has an draft implementation of GETDNS_NAMESPACE_MDNS, which has to be enabled at configure time.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_dns_transport()

getdns_return_t getdns_context_set_dns_transport ( getdns_context context,
getdns_transport_t  value 
)

Specifies what transport are used for DNS lookups. The default is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP. Use of this function is discouraged. Please use getdns_context_set_dns_transport_list() instead of this function.

See also
getdns_context_get_dns_transport
Transport arrangements and texts
getdns_context_set_dns_transport_list
Parameters
contextThe context to configure
valueThe transport to use for DNS lookups. The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP, GETDNS_TRANSPORT_UDP_ONLY, GETDNS_TRANSPORT_TCP_ONLY, GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN, GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN or GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_dns_transport_list()

getdns_return_t getdns_context_set_dns_transport_list ( getdns_context context,
size_t  transport_count,
getdns_transport_list_t transports 
)

Specifies what transport is used for DNS lookups. The default is a list containing GETDNS_TRANSPORT_UDP then GETDNS_TRANSPORT_TCP. The API will return information on the actual transport used to fulfill the request in the response dict, when the return_call_reporting extension is used.

See also
getdns_context_get_dns_transport_list
Transport list values and tests
getdns_context_set_dns_transport
Parameters
contextThe context to configure
transport_countThe number of values in the transports list.
transportsAn ordered list of transports that will be used for DNS lookups. If only one transport value is specified it will be the only transport used. Should it not be available basic resolution will fail. Fallback transport options are specified by including multiple values in the list. The values are: GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP, or GETDNS_TRANSPORT_TLS
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_idle_timeout()

getdns_return_t getdns_context_set_idle_timeout ( getdns_context context,
uint64_t  timeout 
)

Specify number of milliseconds the API will leave an idle TCP or TLS connection open for (idle means no outstanding responses and no pending queries). When set to 0, all currently open idle connections will be closed immediately. The default is 0. Note with synchronous queries, idle connections can not reliably be timed. Each new synchronous request, will reset the counter no matter the time in between requests, and thus leave the connection open always. This setting is thus only meaningful when doing requests asynchronously.

See also
getdns_context_get_idle_timeout
Parameters
contextThe context to configure
timeoutThe number of milliseconds the API will leave an idle TCP or TLS connection open for
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_limit_outstanding_queries()

getdns_return_t getdns_context_set_limit_outstanding_queries ( getdns_context context,
uint16_t  limit 
)

Limit the number of outstanding DNS queries. When more than limit requests are scheduled, they are kept on an internal queue, to be rescheduled when the number of outstanding queries drops below the limit again. A value of 0 indicates that the number of outstanding DNS queries is unlimited, however, queries will be put on the internal queue too when system resources are exhausted (i.e. number of available sockets). The default value is 0.

See also
getdns_context_get_limit_outstanding_queries
Parameters
contextThe context to configure
limitThe maximum number of outstanding DNS queries.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_timeout()

getdns_return_t getdns_context_set_timeout ( getdns_context context,
uint64_t  timeout 
)

Specifies number of milliseconds the API will wait for request to return. The default is 5000 (i.e. 5 seconds).

See also
getdns_context_get_timeout
Parameters
contextThe context to configure
timeoutThe number of milliseconds the API will wait for request to return.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER for a timeout 0, or when context was NULL

◆ getdns_context_set_follow_redirects()

getdns_return_t getdns_context_set_follow_redirects ( getdns_context context,
getdns_redirects_t  value 
)

Specifies whether or not DNS queries follow redirects. The default value is GETDNS_REDIRECTS_FOLLOW. In this implementation, redirects are only actively followed in the recursing resolution mode. The GETDNS_REDIRECTS_DO_NOT_FOLLOW will not prevent this, but the response will be stripped of all resource records that could only be found through following redirects. The setting will do this with answers provided by an upstream in stub resolution mode too.

See also
getdns_context_get_follow_redirects
Redirect policies and texts
Parameters
contextThe context to configure
valueGETDNS_REDIRECTS_FOLLOW for normal following of redirects through CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to cause any lookups that would have gone through CNAME and DNAME to return the CNAME or DNAME, not the eventual target.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER for an unknown value, or when context was NULL

◆ getdns_context_set_dns_root_servers()

getdns_return_t getdns_context_set_dns_root_servers ( getdns_context context,
getdns_list addresses 
)

Configure the list of addresses to be used for looking up top-level domains. The default is the list of "normal" IANA root servers

See also
getdns_context_get_dns_root_servers
Parameters
contextThe context to configure
addressesThe list contains dicts that are addresses to be used for looking up top-level domains. Each dict in the list contains at least two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). This implementation also accepts a list of addressxi bindatas. Or a list of rr_dicts for address records (i.e. the additional section of a NS query for ".", or a with getdns_fp2rr_list() converted root.hints file).
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_ CONTEXT_UPDATE_FAIL when there were problems parsing the provided addresses list.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_append_name()

getdns_return_t getdns_context_set_append_name ( getdns_context context,
getdns_append_name_t  value 
)

Specifies whether, how and when to append a suffix to the query string. The non-standard implementation default is GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST.

See also
getdns_context_get_append_name
Suffix appending values and texts
Parameters
contextThe context to configure
valueGETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST, 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.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_suffix()

getdns_return_t getdns_context_set_suffix ( getdns_context context,
getdns_list value 
)

Specify the list of suffixes to be appended based on the value off the append_name setting. The default is read from OS, or an empty list when the context is not initialized with OS defaults.

See also
getdns_context_get_suffix
Parameters
contextThe context to configure
valueA list of bindatas that are strings that are to be appended based on the value off the append_name setting.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_dnssec_trust_anchors()

getdns_return_t getdns_context_set_dnssec_trust_anchors ( getdns_context context,
getdns_list value 
)

Specify the DNSSEC trust anchors. The default is to read it from /etc/unbound/getdns-root.key.

See also
getdns_context_get_dnssec_trust_anchors
Parameters
contextThe context to configure
valueA list of rr_dicts for DS or DNSKEY that are the DNSSEC trust anchors.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_dnssec_allowed_skew()

getdns_return_t getdns_context_set_dnssec_allowed_skew ( getdns_context context,
uint32_t  value 
)

Specify the DNSSEC allowed skew. The default is 0.

See also
getdns_context_get_dnssec_allowed_skew
Parameters
contextThe context to configure
valueThe number of seconds of skew that is allowed in either direction when checking an RRSIG's Expiration and Inception fields.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_upstream_recursive_servers()

getdns_return_t getdns_context_set_upstream_recursive_servers ( getdns_context context,
getdns_list upstream_list 
)

Specify where a stub resolver will send queries. The default value is set from the OS when the context is created with the set_from_os flag, or empty otherwise.

See also
getdns_context_get_upstream_recursive_servers
Parameters
contextThe context to configure
upstream_listThe upstreams are specified either by a getdns_bindata containing a IPv4 or IPv6 address in network format or a getdns_dict, containing at least a name address_data whose value is the address bindata, and optionally also:
  • scode_id containing an getdns_bindata with the scope ID for IPv6 link-local addresses.
  • port an integer specifying which port to use to contact this upstream over UDP and TCP; the default is 53
  • tsig_algorithm (a bindata) that is the name of the TSIG hash algorithm
  • tsig_name (a bindata) that is the name of the TSIG key
  • tsig_secret (a bindata) that is the TSIG key
  • tls_port (a integer) that is the port to use to contact this upstream over TLS
  • tls_auth_name (a bindata) that is the name of the upstream (as a bindata containing a string) which must be verified to confirm its identity.
  • tls_pubkey_pinset (a list) containing dicts with
    • digest which must be a bindata containing the text sha256
    • value A SHA256 hash of the SubjectPublicKeyInfo of the upstream, which will be used to authenticate it.
  • tls_cipher_list (a bindata) that is the string of available ciphers specific for this upstream.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context or upstream_list was NULL
GETDNS_RETURN_CONTEXT_UPDATE_FAIL when there were problems parsing the upstream_list.

◆ getdns_context_set_edns_maximum_udp_payload_size()

getdns_return_t getdns_context_set_edns_maximum_udp_payload_size ( getdns_context context,
uint16_t  value 
)

Set the maximum UDP payload size advertised in a EDNS0 OPT record. When not set (the default), outgoing values will adhere to the suggestions in RFC 6891 and may follow a scheme that uses multiple values to maximize receptivity.

See also
getdns_context_get_edns_maximum_udp_payload_size
getdns_context_unset_edns_maximum_udp_payload_size
Parameters
contextThe context to configure
valueThe maximum UDP payload size advertised in a EDNS0 OPT record. The value must be between 512 and 65536
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_edns_extended_rcode()

getdns_return_t getdns_context_set_edns_extended_rcode ( getdns_context context,
uint8_t  value 
)

Set the rcode advertised in a EDNS0 OPT record. The default is 0.

See also
getdns_context_get_edns_extended_rcode
Parameters
contextThe context to configure
valueA value between 0 and 255.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_edns_version()

getdns_return_t getdns_context_set_edns_version ( getdns_context context,
uint8_t  value 
)

Set the version advertised in a EDNS0 OPT record. The default is 0.

See also
getdns_context_get_edns_version
Parameters
contextThe context to configure
valueA value between 0 and 255.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_edns_do_bit()

getdns_return_t getdns_context_set_edns_do_bit ( getdns_context context,
uint8_t  value 
)

Set the DO ibit advertised in a EDNS0 OPT record. The default is 0. However use of any of the dnssec_* extension will override this setting and set the DO bit.

See also
getdns_context_get_edns_do_bit
Parameters
contextThe context to configure
valueA value between 0 and 1.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_memory_functions()

getdns_return_t getdns_context_set_memory_functions ( getdns_context context,
void *(*)(size_t)  malloc,
void *(*)(void *, size_t)  realloc,
void(*)(void *)  free 
)

Specify custom memory management functions to be used with this context. The given memory management functions will be used for creating the response dicts. The response dicts inherit the custom memory management functions from the context and will deallocate themselves (and their members) with the custom deallocator. By default, the system malloc, realloc, and free are used.

Parameters
contextThe context to configure
mallocA custom memory allocator. The default is malloc.
reallocA custom memory reallocator. The default is realloc.
freeA custom memory deallocator. The default is free.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_extended_memory_functions()

getdns_return_t getdns_context_set_extended_memory_functions ( getdns_context context,
void *  userarg,
void *(*)(void *userarg, size_t sz)  malloc,
void *(*)(void *userarg, void *ptr, size_t sz)  realloc,
void(*)(void *userarg, void *ptr)  free 
)

Specify custom extended memory management functions to be used with this context. The value of userarg argument will be passed to the custom malloc, realloc, and free. The response dicts inherit the custom memory management functions from the context and will deallocate themselves (and their members) with the custom deallocator. By default, the system malloc, realloc, and free are used.

Parameters
contextThe context to configure
userargThis value will be passed as the userarg argument to the custom malloc, realloc and free function.
mallocA custom memory allocator. The default is a wrapper for malloc.
reallocA custom memory reallocator. The default is a wrapper for realloc.
freeA custom memory deallocator. The default is a wrapper for free.
Returns
GETDNS_RETURN_GOOD when successful.
GETDNS_RETURN_INVALID_PARAMETER when context was NULL

◆ getdns_context_set_update_callback()

getdns_return_t getdns_context_set_update_callback ( getdns_context context,
void *  userarg,
void(*)(getdns_context *, getdns_context_code_t, void *)  value 
)

Register a callback function for context changes.

See also
getdns_context_set_context_update_callback
Context code values and texts
Parameters
contextThe context to monitor for changes
userargA user defined argument that will be passed to the callback function.
valueThe callback function that will be called when a context value is changed. The arguments to the callback function are the context for which the value changes, a code referencing the changed value and the userarg parameter supplied during callback registration.
Returns
GETDNS_RETURN_GOOD on success or an error code on failure.

◆ getdns_context_set_return_dnssec_status()

getdns_return_t getdns_context_set_return_dnssec_status ( getdns_context context,
int  enabled 
)

Enable the return_dnssec_status extension on every request.

Parameters
contextThe context to configure
enabledis either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context or value is invalid

◆ getdns_context_set_tls_authentication()

getdns_return_t getdns_context_set_tls_authentication ( getdns_context context,
getdns_tls_authentication_t  value 
)

Configure context for oppertunistic or scrict usage profile with DNS over TLS.

See also
getdns_context_get_tls_authentication
Authentication values and texts
Parameters
contextThe context to configure
valueis either GETDNS_AUTHENTICATION_REQUIRED for the strict usage profile or GETDNS_AUTHENTICATION_NONE for opportunistic profile. See getdns_context_set_upstream_recursive_servers for details on how to configure credentials per upstream.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.

◆ getdns_context_set_round_robin_upstreams()

getdns_return_t getdns_context_set_round_robin_upstreams ( getdns_context context,
uint8_t  value 
)

Configure context to round robin queries over the available upstreams when resolving with the stub resolution type.

See also
getdns_context_get_round_robin_upstreams
Parameters
contextThe context to configure
valueis either 1 to enable and 0 to disable round robin.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.

◆ getdns_context_set_tls_backoff_time()

getdns_return_t getdns_context_set_tls_backoff_time ( getdns_context context,
uint16_t  value 
)

Configure the amount of seconds a TLS connection should not be tried with an upstream when it has never been tried before. Default is 3600 which is one hour.

See also
getdns_context_get_tls_backoff_time
Parameters
contextThe context to configure
valueNumber of seconds before an attempt to setup DNS over TLS, with an upstream for which setting up an TLS connection has never been successful before, will be retried.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null.

◆ getdns_context_set_tls_connection_retries()

getdns_return_t getdns_context_set_tls_connection_retries ( getdns_context context,
uint16_t  value 
)

Configure the number of times getdns retries to setup DNS over TLS with a specific upstream, before it decides to give up for tls_backoff_time seconds. The default is 2.

See also
getdns_context_get_tls_connection_retries
Parameters
contextThe context to configure
valueNumber of attempts to retry setting up a DNS over TLS connection before giving up.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null.

◆ getdns_context_set_edns_client_subnet_private()

getdns_return_t getdns_context_set_edns_client_subnet_private ( getdns_context context,
uint8_t  value 
)

Configure context to sent queries with the EDNS Client Subnet option set to hide the originating network when resolving in stub resolution. The default is 0 (disabled).

See also
getdns_context_get_edns_client_subnet_private
Parameters
contextThe context to configure
valueis either 1 to enable and 0 to disable.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.

◆ getdns_context_set_tls_query_padding_blocksize()

getdns_return_t getdns_context_set_tls_query_padding_blocksize ( getdns_context context,
uint16_t  value 
)

Configure context to pad each outgoing query over TLS to a multiple of the requested blocksizes. A value of 0 means disable, and a value of 1 means to "pad using a sensible policy". The default is 1 (pad using sensible policy).

See also
getdns_context_get_tls_query_padding_blocksize
Parameters
contextThe context to configure
valueThe requested block size to pad to, or 0 to disable, or 1 to indicate that the library should use a sinsible policy. Currently that just means to pad to a multiple of 128 octets for outgoing queries, but this might change in the future.
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.

◆ getdns_context_unset_edns_maximum_udp_payload_size()

getdns_return_t getdns_context_unset_edns_maximum_udp_payload_size ( getdns_context context)

Configure context to advertise maximum UDP payload size values, that adhere to the suggestions in RFC 6891 and may follow a scheme that uses multiple values to maximize receptivity. In practice with our implementation this means 1432 for IPv4 upstreams and 1232 for IPv6 upstreams. The default is to have the edns maximum UDP payload size to be unset and thus use the adaptive scheme.

See also
getdns_context_set_edns_maximum_udp_payload_size
getdns_context_get_edns_maximum_udp_payload_size
Parameters
contextThe context to configure
Returns
GETDNS_RETURN_GOOD on success
GETDNS_RETURN_INVALID_PARAMETER if context is null.

◆ getdns_context_set_logfunc()

getdns_return_t getdns_context_set_logfunc ( getdns_context context,
void *  userarg,
uint64_t  system,
getdns_loglevel_type  level,
getdns_logfunc_type  func 
)

Register a function that will be called when there is something to log equally or more severe than the given level for the given system.

Parameters
[in]contextThe context from which to get the setting
[in]userargA user defined argument to be passed to the log function.
[in]systemA bitwise ORed collection of systems for which the log function should be called. Currently only logging information about upstream statistics is available; i.e.: GETDNS_LOG_UPSTREAM_STATS
[in]levelA severity level. The log function will be called only for messages with an equal or more severe level. More severe has a lower value.
[in]funcThe log function to call with the user argument, the system for which the log message, the severity level, a printf style format string and the arguments for the format string, as parameter.
See also
getdns_loglevel_type
getdns_logfunc_type
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_appdata_dir()

getdns_return_t getdns_context_set_appdata_dir ( getdns_context context,
const char *  appdata_dir 
)

Define the location for storing library specific data. The location should be writable for the current user using the application with which the library is linked. Currently this is only used for storing data concerning zero configuration dnssec.

Parameters
[in]contextThe context from which to get the setting
[in]appdata_dirA user writable location in which the library can store data. The last element of the path is tried to be created if it does not exist. When NULL is given, the default location is used which is ${HOME}/.getdns/ on Unix line systems (Linux, BSD's, MacOS), and AppData%\ on Windows.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_trust_anchors_url()

getdns_return_t getdns_context_set_trust_anchors_url ( getdns_context context,
const char *  url 
)

Sets the url for the location of the XML file from which to fetch the trust anchors with Zero configuration DNSSEC. The url should be for http, and the file should have the .xml extension.

Alongside the XML file, also the S/MIME signature that will be used to validate the XML file, will be fetched from the url with the .xml extension replaced by .p7s.

When successfully validated with the verify Certificate Authority and the verify email address, the context will be equipped with the DNSSEC trust anchors defined within the XML file as described in RFC7958. The XML file will also be stored together with the .p7s file in the appdata directory with the names "root-anchors.xml" and "root-anchors.p7s" respectively.

When the trust-anchors from the XML file are used, the root DNSKEY is tracked and stored in the appdata directory too as "root.key"

Trust anchors from the XML file will be tried when:

  • There were no other trust anchors provided, either by the default trust anchor file "/etc/unbound/getdns-root.key", or set with the getdns_context_set_dnssec_trust_anchors() function.
  • or the available trust anchors (from the default location or set by the application) caused the root DNSKEY rrset to be BOGUS.

Trust anchors from the XML file will be read from the root-anchors.xml file in appdata directory and will only be used when validation with the S/MIME signatures in root-anchors.p7s succeeds with the verification Certificate Authority and the verification email address.

A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be fetched when:

  • The appdata directory is writeable by the current used, but the "root-anchors.xml" or "root-anchors.p7s" files were not available.
  • or there is a new root DNSKEY RRset (or signature) and it contains key_ids which were not in "root-anchors.xml."
See also
getdns_context_get_trust_anchors_url
getdns_context_set_trust_anchors_verify_CA
getdns_context_set_trust_anchors_verify_email
Parameters
[in]contextThe context to configure
[in]urlThe url including the XML file from which the trust anchors (and the S/MIME signature) will be fetched. Default is: http://data.iana.org/root-anchors/root-anchors.xml When NULL is given, the default will be used.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_trust_anchors_verify_CA()

getdns_return_t getdns_context_set_trust_anchors_verify_CA ( getdns_context context,
const char *  verify_CA 
)

Sets the public certificate for the Certificate Authority with which to validate the XML file with the S/MIME signatures fetch from the url given with the getdns_context_set_trust_anchors_url() function.

See also
getdns_context_get_trust_anchors_verify_CA
getdns_context_set_trust_anchors_url
getdns_context_set_trust_anchors_verify_email
Parameters
[in]contextThe context to configure
[in]verify_CAThe certificate of the Certificate Authority with which to validate the XML trust anchors. The default is the ICANN Root CA, which is valid till Dec 18 2029. When NULL is given, the default will be used. When an empty string is given, Zero configuration DNSSEC will be disabled.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_trust_anchors_verify_email()

getdns_return_t getdns_context_set_trust_anchors_verify_email ( getdns_context context,
const char *  verify_email 
)

Sets the email address for the Subject of the signer's certificate from the p7s signature file with which to validate the XML file fetched from the url given with the getdns_context_set_trust_anchors_url() function.

See also
getdns_context_get_trust_anchors_verify_email
getdns_context_set_trust_anchors_url
getdns_context_set_trust_anchors_verify_CA
Parameters
[in]contextThe context to configure
[in]verify_emailOnly signatures from this name are allowed. The default dnsse.nosp@m.c@ia.nosp@m.na.or.nosp@m.g. When NULL is given, the default will be used. When an empty string is given, Zero configuration DNSSEC will be disabled.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_resolvconf()

getdns_return_t getdns_context_set_resolvconf ( getdns_context context,
const char *  resolvconf 
)

Initialized the context's upstream recursive servers and suffixes with the values from the given resolv.conf file.

See also
getdns_context_get_resolvconf
getdns_context_set_hosts
Parameters
[in]contextThe context to configure
[in]resolvconfDefaults to /etc/resolv.conf
Returns
GETDNS_RETURN_GOOD when successful and error code otherwise.

◆ getdns_context_set_hosts()

getdns_return_t getdns_context_set_hosts ( getdns_context context,
const char *  hosts 
)

Initialized the context's GETDNS_NAMESPACE_LOCALNAMES namespace with values from the given hosts file.

See also
getdns_context_get_hosts
getdns_context_set_resolvconf
Parameters
[in]contextThe context to configure
[in]hostsDefaults to /etc/hosts
Returns
GETDNS_RETURN_GOOD when successful and error code otherwise.

◆ getdns_context_set_tls_ca_path()

getdns_return_t getdns_context_set_tls_ca_path ( getdns_context context,
const char *  tls_ca_path 
)

Specify where the location for CA certificates for verification purposes are located.

See also
getdns_context_get_tls_ca_path
getdns_context_set_tls_ca_file
Parameters
[in]contextThe context to configure
[in]tls_ca_pathDirectory with Certificate Authority certificates.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_tls_ca_file()

getdns_return_t getdns_context_set_tls_ca_file ( getdns_context context,
const char *  tls_ca_file 
)

Specify the file with CA certificates for verification purposes.

See also
getdns_context_get_tls_ca_file
getdns_context_set_tls_ca_path
Parameters
[in]contextThe context to configure
[in]tls_ca_fileThe file with Certificate Authority certificates.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_tls_cipher_list()

getdns_return_t getdns_context_set_tls_cipher_list ( getdns_context context,
const char *  cipher_list 
)

Sets the list of available ciphers for authenticated TLS upstreams.

See also
getdns_context_get_tls_cipher_list
Parameters
[in]contextThe context to configure
[in]cipher_listThe cipher list
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_set_tls_curves_list()

getdns_return_t getdns_context_set_tls_curves_list ( getdns_context context,
const char *  curves_list 
)

Sets the supported curves TLS upstreams.

See also
getdns_context_get_tls_curves_list
Parameters
[in]contextThe context to configure
[in]curves_listThe string is a colon separated list of curve NIDs or names, for example "P-521:P-384:P-256".
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_resolution_type()

getdns_return_t getdns_context_get_resolution_type ( getdns_context context,
getdns_resolution_t value 
)

Get the current resolution type setting from this context.

See also
getdns_context_set_resolution_type
Resolution types and texts
Parameters
[in]contextThe context from which to get the setting
[out]valueThe resolution type, either GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_namespaces()

getdns_return_t getdns_context_get_namespaces ( getdns_context context,
size_t *  namespace_count,
getdns_namespace_t **  namespaces 
)

Get a copy of the namespaces list setting from this context. Users must call free on the resulting namespaces if not NULL

See also
getdns_context_set_namespaces
Namespace types and texts
Parameters
[in]contextThe context from which to get the setting
[out]namespace_countThe length of the list.
[out]namespacesThe returned namespaces list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.

◆ getdns_context_get_dns_transport()

getdns_return_t getdns_context_get_dns_transport ( getdns_context context,
getdns_transport_t value 
)

Get what transports are used for DNS lookups.

See also
getdns_context_set_dns_transport
Transport arrangements and texts
getdns_context_get_dns_transport_list
Parameters
[in]contextThe context from which to get the setting
[out]valueThe transport to use for DNS lookups.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.

◆ getdns_context_get_dns_transport_list()

getdns_return_t getdns_context_get_dns_transport_list ( getdns_context context,
size_t *  transport_count,
getdns_transport_list_t **  transports 
)

Get a copy of the transports list setting from this context. Users must call free on the resulting transports if not NULL

See also
getdns_context_set_dns_transport_list
Transport list values and tests
getdns_context_get_dns_transport
Parameters
[in]contextThe context from which to get the setting
[out]transport_countThe length of the list.
[out]transportsThe returned transports list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.

◆ getdns_context_get_limit_outstanding_queries()

getdns_return_t getdns_context_get_limit_outstanding_queries ( getdns_context context,
uint16_t *  limit 
)

Get the current limit for outstanding queries setting from this context.

See also
getdns_context_set_limit_outstanding_queries
Parameters
[in]contextThe context from which to get the setting
[out]limitThe current limit for outstanding queries
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.

◆ getdns_context_get_timeout()

getdns_return_t getdns_context_get_timeout ( getdns_context context,
uint64_t *  timeout 
)

Get the current number of milliseconds the API will wait for request to return setting from this context.

See also
getdns_context_set_timeout
Parameters
[in]contextThe context from which to get the setting
[out]timeoutThe number of milliseconds the API will wait for a response.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.

◆ getdns_context_get_idle_timeout()

getdns_return_t getdns_context_get_idle_timeout ( getdns_context context,
uint64_t *  timeout 
)

Get the current number of milliseconds the API will leave an idle TCP or TLS connection open for (idle means no outstanding responses and no pending queries).

See also
getdns_context_set_idle_timeout
Parameters
[in]contextThe context from which to get the setting
[out]timeoutThe number of milliseconds the API will leave an idle TCP or TLS connection open for
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or timeout was NULL.

◆ getdns_context_get_follow_redirects()

getdns_return_t getdns_context_get_follow_redirects ( getdns_context context,
getdns_redirects_t value 
)

Get the setting that says whether or not DNS queries follow redirects.

See also
getdns_context_set_follow_redirects
Redirect policies and texts
Parameters
[in]contextThe context from which to get the setting
[out]valueEither GETDNS_REDIRECTS_FOLLOW or GETDNS_REDIRECTS_DO_NOT_FOLLOW
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_dns_root_servers()

getdns_return_t getdns_context_get_dns_root_servers ( getdns_context context,
getdns_list **  addresses 
)

Get a copy of the list of addresses in use for looking up top-level domains in use by the context. Callers are responsible for deallocating the returned list with getdns_list_destroy()

See also
getdns_context_set_dns_root_servers
Parameters
[in]contextThe context from which to get the setting
[out]addressesA copy of the list of dns root servers in use for looking up top level domains. The caller must destroy this list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or adresses was NULL.
GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated

◆ getdns_context_get_append_name()

getdns_return_t getdns_context_get_append_name ( getdns_context context,
getdns_append_name_t value 
)

Get whether, how and when a suffix is appended to a query string with the context.

See also
getdns_context_set_append_name
Suffix appending values and texts
Parameters
[in]contextThe context from which to get the setting
[out]valueGETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST, 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
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_suffix()

getdns_return_t getdns_context_get_suffix ( getdns_context context,
getdns_list **  value 
)

Get a copy of the list of suffixes to be appended based on the value off the append_name setting in use by context Callers are responsible for deallocating the returned list with getdns_list_destroy()

See also
getdns_context_set_suffix
Parameters
[in]contextThe context from which to get the setting
[out]valueA copy of the list of suffixes. The caller must destroy this list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated

◆ getdns_context_get_dnssec_trust_anchors()

getdns_return_t getdns_context_get_dnssec_trust_anchors ( getdns_context context,
getdns_list **  value 
)

Get a copy of the list of DNSSEC trust anchors in use by context. Callers are responsible for deallocating the returned list with getdns_list_destroy()

See also
getdns_context_set_dnssec_trust_anchors
Parameters
[in]contextThe context from which to get the setting
[out]valueA copy of the list of DNSSEC trust anchors. The caller must destroy this list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated

◆ getdns_context_get_dnssec_allowed_skew()

getdns_return_t getdns_context_get_dnssec_allowed_skew ( getdns_context context,
uint32_t *  value 
)

Get the allowed DNSSEC skew setting from context

See also
getdns_context_set_dnssec_allowed_skew
Parameters
[in]contextThe context from which to get the setting
[out]valueThe number of seconds of skew that is allowed in either direction when checking an RRSIG's Expiration and Inception fields.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_upstream_recursive_servers()

getdns_return_t getdns_context_get_upstream_recursive_servers ( getdns_context context,
getdns_list **  upstream_list 
)

Get a copy of the list of upstream that will be targeted in stub resolution mode. Callers are responsible for deallocating the returned list with getdns_list_destroy()

See also
getdns_context_set_upstream_recursive_servers
Parameters
[in]contextThe context from which to get the setting
[out]upstream_listA copy of the list of upstreams. The caller must destroy this list.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.
GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated

◆ getdns_context_get_edns_maximum_udp_payload_size()

getdns_return_t getdns_context_get_edns_maximum_udp_payload_size ( getdns_context context,
uint16_t *  value 
)

Get the maximum UDP payload size advertised in an EDNS0 OPT record setting from context

See also
getdns_context_set_edns_maximum_udp_payload_size
getdns_context_unset_edns_maximum_udp_payload_size
Parameters
[in]contextThe context from which to get the setting
[out]valuethe maximum UDP payload size advertised in an EDNS0 OPT record. When the value is unset, 0 is returned.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_edns_extended_rcode()

getdns_return_t getdns_context_get_edns_extended_rcode ( getdns_context context,
uint8_t *  value 
)

Get the rcode advertised in an EDNS0 OPT record setting from context

See also
getdns_context_set_edns_extended_rcode
Parameters
[in]contextThe context from which to get the setting
[out]valueThe rcode advertised in an EDNS0 OPT record
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_edns_version()

getdns_return_t getdns_context_get_edns_version ( getdns_context context,
uint8_t *  value 
)

Get the version advertised in an EDNS0 OPT record setting from context

See also
getdns_context_set_edns_version
Parameters
[in]contextThe context from which to get the setting
[out]valueThe version advertised in an EDNS0 OPT record
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_edns_do_bit()

getdns_return_t getdns_context_get_edns_do_bit ( getdns_context context,
uint8_t *  value 
)

Get the DO bit advertised in an EDNS0 OPT record setting from context

See also
getdns_context_set_edns_do_bit
Parameters
[in]contextThe context from which to get the setting
[out]value1 if the DO bit is advertised in EDNS0 OPT records, 0 otherwise.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_edns_client_subnet_private()

getdns_return_t getdns_context_get_edns_client_subnet_private ( getdns_context context,
uint8_t *  value 
)

Get whether queries with this context will have the EDNS Client Subnet option set to hide the originating network when resolving in stub resolution.

See also
getdns_context_set_edns_do_bit
Parameters
[in]contextThe context from which to get the setting
[out]value1 if the setting is on, 0 otherwise
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_tls_query_padding_blocksize()

getdns_return_t getdns_context_get_tls_query_padding_blocksize ( getdns_context context,
uint16_t *  value 
)

Get the blocksize that will be used to pad outgoing queries over TLS.

See also
getdns_context_set_tls_query_padding_blocksize
Parameters
[in]contextThe context from which to get the setting
[out]valueThe padding blocksize, or 0 if padding is disabled, or 1 if the setting is to pad using a sensible policy.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_tls_authentication()

getdns_return_t getdns_context_get_tls_authentication ( getdns_context context,
getdns_tls_authentication_t value 
)

Get whether the upstream needs to be authenticated with DNS over TLS.

See also
getdns_context_set_tls_authentication
Authentication values and texts
Parameters
[in]contextThe context from which to get the setting
[out]valueis either GETDNS_AUTHENTICATION_REQUIRED if authentication is required, or GETDNS_AUTHENTICATION_NONE if authentication is optional. When credentials are available, the API will still try to authenticate the upstream. See getdns_context_set_upstream_recursive_servers for details on how to configure credentials per upstream.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_round_robin_upstreams()

getdns_return_t getdns_context_get_round_robin_upstreams ( getdns_context context,
uint8_t *  value 
)

Get whether the context is configured to round robin queries over the available upstreams.

See also
getdns_context_set_round_robin_upstreams
Parameters
[in]contextThe context from which to get the setting
[out]value1 if the setting is on, 0 otherwise
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_tls_backoff_time()

getdns_return_t getdns_context_get_tls_backoff_time ( getdns_context context,
uint16_t *  value 
)

Get the amount of seconds a TLS connection should not be tried with an upstream when it has never been tried before.

See also
getdns_context_set_tls_backoff_time
Parameters
[in]contextThe context from which to get the setting
[out]valueNumber of seconds before an attempt to setup DNS over TLS, with an upstream for which setting up an TLS connection has never been successful before, will be retried.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_tls_connection_retries()

getdns_return_t getdns_context_get_tls_connection_retries ( getdns_context context,
uint16_t *  value 
)

Get the number of times getdns retries to setup DNS over TLS with a specific upstream, before it decides to give up for tls_backoff_time seconds.

See also
getdns_context_set_tls_connection_retries
Parameters
[in]contextThe context from which to get the setting
[out]valueNumber of attempts to retry setting up a DNS over TLS connection before giving up.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL.

◆ getdns_context_get_update_callback()

getdns_return_t getdns_context_get_update_callback ( getdns_context context,
void **  userarg,
void(**)(getdns_context *, getdns_context_code_t, void *)  value 
)

Get the currently registered callback function and user defined argument for context changes. Combined with getdns_context_set_update_callback this can be used to "chain" context update callbacks and in this way create a subscription service catering multiple interested parties.

See also
Context code values and texts
Parameters
contextThe context to monitor for changes
userargA user defined argument to be passed to the callback function.
valueThe callback function to be called on context value changes.
Returns
GETDNS_RETURN_GOOD on success or an error code on failure.

◆ getdns_context_get_trust_anchors_url()

getdns_return_t getdns_context_get_trust_anchors_url ( getdns_context context,
const char **  url 
)

Gets the url for the location of the XML file from which to fetch the trust anchors with Zero configuration DNSSEC.

Alongside the XML file, also the S/MIME signature that will be used to validate the XML file, will be fetched from the url with the .xml extension replaced by .p7s.

When successfully validated with the verify Certificate Authority and the verify email address, the context will be equipped with the DNSSEC trust anchors defined within the XML file as described in RFC7958. The XML file will also be stored together with the .p7s file in the appdata directory with the names "root-anchors.xml" and "root-anchors.p7s" respectively.

When the trust-anchors from the XML file are used, the root DNSKEY is tracked and stored in the appdata directory too as "root.key"

Trust anchors from the XML file will be tried when:

  • There were no other trust anchors provided, either by the default trust anchor file "/etc/unbound/getdns-root.key", or set with the getdns_context_set_dnssec_trust_anchors() function.
  • or the available trust anchors (from the default location or set by the application) caused the root DNSKEY rrset to be BOGUS.

Trust anchors from the XML file will be read from the root-anchors.xml file in appdata directory and will only be used when validation with the S/MIME signatures in root-anchors.p7s succeeds with the verification Certificate Authority and the verification email address.

A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be fetched when:

  • The appdata directory is writeable by the current used, but the "root-anchors.xml" or "root-anchors.p7s" files were not available.
  • or there is a new root DNSKEY RRset (or signature) and it contains key_ids which were not in "root-anchors.xml."
See also
getdns_context_set_trust_anchors_url
getdns_context_get_trust_anchors_verify_CA
getdns_context_get_trust_anchors_verify_email
Parameters
[in]contextThe context to configure
[out]urlThe url including the XML file, from which the trust anchors (and the S/MIME signature) will be fetched. Default is: http://data.iana.org/root-anchors/root-anchors.xml
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_trust_anchors_verify_CA()

getdns_return_t getdns_context_get_trust_anchors_verify_CA ( getdns_context context,
const char **  verify_CA 
)

Gets the public certificate for the Certificate Authority with which to validate the XML file with the S/MIME signatures fetch from the url given with the getdns_context_set_trust_anchors_url() function.

See also
getdns_context_set_trust_anchors_verify_CA
getdns_context_get_trust_anchors_url
getdns_context_get_trust_anchors_verify_email
Parameters
[in]contextThe context to configure
[out]verify_CAThe certificate of the Certificate Authority with which to validate the XML trust anchors. The default is the ICANN Root CA, which is valid till Dec 18 2029.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_trust_anchors_verify_email()

getdns_return_t getdns_context_get_trust_anchors_verify_email ( getdns_context context,
const char **  verify_email 
)

Gets the email address for the Subject of the signer's certificate from the p7s signature file with which to validate the XML file fetched from the url given with the getdns_context_set_trust_anchors_url() function.

See also
getdns_context_set_trust_anchors_verify_email
getdns_context_get_trust_anchors_url
getdns_context_get_trust_anchors_verify_CA
Parameters
[in]contextThe context to configure
[out]verify_emailOnly signatures from this name are allowed. The default dnsse.nosp@m.c@ia.nosp@m.na.or.nosp@m.g.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_resolvconf()

getdns_return_t getdns_context_get_resolvconf ( getdns_context context,
const char **  resolvconf 
)

Get the value with which the context's upstream recursive servers and suffixes were initialized.

See also
getdns_context_set_resolvconf
getdns_context_get_hosts
Parameters
[in]contextThe context to configure
[out]resolvconfNULL if the context was not initialized with a resolv.conf file.
Returns
GETDNS_RETURN_GOOD when successful and error code otherwise.

◆ getdns_context_get_hosts()

getdns_return_t getdns_context_get_hosts ( getdns_context context,
const char **  hosts 
)

Get the value with which the context's GETDNS_NAMESPACE_LOCALNAMES namespace was initialized.

See also
getdns_context_set_hosts
getdns_context_get_resolvconf
Parameters
[in]contextThe context to configure
[out]hostsNULL when GETDNS_NAMESPACE_LOCALNAMES namespace was not initialized.
Returns
GETDNS_RETURN_GOOD when successful and error code otherwise.

◆ getdns_context_get_tls_ca_path()

getdns_return_t getdns_context_get_tls_ca_path ( getdns_context context,
const char **  tls_ca_path 
)

Get the location of the directory for CA certificates for verification purposes.

See also
getdns_context_set_tls_ca_path
getdns_context_get_tls_ca_file
Parameters
[in]contextThe context to configure
[out]tls_ca_pathDirectory with Certificate Authority certificates or NULL when one was not configured.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_tls_ca_file()

getdns_return_t getdns_context_get_tls_ca_file ( getdns_context context,
const char **  tls_ca_file 
)

Get the file location with CA certificates for verification purposes.

See also
getdns_context_set_tls_ca_file
getdns_context_get_tls_ca_path
Parameters
[in]contextThe context to configure
[out]tls_ca_fileThe file with Certificate Authority certificates or NULL when one was not configured.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_tls_cipher_list()

getdns_return_t getdns_context_get_tls_cipher_list ( getdns_context context,
const char **  cipher_list 
)

Get the list of available ciphers for authenticated TLS upstreams.

See also
getdns_context_set_tls_cipher_list
Parameters
[in]contextThe context configure
[out]cipher_listThe cipher list
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_get_tls_curves_list()

getdns_return_t getdns_context_get_tls_curves_list ( getdns_context context,
const char **  curves_list 
)

Get the supported curves list if one has been set earlier.

See also
getdns_context_set_tls_curves_list
Parameters
[in]contextThe configured context
[out]curves_listThe string is a colon separated list of curve NIDs or names, for example "P-521:P-384:P-256", when one has been configured on the context, or NULL when none has been set before.
Returns
GETDNS_RETURN_GOOD when successful
GETDNS_RETURN_INVALID_PARAMETER when context was NULL.

◆ getdns_context_config()

getdns_return_t getdns_context_config ( getdns_context context,
const getdns_dict config_dict 
)

Configure a context with settings given in a getdns_dict.

Parameters
contextThe context to be configured.
config_dictThe getdns_dict containing the settings. The settings have the same name as returned by the getdns_context_get_api_information() function, or as used in the names of the getdns_context_get_*() and getdns_context_set_*() functions.
  • The dict returned by getdns_context_get_api_information() can be used as the config_dict directly, but context settings do not have to be below a "all_context" key.
  • It is possible to set default values for extensions that could otherwise only be given on a per query basis. For example: { dnssec_return_status: GETDNS_EXTENSION_TRUE } is equivalent to using the getdns_context_set_return_dnssec_status() function with that value, but default values for the other extensions can be set by this method now too. For example { return_call_reporting: GETDNS_EXTENSION_TRUE}
  • Trust anchor files and root hints content can also be given by file, for example:
     { dns_root_servers : "named.root"
     , dnssec_trust_anchors: "/etc/unbound/getdns-root.key"
     }
    
Returns
GETDNS_RETURN_GOOD on success or an error code on failure. Beware that context might be partially configured on error. For retry strategies it is advised to recreate a new config.