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 0x3000 |
| #define | GETDNS_LOG_UPSTREAM_STATS_TEXT "Log messages about upstream statistics" |
| #define | GETDNS_LOG_SYS_STUB 0x2000 |
| #define | GETDNS_LOG_SYS_STUB_TEXT "Log messages about stub resolving" |
| #define | GETDNS_LOG_SYS_RECURSING 0x4000 |
| #define | GETDNS_LOG_SYS_RECURSING_TEXT "Log messages about recursive resolving" |
| #define | GETDNS_LOG_SYS_RESOLVING 0x6000 |
| #define | GETDNS_LOG_SYS_RESOLVING_TEXT "Log messages about resolving" |
| #define | GETDNS_LOG_SYS_ANCHOR 0x8000 |
| #define | GETDNS_LOG_SYS_ANCHOR_TEXT "Log messages about fetching trust anchors" |
| #define | GETDNS_SSL3_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
| #define | GETDNS_TLS1_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
| #define | GETDNS_TLS1_1_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
| #define | GETDNS_TLS1_2_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
| #define | GETDNS_TLS1_3_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
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) |
| typedef enum getdns_tls_version_t | getdns_tls_version_t |
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 } |
| enum | getdns_tls_version_t { GETDNS_SSL3 = 1400 , GETDNS_TLS1 = 1401 , GETDNS_TLS1_1 = 1402 , GETDNS_TLS1_2 = 1403 , GETDNS_TLS1_3 = 1404 } |
Detailed Description
Macro Definition Documentation
◆ GETDNS_LOG_EMERG_TEXT
| #define GETDNS_LOG_EMERG_TEXT "System is unusable" |
Definition at line 567 of file getdns_extra.h.
◆ GETDNS_LOG_ALERT_TEXT
| #define GETDNS_LOG_ALERT_TEXT "Action must be taken immediately" |
Definition at line 568 of file getdns_extra.h.
◆ GETDNS_LOG_CRIT_TEXT
| #define GETDNS_LOG_CRIT_TEXT "Critical conditions" |
Definition at line 569 of file getdns_extra.h.
◆ GETDNS_LOG_ERR_TEXT
| #define GETDNS_LOG_ERR_TEXT "Error conditions" |
Definition at line 570 of file getdns_extra.h.
◆ GETDNS_LOG_WARNING_TEXT
| #define GETDNS_LOG_WARNING_TEXT "Warning conditions" |
Definition at line 571 of file getdns_extra.h.
◆ GETDNS_LOG_NOTICE_TEXT
| #define GETDNS_LOG_NOTICE_TEXT "Normal, but significant, condition" |
Definition at line 572 of file getdns_extra.h.
◆ GETDNS_LOG_INFO_TEXT
| #define GETDNS_LOG_INFO_TEXT "Informational message" |
Definition at line 573 of file getdns_extra.h.
◆ GETDNS_LOG_DEBUG_TEXT
| #define GETDNS_LOG_DEBUG_TEXT "Debug-level message" |
Definition at line 574 of file getdns_extra.h.
◆ GETDNS_LOG_UPSTREAM_STATS
| #define GETDNS_LOG_UPSTREAM_STATS 0x3000 |
Definition at line 576 of file getdns_extra.h.
◆ GETDNS_LOG_UPSTREAM_STATS_TEXT
| #define GETDNS_LOG_UPSTREAM_STATS_TEXT "Log messages about upstream statistics" |
Definition at line 577 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_STUB
| #define GETDNS_LOG_SYS_STUB 0x2000 |
Definition at line 578 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_STUB_TEXT
| #define GETDNS_LOG_SYS_STUB_TEXT "Log messages about stub resolving" |
Definition at line 579 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_RECURSING
| #define GETDNS_LOG_SYS_RECURSING 0x4000 |
Definition at line 580 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_RECURSING_TEXT
| #define GETDNS_LOG_SYS_RECURSING_TEXT "Log messages about recursive resolving" |
Definition at line 581 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_RESOLVING
| #define GETDNS_LOG_SYS_RESOLVING 0x6000 |
Definition at line 582 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_RESOLVING_TEXT
| #define GETDNS_LOG_SYS_RESOLVING_TEXT "Log messages about resolving" |
Definition at line 583 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_ANCHOR
| #define GETDNS_LOG_SYS_ANCHOR 0x8000 |
Definition at line 584 of file getdns_extra.h.
◆ GETDNS_LOG_SYS_ANCHOR_TEXT
| #define GETDNS_LOG_SYS_ANCHOR_TEXT "Log messages about fetching trust anchors" |
Definition at line 585 of file getdns_extra.h.
◆ GETDNS_SSL3_TEXT
| #define GETDNS_SSL3_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
Definition at line 842 of file getdns_extra.h.
◆ GETDNS_TLS1_TEXT
| #define GETDNS_TLS1_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
Definition at line 843 of file getdns_extra.h.
◆ GETDNS_TLS1_1_TEXT
| #define GETDNS_TLS1_1_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
Definition at line 844 of file getdns_extra.h.
◆ GETDNS_TLS1_2_TEXT
| #define GETDNS_TLS1_2_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
Definition at line 845 of file getdns_extra.h.
◆ GETDNS_TLS1_3_TEXT
| #define GETDNS_TLS1_3_TEXT "See getdns_context_(set|get)_tls_(min|max)_version()" |
Definition at line 846 of file getdns_extra.h.
Typedef Documentation
◆ getdns_loglevel_type
| typedef enum getdns_loglevel_type 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 589 of file getdns_extra.h.
◆ getdns_tls_version_t
| typedef enum getdns_tls_version_t getdns_tls_version_t |
Enumeration Type Documentation
◆ getdns_loglevel_type
| enum 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 556 of file getdns_extra.h.
◆ getdns_tls_version_t
| enum getdns_tls_version_t |
| Enumerator | |
|---|---|
| GETDNS_SSL3 | |
| GETDNS_TLS1 | |
| GETDNS_TLS1_1 | |
| GETDNS_TLS1_2 | |
| GETDNS_TLS1_3 | |
Definition at line 834 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
-
context context that can be used immediately with other API calls set_from_os set 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
-
context context that can be used immediately with other API calls set_from_os set to 1 to initialize the context with os defaults malloc custom malloc function realloc custom realloc function free custom 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
-
context context that can be used immediately with other API calls set_from_os set to 1 to initialize the context with os defaults userarg parameter passed to the custom malloc, realloc and free functions malloc custom malloc function realloc custom realloc function free custom 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
-
context The context for which to monitor changes value The 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.
- Parameters
-
context The context to configure value GETDNS_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, | ||
| const 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
- Parameters
-
context The context to configure namespace_count The number of values in the namespaces list. namespaces An 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
-
context The context to configure value The 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
-
context The context to configure transport_count The number of values in the transports list. transports An 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
-
context The context to configure timeout The 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_tcp_send_timeout()
| getdns_return_t getdns_context_set_tcp_send_timeout | ( | getdns_context * | context, |
| uint32_t | value | ||
| ) |
Set the number of milliseconds send data may remain unacknowledged by the peer in a TCP connection, if supported by the operation system. When not set (the default), the system default is left alone.
- Parameters
-
context The context to configure value The number of milliseconds the send data may remain unacknowledged by the peer in a TCP connection.
- Returns
- GETDNS_RETURN_GOOD when successful.
- GETDNS_RETURN_INVALID_PARAMETER when context was NULL or the value was too high.
◆ 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.
- Parameters
-
context The context to configure limit The 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
-
context The context to configure timeout The 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.
- Parameters
-
context The context to configure value GETDNS_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
- Parameters
-
context The context to configure addresses The 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.
- Parameters
-
context The context to configure value GETDNS_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
-
context The context to configure value A 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 1.
- Parameters
-
context The context to configure value A 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.
- Parameters
-
context The context to configure value The 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.
- Parameters
-
context The context to configure upstream_list The 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 nameaddress_datawhose value is the address bindata, and optionally also:scode_idcontaining an getdns_bindata with the scope ID for IPv6 link-local addresses.portan integer specifying which port to use to contact this upstream over UDP and TCP; the default is 53tsig_algorithm(a bindata) that is the name of the TSIG hash algorithmtsig_name(a bindata) that is the name of the TSIG keytsig_secret(a bindata) that is the TSIG keytls_port(a integer) that is the port to use to contact this upstream over TLStls_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 withdigestwhich must be a bindata containing the text sha256valueA SHA256 hash of theSubjectPublicKeyInfoof 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
contextorupstream_listwasNULL -
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
-
context The context to configure value The 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.
- Parameters
-
context The context to configure value A 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
-
context The context to configure value A 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
-
context The context to configure value A 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
-
context The context to configure malloc A custom memory allocator. The default is malloc.realloc A custom memory reallocator. The default is realloc.free A 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
-
context The context to configure userarg This value will be passed as the userargargument to the custommalloc,reallocandfreefunction.malloc A custom memory allocator. The default is a wrapper for malloc.realloc A custom memory reallocator. The default is a wrapper for realloc.free A 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.
- Parameters
-
context The context to monitor for changes userarg A user defined argument that will be passed to the callback function. value The 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
-
context The context to configure enabled is 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.
- Parameters
-
context The context to configure value is 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.
- Parameters
-
context The context to configure value is 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.
- Parameters
-
context The context to configure value Number 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.
- Parameters
-
context The context to configure value Number 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).
- Parameters
-
context The context to configure value is 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).
- Parameters
-
context The context to configure value The 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
-
context The context to configure
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null.
◆ getdns_context_unset_tcp_send_timeout()
| getdns_return_t getdns_context_unset_tcp_send_timeout | ( | getdns_context * | context | ) |
Configure context to use the system default setting for the time send data may remain unacknowledged by the peer in a TCP connection.
- Parameters
-
context The 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] context The context from which to get the setting [in] userarg A user defined argument to be passed to the log function. [in] system A 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] level A 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] func The 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.
- 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] context The context from which to get the setting [in] appdata_dir A 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 /.getdns/ on Unix line systems (Linux, BSD's, MacOS), and AppData%\getdns\ 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 "1", 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] context The context to configure [in] url The 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] context The context to configure [in] verify_CA The 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] context The context to configure [in] verify_email Only signatures from this name are allowed. The default dnssec@iana.org. 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_backoff_time()
| getdns_return_t getdns_context_set_trust_anchors_backoff_time | ( | getdns_context * | context, |
| uint64_t | value | ||
| ) |
Configure the amount of milliseconds the trust anchors should not be tried to be fetched after failure. Default is 2500 which is two and a half seconds. Setting the trust anchors backoff time will cause fetching to be retried immediatly.
- Parameters
-
context The context to configure value Number of milliseconds before fetch trust anchors will be retried.
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is 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.
- Parameters
-
[in] context The context to configure [in] resolvconf Defaults 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.
- Parameters
-
[in] context The context to configure [in] hosts Defaults 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.
- Parameters
-
[in] context The context to configure [in] tls_ca_path Directory 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.
- Parameters
-
[in] context The context to configure [in] tls_ca_file The 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.
- Parameters
-
[in] context The context to configure [in] cipher_list The cipher list
- Returns
- GETDNS_RETURN_GOOD when successful
- GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
◆ getdns_context_set_tls_ciphersuites()
| getdns_return_t getdns_context_set_tls_ciphersuites | ( | getdns_context * | context, |
| const char * | ciphersuites | ||
| ) |
Configure the available TLS1.3 ciphersuites for authenticated TLS upstreams.
- Parameters
-
[in] context The context to configure [in] ciphersuites The 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.
- Parameters
-
[in] context The context to configure [in] curves_list The 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_set_tls_min_version()
| getdns_return_t getdns_context_set_tls_min_version | ( | getdns_context * | context, |
| getdns_tls_version_t | min_version | ||
| ) |
Configure context for minimum supported TLS version.
- Parameters
-
context The context to configure min_version is one of GETDNS_SSL3, GETDNS_TLS1, GETDNS_TLS1_1, GETDNS_TLS1_2, GETDNS_TLS1_3
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.
◆ getdns_context_get_tls_min_version()
| getdns_return_t getdns_context_get_tls_min_version | ( | const getdns_context * | context, |
| getdns_tls_version_t * | min_version | ||
| ) |
Get configured minimum supported TLS version.
- Parameters
-
context The context to configure min_version is one of GETDNS_SSL3, GETDNS_TLS1, GETDNS_TLS1_1, GETDNS_TLS1_2, GETDNS_TLS1_3
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.
◆ getdns_context_set_tls_max_version()
| getdns_return_t getdns_context_set_tls_max_version | ( | getdns_context * | context, |
| getdns_tls_version_t | max_version | ||
| ) |
Configure context for maximum supported TLS version.
- Parameters
-
context The context to configure max_version is one of GETDNS_SSL3, GETDNS_TLS1, GETDNS_TLS1_1, GETDNS_TLS1_2, GETDNS_TLS1_3
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.
◆ getdns_context_get_tls_max_version()
| getdns_return_t getdns_context_get_tls_max_version | ( | const getdns_context * | context, |
| getdns_tls_version_t * | max_version | ||
| ) |
Get configured maximum supported TLS version.
- Parameters
-
context The context to configure max_version is one of GETDNS_SSL3, GETDNS_TLS1, GETDNS_TLS1_1, GETDNS_TLS1_2, GETDNS_TLS1_3
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an invalid value.
◆ getdns_context_get_resolution_type()
| getdns_return_t getdns_context_get_resolution_type | ( | const getdns_context * | context, |
| getdns_resolution_t * | value | ||
| ) |
Get the current resolution type setting from this context.
- Parameters
-
[in] context The context from which to get the setting [out] value The 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 | ( | const 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
- Parameters
-
[in] context The context from which to get the setting [out] namespace_count The length of the list. [out] namespaces The 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 | ( | const 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] context The context from which to get the setting [out] value The 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 | ( | const 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] context The context from which to get the setting [out] transport_count The length of the list. [out] transports The 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 | ( | const getdns_context * | context, |
| uint16_t * | limit | ||
| ) |
Get the current limit for outstanding queries setting from this context.
- Parameters
-
[in] context The context from which to get the setting [out] limit The 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 | ( | const 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] context The context from which to get the setting [out] timeout The 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 | ( | const 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] context The context from which to get the setting [out] timeout The 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_tcp_send_timeout()
| getdns_return_t getdns_context_get_tcp_send_timeout | ( | const getdns_context * | context, |
| uint32_t * | value | ||
| ) |
Get the number of milliseconds send data may remain unacknowledged by the peer in a TCP connection setting from context.
- Parameters
-
[in] context The context from which to get the setting [out] value The number of milliseconds the send data may remain unacknowledged by the peer in a TCP connection. 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_follow_redirects()
| getdns_return_t getdns_context_get_follow_redirects | ( | const getdns_context * | context, |
| getdns_redirects_t * | value | ||
| ) |
Get the setting that says whether or not DNS queries follow redirects.
- Parameters
-
[in] context The context from which to get the setting [out] value Either 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 | ( | const 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()
- Parameters
-
[in] context The context from which to get the setting [out] addresses A 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 | ( | const getdns_context * | context, |
| getdns_append_name_t * | value | ||
| ) |
Get whether, how and when a suffix is appended to a query string with the context.
- Parameters
-
[in] context The context from which to get the setting [out] value GETDNS_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 | ( | const 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] context The context from which to get the setting [out] value A 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 | ( | const 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()
- Parameters
-
[in] context The context from which to get the setting [out] value A 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 | ( | const getdns_context * | context, |
| uint32_t * | value | ||
| ) |
Get the allowed DNSSEC skew setting from context
- Parameters
-
[in] context The context from which to get the setting [out] value The 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 | ( | const 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()
- Parameters
-
[in] context The context from which to get the setting [out] upstream_list A 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 | ( | const 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] context The context from which to get the setting [out] value the 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 | ( | const getdns_context * | context, |
| uint8_t * | value | ||
| ) |
Get the rcode advertised in an EDNS0 OPT record setting from context
- Parameters
-
[in] context The context from which to get the setting [out] value The 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 | ( | const 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] context The context from which to get the setting [out] value The 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 | ( | const 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] context The context from which to get the setting [out] value 1 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 | ( | const 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] context The context from which to get the setting [out] value 1 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 | ( | const getdns_context * | context, |
| uint16_t * | value | ||
| ) |
Get the blocksize that will be used to pad outgoing queries over TLS.
- Parameters
-
[in] context The context from which to get the setting [out] value The 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 | ( | const getdns_context * | context, |
| getdns_tls_authentication_t * | value | ||
| ) |
Get whether the upstream needs to be authenticated with DNS over TLS.
- Parameters
-
[in] context The context from which to get the setting [out] value is 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 | ( | const getdns_context * | context, |
| uint8_t * | value | ||
| ) |
Get whether the context is configured to round robin queries over the available upstreams.
- Parameters
-
[in] context The context from which to get the setting [out] value 1 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 | ( | const 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.
- Parameters
-
[in] context The context from which to get the setting [out] value Number 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 | ( | const 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.
- Parameters
-
[in] context The context from which to get the setting [out] value Number 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 | ( | const 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
-
context The context to monitor for changes userarg A user defined argument to be passed to the callback function. value The 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 | ( | const 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 "1", 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] context The context to configure [out] url The 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 | ( | const 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] context The context to configure [out] verify_CA The 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 | ( | const 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] context The context to configure [out] verify_email Only signatures from this name are allowed. The default dnssec@iana.org.
- Returns
- GETDNS_RETURN_GOOD when successful
- GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
◆ getdns_context_get_trust_anchors_backoff_time()
| getdns_return_t getdns_context_get_trust_anchors_backoff_time | ( | const getdns_context * | context, |
| uint64_t * | value | ||
| ) |
Get the amount of milliseconds the trust anchors will not be tried to be fetched after failure.
- Parameters
-
context The context to configure value Number of milliseconds before fetch trust anchors will be retried.
- Returns
- GETDNS_RETURN_GOOD on success
- GETDNS_RETURN_INVALID_PARAMETER if context is null.
◆ getdns_context_get_resolvconf()
| getdns_return_t getdns_context_get_resolvconf | ( | const getdns_context * | context, |
| const char ** | resolvconf | ||
| ) |
Get the value with which the context's upstream recursive servers and suffixes were initialized.
- Parameters
-
[in] context The context to configure [out] resolvconf NULL 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 | ( | const getdns_context * | context, |
| const char ** | hosts | ||
| ) |
Get the value with which the context's GETDNS_NAMESPACE_LOCALNAMES namespace was initialized.
- Parameters
-
[in] context The context to configure [out] hosts NULL 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 | ( | const getdns_context * | context, |
| const char ** | tls_ca_path | ||
| ) |
Get the location of the directory for CA certificates for verification purposes.
- Parameters
-
[in] context The context to configure [out] tls_ca_path Directory 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 | ( | const getdns_context * | context, |
| const char ** | tls_ca_file | ||
| ) |
Get the file location with CA certificates for verification purposes.
- Parameters
-
[in] context The context to configure [out] tls_ca_file The 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 | ( | const getdns_context * | context, |
| const char ** | cipher_list | ||
| ) |
Get the list of available ciphers for authenticated TLS upstreams.
- Parameters
-
[in] context The context configure [out] cipher_list The cipher list
- Returns
- GETDNS_RETURN_GOOD when successful
- GETDNS_RETURN_INVALID_PARAMETER when context was NULL.
◆ getdns_context_get_tls_ciphersuites()
| getdns_return_t getdns_context_get_tls_ciphersuites | ( | const getdns_context * | context, |
| const char ** | ciphersuites | ||
| ) |
Get the configured available TLS1.3 ciphersuited for authenticated TLS upstreams.
- Parameters
-
[in] context The context configure [out] ciphersuites The 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 | ( | const getdns_context * | context, |
| const char ** | curves_list | ||
| ) |
Get the supported curves list if one has been set earlier.
- Parameters
-
[in] context The configured context [out] curves_list The 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
-
context The context to be configured. config_dict The 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" }
- 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
- 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.