From ed0b655af04a055919a73fdbeda2fe1efa8a899f Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Sat, 25 Mar 2017 06:45:02 -0500 Subject: [PATCH 1/6] Update doxygen --- src/getdns/getdns.h.in | 88 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index f7825361..5851c023 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -501,6 +501,8 @@ typedef enum getdns_data_type { t_dict, t_list, t_int, t_bindata } getdns_data_type; + + typedef struct getdns_bindata { size_t size; @@ -709,12 +711,46 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict, * @return pointer to an allocated list, NULL if insufficient memory */ getdns_list *getdns_list_create(); + +/** + * create a new list with no items, creating and initializing it with the + * custom memory function from context. These memory functions will be used + * for creating, and inherited by the list members when populating the list. + * The custom deallocator will be used for destroying the list. + * @param context The context from which the custom memory functions will be + * used to create and initialize the list. + * @return pointer to an allocated list, NULL if insufficient memory + */ getdns_list *getdns_list_create_with_context(getdns_context *context); + +/** + * create a new list with no items, creating and initializing it with the + * provided custom memory function. These memory functions will be used + * for creating, and inherited by the list members when populating the list. + * The custom deallocator will be used for destroying the list. + * @param malloc Custom allocator + * @param realloc Custom reallocator + * @param free Custom deallocator + * @return pointer to an allocated list, NULL if insufficient memory + */ getdns_list *getdns_list_create_with_memory_functions( void *(*malloc) (size_t), void *(*realloc) (void *, size_t), void (*free) (void *) ); + +/** + * create a new list with no items, creating and initializing it with the + * provided extended custom memory function. These memory functions will be + * used for creating, and inherited by the list members when populating the + * list. The custom deallocator will be used for destroying the list. + * @param userarg Will be passed as the first argument to the extended + * custom malloc, realloc, and free. + * @param malloc Custom allocator + * @param realloc Custom reallocator + * @param free Custom deallocator + * @return pointer to an allocated list, NULL if insufficient memory + */ getdns_list *getdns_list_create_with_extended_memory_functions( void *userarg, void *(*malloc) (void *userarg, size_t), @@ -795,12 +831,46 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, * @return pointer to an allocated dictionary, NULL if insufficient memory */ getdns_dict *getdns_dict_create(); + +/** + * create a new dict with no items, creating and initializing it with the + * custom memory function from context. These memory functions will be used + * for creating, and inherited by the list members when populating the dict. + * The custom deallocator will be used for destroying the dict. + * @param context The context from which the custom memory functions will be + * used to create and initialize the dict. + * @return pointer to an allocated dict, NULL if insufficient memory + */ getdns_dict *getdns_dict_create_with_context(getdns_context *context); + +/** + * create a new dict with no items, creating and initializing it with the + * provided custom memory function. These memory functions will be used + * for creating, and inherited by the dict members when populating the dict. + * The custom deallocator will be used for destroying the dict. + * @param malloc Custom allocator + * @param realloc Custom reallocator + * @param free Custom deallocator + * @return pointer to an allocated dict, NULL if insufficient memory + */ getdns_dict *getdns_dict_create_with_memory_functions( void *(*malloc) (size_t), void *(*realloc) (void *, size_t), void (*free) (void *) ); + +/** + * create a new dict with no items, creating and initializing it with the + * provided extended custom memory function. These memory functions will be + * used for creating, and inherited by the dict members when populating the + * dict. The custom deallocator will be used for destroying the dict. + * @param userarg Will be passed as the first argument to the extended + * custom malloc, realloc, and free. + * @param malloc Custom allocator + * @param realloc Custom reallocator + * @param free Custom deallocator + * @return pointer to an allocated dict, NULL if insufficient memory + */ getdns_dict *getdns_dict_create_with_extended_memory_functions( void *userarg, void *(*malloc) (void *userarg, size_t), @@ -872,7 +942,10 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); /** * \addtogroup callbackfns getdns_callback functions */ -/* Callback arguments */ +/** + * The type of the callback function that must be registered when scheduling + * asynchronous requests. + */ typedef void (*getdns_callback_t) (getdns_context *context, getdns_callback_type_t callback_type, getdns_dict * response, @@ -1019,6 +1092,10 @@ getdns_context_create_with_extended_memory_functions( void (*free) (void *userarg, void *) ); +/** + * destroy the context. All outstanding requests will be cancelled with + * the getdns_cancel_callback() function. + */ void getdns_context_destroy(getdns_context *context); /** @} */ @@ -1028,6 +1105,11 @@ void getdns_context_destroy(getdns_context *context); * \addtogroup callbackfns getdns_callback functions * @{ */ +/** + * Cancel an outstanding asynchronous request. The callback registered with + * the request will be called with the getdns_callback_type_t set to + * GETDNS_CALLBACK_CANCEL and the response set to NULL. + */ getdns_return_t getdns_cancel_callback(getdns_context *context, getdns_transaction_t transaction_id); @@ -1111,6 +1193,10 @@ getdns_service_sync(getdns_context *context, * @{ */ +/** + * Convert a domain name in DNS wire format to presentation format. + * The newly allocated string should be freed with free. + */ getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, From a060e723f2f054bb281c13ddd0a07f2023e4cfc7 Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Tue, 11 Apr 2017 23:29:33 +0200 Subject: [PATCH 2/6] Doxygen documentation for everything in getdns.h --- src/getdns/getdns.h.in | 436 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 432 insertions(+), 4 deletions(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index 5851c023..618bb835 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -490,12 +490,30 @@ typedef enum getdns_callback_type_t { */ +/** + * Many calls in the DNS API require a DNS context. A DNS context contains + * the information that the API needs in order to process DNS calls, such + * as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. + * The internal structure of the DNS context is opaque, and might be different + * on each OS. When a context is passed to any function, it must be an + * allocated context; the context must not be NULL. + * + * Use getdns_context_set_* functions to configure a context. + */ typedef struct getdns_context getdns_context; + +/** + * When scheduling asynchronous requests, transaction identifiers associated + * with the request are returned. These identifiers are of the type: + * getdns_transaction_t. These identifiers can be used to associate answers + * with requests, and also to cancel outstanding requests. + */ typedef uint64_t getdns_transaction_t; /** - * used to check data types within complex types (dict, list) + * getdns_list_get_data_type() and getdns_dict_get_data_type() return the type + * of data on an index in a getdns_list, or on a name in a getdns_dict. */ typedef enum getdns_data_type { @@ -503,6 +521,9 @@ typedef enum getdns_data_type } getdns_data_type; +/** + * A struct to hold binary data. + */ typedef struct getdns_bindata { size_t size; @@ -893,8 +914,17 @@ void getdns_dict_destroy(getdns_dict *dict); * @{ */ +/** + * create a new entry in the dictionary, or replace the value of an existing entry + * this routine makes a copy of the child_dict_ + * @param dict dictionary in which to add or change the value + * @param name key that identifies which item in the dictionary to add/change + * @param child_dict value to assign to the node identified by name + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); + /** * create a new entry in the dictionary, or replace the value of an existing entry * this routine makes a copy of the child_list @@ -944,7 +974,28 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); */ /** * The type of the callback function that must be registered when scheduling - * asynchronous requests. + * asynchronous requests. The registered function will be called from the + * eventloop with the following parameters. + * @param context The DNS context that was used in the calling function + * @param callback_type Supplies the reason for the callback. + * This will be one of: + * - GETDNS_CALLBACK_COMPLETE The response has the + * requested data in it + * - GETDNS_CALLBACK_CANCEL The calling program cancelled + * the callback; response is NULL + * - GETDNS_CALLBACK_TIMEOUT The requested action timed + * out; response is filled in with empty structures or + * will contain additional information about the timeout + * when used in combination with the + * return_call_reporting extension. + * - GETDNS_CALLBACK_ERROR The requested action had an + * error; response is NULL. + * @param response A response object with the response data. + * The application is responsible for cleaning up the response + * object with getdns_dict_destroy. + * @param userarg Identical to the userarg passed to the calling function. + * @param transaction_id The transaction identifier that was assigned by the + * calling function. */ typedef void (*getdns_callback_t) (getdns_context *context, getdns_callback_type_t callback_type, @@ -1196,27 +1247,90 @@ getdns_service_sync(getdns_context *context, /** * Convert a domain name in DNS wire format to presentation format. * The newly allocated string should be freed with free. + * @param dns_name_wire_fmt A bindata to the DNS name in wire format + * @param fqdn_as_string A reference to a pointer that will be set + * to a newly allocated string containing the + * presentation format of the name. The caller + * is responsible for deallocate this space with free(). + * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR + * when the wireformat name could not be parsed. */ getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, char **fqdn_as_string); +/** + * Convert a domain name in presentation format to DNS wire format. + * @param fqdn_as_string The name to convert in presentation format. + * @param dns_name_wire_fmt A reference to a pointer that will be set + * to a newly allocated bindata containing the + * DNS wire format of the name. The caller + * is responsible for deallocate this space with free(). + * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR + * when the presentation format name could not be parsed. + */ getdns_return_t getdns_convert_fqdn_to_dns_name( const char *fqdn_as_string, getdns_bindata **dns_name_wire_fmt); +/** + * Convert an Unicode encoded label to ASCII encoding following the + * rules for IDNA 2008 described in RFC 5890-5892. + * @param ulabel The Unicode encoded label to convert. + * @return The ASCII encoding label. The caller is responsible for deallocate + * this space with free(). + */ char *getdns_convert_ulabel_to_alabel(const char *ulabel); +/** + * Convert an ASCII encoded label to Unicode encoding following the + * rules for IDNA 2008 described in RFC 5890-5892. + * @param alabel The ASCII encoded label to convert. + * @return The Unicode encoding label. The caller is responsible for + * deallocation with free(). + */ char *getdns_convert_alabel_to_ulabel(const char *alabel); +/** + * Offline DNSSEC validate Resource Records with the help of support + * records and a DNSSEC trust anchor. + * @param to_validate This is a list of reply_dicts to validate (as can + * be seen under "replies_tree" in a response dict), or + * an RRset with signatures represented as a list of + * rr_dicts. The format of rr_dict can be seen in + * the sections of reply_dicts in response dicts. + * It is also possible to validate the non-existance + * of a query. Besides all the necessary NSEC(3)s plus + * signature, the to_validate should then also contain + * a question rr_dict with a qname, qclass and qtype. + * @param support_records A list of all the DNSKEY, DS and NSEC(3) RRsets + * (in the form of rr_dicts) that may be used to + * validate the RRsets or replies in to_validate. + * The value returned under "validation_chain" in a + * response dict when the dnssec_return_validation_chain + * extension was used, can be used directly for this. + * @param trust_anchors A list of rr_dicts containing the DNSSEC trust anchors. + * The return value of the getdns_root_trust_anchor() + * can be used directly for this. + * @return The function returns one of GETDNS_DNSSEC_SECURE, + * GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, or GETDNS_DNSSEC_INSECURE + * depending on the validation status. + */ getdns_return_t getdns_validate_dnssec(getdns_list *to_validate, getdns_list *support_records, getdns_list *trust_anchors); -/* Get root trust anchor */ +/** + * Get the default list of trust anchor records that is used by the library + * to validate DNSSEC. + * @param utc_date_of_anchor Set to the number of seconds since epoch + * the trust anchors were obtained + * @return The list of DNSSEC trust anchors, or NULL on error. The caller is + * responsible for deallocating the list with getdns_list_destroy(). + */ getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor); /** @@ -1227,6 +1341,13 @@ getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor); */ char *getdns_pretty_print_dict(const getdns_dict *some_dict); +/** + * Converts a getdns_bindata representing an IPv4 or IPv6 address to a + * textual representation. + * @param bindata_of_ipv4_or_ipv6_address The IP address to convert. + * @return character array (caller must free this) containing the textual + * representation of the address. + */ char *getdns_display_ip_address(const getdns_bindata *bindata_of_ipv4_or_ipv6_address); @@ -1238,6 +1359,16 @@ char *getdns_display_ip_address(const getdns_bindata * \addtogroup context_set getdns_context_set functions * @{ */ + +/** + * An application can be notified when the context is changed. + * @param context The context for which to monitor changes + * @param value The callback function that will be called when any context is + * changed. A update callback function can be deregistered by + * passing NULL. + * @return GETDNS_RETURN_GOOD when succesful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_context_update_callback( getdns_context *context, @@ -1245,73 +1376,339 @@ getdns_context_set_context_update_callback( getdns_context_code_t changed_item) ); +/** + * Specify whether DNS queries are performed with recursive lookups or as a + * stub resolver. The default value is GETDNS_RESOLUTION_RECURSING. + * @param context The context to configure + * @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown resolution types + * @return GETDNS_RETURN_NOT_IMPLEMENTED when getdns was compiled for stub + * resolution only and recursing resolution type was requested. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_resolution_type(getdns_context *context, getdns_resolution_t value); +/** + * 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 + * @param context The context to configure + * @param namespace_count The number of values in the namespaces list. + * @param 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. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown namespace types + * @return 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. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_namespaces(getdns_context *context, size_t namespace_count, getdns_namespace_t *namespaces); +/** + * 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. + * @param context The context to configure + * @param 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. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_dns_transport(getdns_context *context, getdns_transport_t value); +/** + * 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. + * @param context The context to configure + * @param transport_count The number of values in the transports list. + * @param 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 + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_dns_transport_list(getdns_context *context, size_t transport_count, getdns_transport_list_t *transports); +/** + * 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. + * @param context The context to configure + * @param timeout The number of milliseconds the API will leave an idle TCP + * or TLS connection open for + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_idle_timeout(getdns_context *context, uint64_t timeout); +/** + * 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. + * @param context The context to configure + * @param limit The maximum number of outstanding DNS queries. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_limit_outstanding_queries(getdns_context *context, uint16_t limit); +/** + * Specifies number of milliseconds the API will wait for request to return. + * The default is 5000 (i.e. 5 seconds). + * @param context The context to configure + * @param timeout The number of milliseconds the API will wait for request to + * return. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER for a timeout 0, + * or when context was NULL + */ getdns_return_t getdns_context_set_timeout(getdns_context *context, uint64_t timeout); +/** + * 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. + * @param context The context to configure + * @param 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. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER for an unknown value, + * or when context was NULL + */ getdns_return_t getdns_context_set_follow_redirects(getdns_context *context, getdns_redirects_t value); +/** + * Configure the list of addresses to be used for looking up top-level domains. + * The default is the list of "normal" IANA root servers + * @param context The context to configure + * @param 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). + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL when there were problems + * parsing the provided addresses list. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dns_root_servers(getdns_context *context, getdns_list *addresses); +/** + * 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. + * @param context The context to configure + * @param 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. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_append_name(getdns_context *context, getdns_append_name_t 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. + * @param context The context to configure + * @param value A list of bindatas that are strings that are to be appended + * based on the value off the append_name setting. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_suffix(getdns_context *context, getdns_list *value); +/** + * Specify the DNSSEC trust anchors. The default is to read it from + * @TRUST_ANCHOR_FILE@. + * @param context The context to configure + * @param value A list of rr_dicts for DS or DNSKEY that are the DNSSEC + * trust anchors. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dnssec_trust_anchors(getdns_context *context, getdns_list *value); +/** + * Specify the DNSSEC allowed skew. The default is 0. + * @param context The context to configure + * @param value The number of seconds of skew that is allowed in either + * direction when checking an RRSIG's Expiration and Inception + * fields. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dnssec_allowed_skew(getdns_context *context, uint32_t value); + +/** + * 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. + * @param context The context to configure + * @param 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 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. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when `context` or `upstream_list` was `NULL` + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL when there were problems parsing + * the `upstream_list`. + */ getdns_return_t getdns_context_set_upstream_recursive_servers(getdns_context *context, getdns_list *upstream_list); +/** + * 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. + * @param context The context to configure + * @param value The maximum UDP payload size advertised in a EDNS0 OPT record. + * The value must be between 512 and 65536 + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_maximum_udp_payload_size(getdns_context *context, uint16_t value); +/** + * Set the rcode advertised in a EDNS0 OPT record. The default is 0. + * @param context The context to configure + * @param value A value between 0 and 255. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_extended_rcode(getdns_context *context, uint8_t value); +/** + * Set the version advertised in a EDNS0 OPT record. The default is 0. + * @param context The context to configure + * @param value A value between 0 and 255. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_version(getdns_context *context, uint8_t value); +/** + * Set the DO 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. + * @param context The context to configure + * @param value A value between 0 and 1. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_do_bit(getdns_context *context, uint8_t value); +/** + * 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. + * @param context The context to configure + * @param malloc A custom memory allocator. The default is `malloc`. + * @param realloc A custom memory reallocator. The default is `realloc`. + * @param free A custom memory deallocator. The default is `free`. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_memory_functions(getdns_context *context, void *(*malloc) (size_t), @@ -1319,6 +1716,22 @@ getdns_context_set_memory_functions(getdns_context *context, void (*free) (void *) ); +/** + * 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. + * @param context The context to configure + * @param userarg This value will be passed as the `userarg` argument to the + * custom `malloc`, `realloc` and `free` function. + * @param malloc A custom memory allocator. The default is a wrapper for `malloc`. + * @param realloc A custom memory reallocator. The default is a wrapper for `realloc`. + * @param free A custom memory deallocator. The default is a wrapper for `free`. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_extended_memory_functions(getdns_context *context, void *userarg, @@ -1329,7 +1742,22 @@ getdns_context_set_extended_memory_functions(getdns_context *context, /** @} */ -/* api information support */ +/** + * Retrieve information about the API itself and inspect the current context. + * The returned dictionary can be used with getdns_context_config() directly + * to configure another context with precisely these settings. + * @param context The context from which to get the information + * @return A getdns_dict containing the following name/value pairs: + * - `version_string` (a bindata) represents the version string for this version of the DNS API. + * - `implementation_string` (a bindata) is a string showing which + * implementation of the getdns API this is. In our implementation + * this will always be set to "https://getdnsapi.net" + * - resolution_type (an int) is the type of resolver that the API is + * acting as in this context: GETDNS_RESOLUTION_RECURSING or + * GETDNS_RESOLUTION_STUB. + * - all_context (a dict) with names for all the other settings in + * context. + */ getdns_dict* getdns_context_get_api_information(getdns_context* context); From 708e520989001bda926ebf6ab8f98549d9698866 Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Tue, 11 Apr 2017 23:33:24 +0200 Subject: [PATCH 3/6] Spelling fixes from Andreas Schulze --- ChangeLog | 3 ++- doc/getdns_address.3.in | 2 +- doc/getdns_cancel_callback.3.in | 2 +- doc/getdns_context.3.in | 4 ++-- doc/getdns_context_set.3.in | 2 +- doc/getdns_context_set_context_update_callback.3.in | 2 +- doc/getdns_convert.3.in | 2 +- doc/getdns_dict.3.in | 2 +- doc/getdns_dict_get.3.in | 2 +- doc/getdns_dict_set.3.in | 2 +- doc/getdns_display_ip_address.3.in | 2 +- doc/getdns_general.3.in | 2 +- doc/getdns_hostname.3.in | 2 +- doc/getdns_list.3.in | 2 +- doc/getdns_list_get.3.in | 2 +- doc/getdns_list_set.3.in | 2 +- doc/getdns_pretty_print_dict.3.in | 2 +- doc/getdns_root_trust_anchor.3.in | 2 +- doc/getdns_service.3.in | 2 +- doc/getdns_validate_dnssec.3.in | 2 +- doc/libgetdns.3.in | 4 ++-- src/stub.c | 2 +- src/test/tests_transports.sh | 4 ++-- src/tools/getdns_query.c | 8 ++++---- src/types-internal.h | 2 +- 25 files changed, 32 insertions(+), 31 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1299763c..5a8b7140 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,5 @@ * 2017-04-??: Version 1.1.0 + * Spelling fixes. Thanks Andreas Schulze. * bugfix: Reschedule request timeout when getting the DNSSEC chain. * getdns_context_unset_edns_maximum_udp_payload_size() to reset to default IPv4/IPv6 dependent edns max udp payload size. @@ -176,7 +177,7 @@ '-1' to append suffix only to single label after failure '-M' to append suffix only to multi label name after failure '-N' to never append a suffix - '-Z ' to set suffixes with the given comma separed list + '-Z ' to set suffixes with the given comma separated list * Better help text for getdns_query (printed with the '-h' option) * Setting the +specify_class extension with getdns_query * Return NOT_IMPLEMENTED for not implemented namespaces, and the diff --git a/doc/getdns_address.3.in b/doc/getdns_address.3.in index 122f2392..561518d9 100644 --- a/doc/getdns_address.3.in +++ b/doc/getdns_address.3.in @@ -33,7 +33,7 @@ -- get ip address(es) for a name .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_cancel_callback.3.in b/doc/getdns_cancel_callback.3.in index 012bd3ef..297e3053 100644 --- a/doc/getdns_cancel_callback.3.in +++ b/doc/getdns_cancel_callback.3.in @@ -32,7 +32,7 @@ -- cancel an outstanding asyn getdns request .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_context.3.in b/doc/getdns_context.3.in index 71ed4b15..6fb089bb 100644 --- a/doc/getdns_context.3.in +++ b/doc/getdns_context.3.in @@ -39,7 +39,7 @@ .ad n .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include @@ -141,7 +141,7 @@ in use might have a requirements on this issue. You may need to provide one or two functions to allow it to function properly. For example before you call getdns_context_create() you may need to use the openssl functions CRYPTO_set_id_callback and CRYPTO_set_locking_callback to set up -asyncronous operation (the application calls these functions once for initialisation). +asynchronous operation (the application calls these functions once for initialisation). Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function. .HP 3 diff --git a/doc/getdns_context_set.3.in b/doc/getdns_context_set.3.in index 606a653d..b97bc243 100644 --- a/doc/getdns_context_set.3.in +++ b/doc/getdns_context_set.3.in @@ -45,7 +45,7 @@ .ad n .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_context_set_context_update_callback.3.in b/doc/getdns_context_set_context_update_callback.3.in index d85b1b3e..d51b34ff 100644 --- a/doc/getdns_context_set_context_update_callback.3.in +++ b/doc/getdns_context_set_context_update_callback.3.in @@ -32,7 +32,7 @@ -- get informed on getdns context updates .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_convert.3.in b/doc/getdns_convert.3.in index 25614585..fb8fca91 100644 --- a/doc/getdns_convert.3.in +++ b/doc/getdns_convert.3.in @@ -34,7 +34,7 @@ -- convert dname between presentation- and wire-format .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_dict.3.in b/doc/getdns_dict.3.in index d4d9b3b9..2ee2b45c 100644 --- a/doc/getdns_dict.3.in +++ b/doc/getdns_dict.3.in @@ -38,7 +38,7 @@ .ad n .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_dict_get.3.in b/doc/getdns_dict_get.3.in index 956c0523..45c71870 100644 --- a/doc/getdns_dict_get.3.in +++ b/doc/getdns_dict_get.3.in @@ -38,7 +38,7 @@ -- get value by name from a getdns dict .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_dict_set.3.in b/doc/getdns_dict_set.3.in index ee684090..f42e455a 100644 --- a/doc/getdns_dict_set.3.in +++ b/doc/getdns_dict_set.3.in @@ -36,7 +36,7 @@ -- set a value by name in a getdns dict .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_display_ip_address.3.in b/doc/getdns_display_ip_address.3.in index a038f4e9..08ea7da1 100644 --- a/doc/getdns_display_ip_address.3.in +++ b/doc/getdns_display_ip_address.3.in @@ -32,7 +32,7 @@ -- convert an getdns ip address to string .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_general.3.in b/doc/getdns_general.3.in index 9b983d0d..27b25574 100644 --- a/doc/getdns_general.3.in +++ b/doc/getdns_general.3.in @@ -33,7 +33,7 @@ -- do a getdns DNS lookup .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_hostname.3.in b/doc/getdns_hostname.3.in index e45c3620..25f53b39 100644 --- a/doc/getdns_hostname.3.in +++ b/doc/getdns_hostname.3.in @@ -33,7 +33,7 @@ -- get hostname by address .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_list.3.in b/doc/getdns_list.3.in index 2bbd8f3c..47a17272 100644 --- a/doc/getdns_list.3.in +++ b/doc/getdns_list.3.in @@ -38,7 +38,7 @@ .ad n .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_list_get.3.in b/doc/getdns_list_get.3.in index 1749ef08..d58d6851 100644 --- a/doc/getdns_list_get.3.in +++ b/doc/getdns_list_get.3.in @@ -38,7 +38,7 @@ -- get a value by index from a getdns list .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_list_set.3.in b/doc/getdns_list_set.3.in index 301bb882..cbba6959 100644 --- a/doc/getdns_list_set.3.in +++ b/doc/getdns_list_set.3.in @@ -36,7 +36,7 @@ -- set a value by index from a getdns list .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_pretty_print_dict.3.in b/doc/getdns_pretty_print_dict.3.in index 7ab966e3..e3e9f73e 100644 --- a/doc/getdns_pretty_print_dict.3.in +++ b/doc/getdns_pretty_print_dict.3.in @@ -32,7 +32,7 @@ -- return a string representation of a getdns dict .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_root_trust_anchor.3.in b/doc/getdns_root_trust_anchor.3.in index 401cd297..3d16b238 100644 --- a/doc/getdns_root_trust_anchor.3.in +++ b/doc/getdns_root_trust_anchor.3.in @@ -32,7 +32,7 @@ -- return the getdns list of default root trust anchors .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_service.3.in b/doc/getdns_service.3.in index 35f40579..ab03c880 100644 --- a/doc/getdns_service.3.in +++ b/doc/getdns_service.3.in @@ -33,7 +33,7 @@ -- getdns lookup of a service .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/getdns_validate_dnssec.3.in b/doc/getdns_validate_dnssec.3.in index bce70b85..a97ca72e 100644 --- a/doc/getdns_validate_dnssec.3.in +++ b/doc/getdns_validate_dnssec.3.in @@ -32,7 +32,7 @@ -- DNSSEC validate a given getdns record .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include diff --git a/doc/libgetdns.3.in b/doc/libgetdns.3.in index 0c4d2ece..791ed384 100644 --- a/doc/libgetdns.3.in +++ b/doc/libgetdns.3.in @@ -32,7 +32,7 @@ libgetdns -- an implementation of a modern asynchronous DNS API by and for application developers .SH LIBRARY -DNS Resolver library (libgetdns, -lgetdns) +DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS .B libgetdns @@ -230,7 +230,7 @@ Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each DNS record in .HP 3 "dnssec_return_only_secure" (int) -Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure withe DNSSEC to be returned in the +Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC to be returned in the .I replies_tree and .I replies_full lists diff --git a/src/stub.c b/src/stub.c index 3597cb88..2fa121f1 100644 --- a/src/stub.c +++ b/src/stub.c @@ -750,7 +750,7 @@ stub_tcp_read(int fd, getdns_tcp_state *tcp, struct mem_funcs *mf) /* stub_tcp_write(fd, tcp, netreq) * will return STUB_TCP_AGAIN when we need to come back again, - * STUB_TCP_ERROR on error and a query_id on successfull sent. + * STUB_TCP_ERROR on error and a query_id on successful sent. */ static int stub_tcp_write(int fd, getdns_tcp_state *tcp, getdns_network_req *netreq) diff --git a/src/test/tests_transports.sh b/src/test/tests_transports.sh index 0cb0947b..89604038 100755 --- a/src/test/tests_transports.sh +++ b/src/test/tests_transports.sh @@ -10,7 +10,7 @@ TLS_SERVER_KEY="foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S=" TLS_SERVER_SS_KEY="pOXrpUt9kgPgbWxBFFcBTbRH2heo2wHwXp1fd4AEVXI=" TLS_SERVER_WRONG_KEY="foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc1S=" GOOD_RESULT_SYNC="Status was: At least one response was returned" -GOOD_RESULT_ASYNC="successfull" +GOOD_RESULT_ASYNC="successful" BAD_RESULT_SYNC="1 'Generic error'" BAD_RESULT_ASYNC="callback_type of 703" NUM_ARGS=3 @@ -196,4 +196,4 @@ done echo echo "Finished transport test: did $COUNT queries, $GOOD_COUNT passes, $FAIL_COUNT failures" -echo \ No newline at end of file +echo diff --git a/src/tools/getdns_query.c b/src/tools/getdns_query.c index 7dca01fe..72eb19b2 100644 --- a/src/tools/getdns_query.c +++ b/src/tools/getdns_query.c @@ -219,7 +219,7 @@ print_usage(FILE *out, const char *progname) } fprintf(out, "\t-D\tSet edns0 do bit\n"); fprintf(out, "\t-d\tclear edns0 do bit\n"); - fprintf(out, "\t-e \tSet idle timeout in miliseconds\n"); + fprintf(out, "\t-e \tSet idle timeout in milliseconds\n"); if (!i_am_stubby) fprintf(out, "\t-F \tread the queries from the specified file\n"); fprintf(out, "\t-f \tRead DNSSEC trust anchors from \n"); @@ -253,7 +253,7 @@ print_usage(FILE *out, const char *progname) , i_am_stubby ? "" : "(default = recursing)" ); if (!i_am_stubby) fprintf(out, "\t-S\tservice lookup ( is ignored)\n"); - fprintf(out, "\t-t \tSet timeout in miliseconds\n"); + fprintf(out, "\t-t \tSet timeout in milliseconds\n"); fprintf(out, "\t-v\tPrint getdns release version\n"); fprintf(out, "\t-x\tDo not follow redirects\n"); fprintf(out, "\t-X\tFollow redirects (default)\n"); @@ -263,7 +263,7 @@ print_usage(FILE *out, const char *progname) fprintf(out, "\t-1\tAppend suffix only to single label after failure\n"); fprintf(out, "\t-M\tAppend suffix only to multi label name after failure\n"); fprintf(out, "\t-N\tNever append a suffix\n"); - fprintf(out, "\t-Z \tSet suffixes with the given comma separed list\n"); + fprintf(out, "\t-Z \tSet suffixes with the given comma separated list\n"); fprintf(out, "\t-T\tSet transport to TCP only\n"); fprintf(out, "\t-O\tSet transport to TCP only keep connections open\n"); @@ -384,7 +384,7 @@ void callback(getdns_context *context, getdns_callback_type_t callback_type, } if (callback_type == GETDNS_CALLBACK_COMPLETE) { - printf("Response code was: GOOD. Status was: Callback with ID %"PRIu64" was successfull.\n", + printf("Response code was: GOOD. Status was: Callback with ID %"PRIu64" was successful.\n", trans_id); } else if (callback_type == GETDNS_CALLBACK_CANCEL) diff --git a/src/types-internal.h b/src/types-internal.h index e70d8911..22cf649a 100644 --- a/src/types-internal.h +++ b/src/types-internal.h @@ -345,7 +345,7 @@ typedef struct getdns_dns_req { /* the transaction id */ getdns_transaction_t trans_id; - /* Absolute time (in miliseconds since epoch), + /* Absolute time (in milliseconds since epoch), * after which this dns request is expired; i.e. timed out */ uint64_t expires; From 68a87e4ceeb2d0d166e23732582733b2d03e809c Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Wed, 12 Apr 2017 11:21:25 +0200 Subject: [PATCH 4/6] Event loop extension functions documentation --- src/getdns/getdns_ext_libev.h | 16 ++- src/getdns/getdns_ext_libevent.h | 16 ++- src/getdns/getdns_ext_libuv.h | 16 ++- src/getdns/getdns_extra.h.in | 174 ++++++++++++++++++++++++++++--- 4 files changed, 205 insertions(+), 17 deletions(-) diff --git a/src/getdns/getdns_ext_libev.h b/src/getdns/getdns_ext_libev.h index c65ef8d3..3a39530f 100644 --- a/src/getdns/getdns_ext_libev.h +++ b/src/getdns/getdns_ext_libev.h @@ -48,7 +48,21 @@ struct ev_loop; /** * \ingroup eventloops */ -/* For libevent, which we are using for these examples */ +/** + * Associate the libev ev_loop with the context, so that all + * asynchronous requests will schedule Input/Output with it. + * Synchronous requests will still use a default eventloop based on `poll()`. + * Applications need to @code #include @endcode + * and link with libgetdns_ext_ev to use this function. + * getdns needs to have been configured with --with-libev for this + * extension to be available. + * @param context The context to configure + * @param ev_loop The libev event loop to associate with this context. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL + * @return GETDNS_RETURN_INVALID_PARAMETER when ev_loop is NULL + * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated + */ getdns_return_t getdns_extension_set_libev_loop(struct getdns_context *context, struct ev_loop *ev_loop); diff --git a/src/getdns/getdns_ext_libevent.h b/src/getdns/getdns_ext_libevent.h index de364e3f..a7fbc9b5 100644 --- a/src/getdns/getdns_ext_libevent.h +++ b/src/getdns/getdns_ext_libevent.h @@ -47,7 +47,21 @@ struct event_base; /** * \ingroup eventloops */ -/* For libevent, which we are using for these examples */ +/** + * Associate the libevent event_base with the context, so that all + * asynchronous requests will schedule Input/Output with it. + * Synchronous requests will still use a default eventloop based on `poll()`. + * Applications need to @code #include @endcode + * and link with libgetdns_ext_event to use this function. + * getdns needs to have been configured with --with-libevent for this + * extension to be available. + * @param context The context to configure + * @param this_event_base The libevent event base to associate with this context. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL + * @return GETDNS_RETURN_INVALID_PARAMETER when this_event_base is NULL + * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated + */ getdns_return_t getdns_extension_set_libevent_base(struct getdns_context *context, struct event_base *this_event_base); diff --git a/src/getdns/getdns_ext_libuv.h b/src/getdns/getdns_ext_libuv.h index f8809149..03463499 100644 --- a/src/getdns/getdns_ext_libuv.h +++ b/src/getdns/getdns_ext_libuv.h @@ -47,7 +47,21 @@ struct uv_loop_s; /** * \ingroup eventloops */ -/* For libevent, which we are using for these examples */ +/** + * Associate the libuv uv_loop with the context, so that all + * asynchronous requests will schedule Input/Output with it. + * Synchronous requests will still use a default eventloop based on `poll()`. + * Applications need to @code #include @endcode + * and link with libgetdns_ext_uv to use this function. + * getdns needs to have been configured with --with-libuv for this + * extension to be available. + * @param context The context to configure + * @param uv_loop The libuv event loop to associate with this context. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_BAD_CONTEXT when context is NULL + * @return GETDNS_RETURN_INVALID_PARAMETER when uv_loop is NULL + * @return GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated + */ getdns_return_t getdns_extension_set_libuv_loop(struct getdns_context *context, struct uv_loop_s *uv_loop); diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index c49113dc..4d623803 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -157,69 +157,215 @@ typedef enum getdns_tls_authentication_t { * @{ */ +/** + * The type of callback function that is used by the callbacks in an + * getdns_eventloop_event. + * @param userarg This will have the value of the userarg attribute of the + * getdns_eventloop_event struct in which this callback was + * present. + */ typedef void (*getdns_eventloop_callback)(void *userarg); -/* context extension event data */ -typedef struct getdns_eventloop_event { + +typedef struct getdns_eventloop_event getdns_eventloop_event; +/** + * getdns uses an event loop abstraction layer to interface with event loop + * extensions. The extension accepts registration of getdns_eventloop_events + * and translates them to the underlying event loop API for which it is an + * extension. Also applications using getdns can use the abstraction layer + * themselves and in doing so inherit the flexibility being immediately + * compatible with all the event loop systems for which there is an extension + * already (i.e. libevent, libev and libuv). + */ +struct getdns_eventloop_event { + /** + * The userarg argument that will be passed to the + * getdns_eventloop_callbacks when they are fired. + */ void *userarg; + + /** + * When not NULL, it will be fired when the associated file descriptor + * is readable. + */ getdns_eventloop_callback read_cb; + + /** + * When not NULL, it will be fired when the associated file descriptor + * is writable. + */ getdns_eventloop_callback write_cb; + + /** + * When not NULL, it will be fired when the during scheduling specified + * timeout time has passed. + */ getdns_eventloop_callback timeout_cb; - /* Pointer to the underlying event - * that the eventloop extension will create and free. + /** + * Pointer to the underlying event + * that an eventloop extension must manage (i.e. create and free.) */ void *ev; -} getdns_eventloop_event; +}; typedef struct getdns_eventloop_vmt getdns_eventloop_vmt; +/** + * The manifestation of the event loop abstraction layer. Event loop + * extension implementers should extend this with attributed needed for the + * underlying event loop. + * The current event loop extension can be obtained with the + * getdns_context_get_eventloop() function. + */ typedef struct getdns_eventloop { + /** + * The Virtual Method Table providing the interface for this specific + * event loop extension. + */ getdns_eventloop_vmt *vmt; } getdns_eventloop; -/* A prototype for a method having no arguments and not return value. */ +/** + * The function prototype for the `cleanup` and `run` functions in an getdns + * event loop's Virtual Method Table. These methods have no (extra) arguments + * and return nothing. + * @param loop The event loop to `run` or `cleanup` + */ typedef void (*getdns_eventloop_noargs)(getdns_eventloop *loop); -/* Call the extension to schedule an event - * +/** + * The function prototype for the `schedule` function in an event loop + * Virtual Method Table. * The getdns_eventloop_event must be provided by the caller with the callbacks * and userarg therein already supplied (by the caller). This function will set * the ev pointer (in the getdns_eventloop_event) to refer to the underlying * (extension) event. + * @param loop The event loop for which to register the event. + * @param fd The file descriptor for which to schedule the read_cb and/or + * write_cb callbacks. + * @param timeout The number of milliseconds that must pass without read + * and/or write event after which the timeout_cb callback is fired. + * @param ev The event with all attributes provisioned, except for the ev->ev + * attribute, which will be provisioned by the implementation of + * the schedule method. + * @return GETDNS_RETURN_GOOD when successful and an error code otherwise. */ typedef getdns_return_t (*getdns_eventloop_schedule)(getdns_eventloop *loop, int fd, uint64_t timeout, getdns_eventloop_event *ev); -/* Call the extension to clean a scheduled event */ +/** + * The function prototype for the `clean` function in an event loop + * Virtual Method Table. + * The implementation must clear the event (which is referred to with + * ev->ev) in the underlying event loop and make ev->ev NULL when done. + * getdns will test for this value to determine if events are scheduled or not. + * @param loop The event loop for which to event needs to be cleared. + * @param ev [in,out] The event with the ev->ev attribute referring to the + * underlying event. ev->ev must be set to NULL after the event + * was cleared. + * @return GETDNS_RETURN_GOOD when successful and an error code otherwise. + */ typedef getdns_return_t (*getdns_eventloop_clear) (getdns_eventloop *loop, getdns_eventloop_event *ev); +/** + * The function prototype for the `run_once` function in an event loop + * Virtual Method Table. The implementation must do a single round of + * firing callbacks, either blocking or not. + * @param loop The event loop to run + * @param blocking When 0, only callbacks for file descriptors that are + * immediately readable or writable or timeouts that have + * passed will be fired. When 1, the eventloop will wait + * until the first callback can be fired, either because a + * associated file descriptor has become readable or writeable, + * or because a timeout time passed. + */ typedef void (*getdns_eventloop_run_once)(getdns_eventloop *loop,int blocking); - /* Virtual Method Table */ +/** + * The Virtual Method Table providing the interface for this specific + * event loop extension. + */ struct getdns_eventloop_vmt { + /** + * Destroy the getdns_eventloop and the associated underlying event + * loop for which it is an extension. + */ getdns_eventloop_noargs cleanup; + + /** + * Schedule a getdns_eventloop_event with a getdns_eventloop. + */ getdns_eventloop_schedule schedule; + + /** + * Clear a getdns_eventloop_event + */ getdns_eventloop_clear clear; + + /** + * Run the getdns_eventloop until it has no getdns_eventloop_events + * scheduled. + */ getdns_eventloop_noargs run; + + /** + * Do a single iteration of firing callbacks for scheduled events + * and then return. + */ getdns_eventloop_run_once run_once; }; -/* set an event loop extension on the context */ +/** + * Configure a context to use the specified event loop abstraction extension. + * This function must be called with an provisioned eventloop by the + * event loop extension registration functions. + * @param context The context to configure + * @param eventloop The event loop abstraction extension with a completely + * provisioned Virtual Method Table and other associated + * data which is opaque to the user. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or eventloop were NULL. + */ getdns_return_t getdns_context_set_eventloop(getdns_context* context, getdns_eventloop *eventloop); -/* get the currently active (pluggable) eventloop from the context */ +/** + * Get the current event loop abstraction extension from the context + * Applications using getdns can use the event loop abstraction extension + * themselves directly to inherit the flexibility being immediately + * compatible with all the event loop systems for which there is an extension + * (i.e. libevent, libev and libuv). + * @param context [in] The context to get the eventloop from + * @param eventloop [out] The currently active event loop abstraction extension + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or evenloop were NULL + */ getdns_return_t getdns_context_get_eventloop(getdns_context* context, getdns_eventloop **eventloop); -/* detach the eventloop from the context */ +/** + * Detach the eventloop from the context. Resets the context with the default + * event loop based on poll(). WARNING! Do not use this function. It is For + * internal use only and may disappear in future releases. + * @param context The context to reset to default event loop usage + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context is NULL + */ getdns_return_t getdns_context_detach_eventloop(getdns_context *context); -/* Run the context's event loop until nothing more to do */ +/** + * Run the context's event loop until nothing more to do. + * This is equivalend to: + * ```c + * if (getdns_context_get_eventloop(context, &loop) == GETDNS_RETURN_GOOD) + * loop->vmt->run(loop); + * ``` + * @param context The context which event loop to run. + */ void getdns_context_run(getdns_context *context); /** @} From 2226c722a9c946be41529c84aaee2603c0e53bb0 Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Wed, 12 Apr 2017 12:35:46 +0200 Subject: [PATCH 5/6] Extra context setters --- src/getdns/getdns.h.in | 3 ++ src/getdns/getdns_extra.h.in | 99 ++++++++++++++++++++++++++++++++++-- src/mk-symfiles.sh | 2 +- 3 files changed, 98 insertions(+), 6 deletions(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index 618bb835..c984e69a 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -1362,6 +1362,9 @@ char *getdns_display_ip_address(const getdns_bindata /** * 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 . * @param context The context for which to monitor changes * @param value The callback function that will be called when any context is * changed. A update callback function can be deregistered by diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index 4d623803..02088978 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -392,36 +392,125 @@ getdns_return_t getdns_context_set_update_callback(getdns_context *context, void *userarg, void (*value) (getdns_context *, getdns_context_code_t, void *)); -/* Enable the return_dnssec_status extension on every request. - value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE - returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER - if context or value is invalid */ +/** + * Enable the return_dnssec_status extension on every request. + * @param context The context to configure + * @param value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context or value is invalid + */ getdns_return_t getdns_context_set_return_dnssec_status( getdns_context *context, int enabled); -/* tells underlying unbound to use background threads or fork */ +/** + * Tell underlying unbound context to use background threads or fork. + * This is only relevant for libunbound version before 1.5.9. After this + * version the underlying unbound will share the event loop with getdns + * eliminating the use for threads. Since the need for this function is + * doubtful and likely to disappear in the future, use is strongly + * discouraged. + * @param context The context to configure + * @param use_threads is either 1 to use threads, or 0 to use fork + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is NULL + */ getdns_return_t getdns_context_set_use_threads(getdns_context* context, int use_threads); +/** + * Configure context for oppertunistic or scrict usage profile with DNS + * over TLS. + * @param context The context to configure + * @param value is either GETDNS_AUTHENTICATION_REQUIRED for the strict + * usage profile or GETDNS_AUTHENTICATION_NONE for opportunistic + * profile. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an + * invalid value. + */ getdns_return_t getdns_context_set_tls_authentication( getdns_context *context, getdns_tls_authentication_t value); +/** + * Configure context to round robin queries over the available upstreams + * when resolving with the stub resolution type. + * @param context The context to configure + * @param value is either 1 to enable and 0 to disable round robin. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an + * invalid value. + */ getdns_return_t getdns_context_set_round_robin_upstreams(getdns_context *context, uint8_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. + * @param context The context to configure + * @param 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. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null. + */ getdns_return_t getdns_context_set_tls_backoff_time(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. + * @param context The context to configure + * @param value Number of attempts to retry setting up a DNS over TLS + * connection before giving up. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null. + */ getdns_return_t getdns_context_set_tls_connection_retries(getdns_context *context, uint16_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). + * @param context The context to configure + * @param value is either 1 to enable and 0 to disable. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an + * invalid value. + */ getdns_return_t getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_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). + * @param context The context to configure + * @param 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. + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an + * invalid value. + */ getdns_return_t getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value); +/** + * 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. + * @param context The context to configure + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is null. + */ getdns_return_t getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context); /** @} diff --git a/src/mk-symfiles.sh b/src/mk-symfiles.sh index 878196b9..597657b7 100755 --- a/src/mk-symfiles.sh +++ b/src/mk-symfiles.sh @@ -3,7 +3,7 @@ write_symbols() { OUTPUT=$1 shift - grep 'getdns_[0-9a-zA-Z_]*(' $* | grep -v '^#' | grep -v 'INLINE' \ + grep 'getdns_[0-9a-zA-Z_]*(' $* | grep -v '^#' | grep -v 'INLINE' | grep -v 'getdns_extra\.h\.in: \* if' \ | sed -e 's/(.*$//g' -e 's/^.*getdns_/getdns_/g' | LC_ALL=C sort | uniq > $OUTPUT } From 8c45f1fded99085e73087d7e225f797650746dba Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Wed, 12 Apr 2017 22:50:17 +0200 Subject: [PATCH 6/6] All remaining doxygen documentation Existing documentation needs to be reviewed too though... --- src/getdns/getdns.h.in | 27 ++- src/getdns/getdns_extra.h.in | 404 +++++++++++++++++++++++++++++++---- 2 files changed, 389 insertions(+), 42 deletions(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index c984e69a..bd1e36fd 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -1382,6 +1382,7 @@ getdns_context_set_context_update_callback( /** * Specify whether DNS queries are performed with recursive lookups or as a * stub resolver. The default value is GETDNS_RESOLUTION_RECURSING. + * @see getdns_context_get_resolution_type * @param context The context to configure * @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB. * @return GETDNS_RETURN_GOOD when successful @@ -1400,6 +1401,7 @@ getdns_context_set_resolution_type(getdns_context *context, * 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 getdns_context_get_namespaces * @param context The context to configure * @param namespace_count The number of values in the namespaces list. * @param namespaces An ordered list of namespaces that will be queried. @@ -1422,8 +1424,11 @@ getdns_context_set_namespaces(getdns_context *context, /** * 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() + * is discouraged. Please use #getdns_context_set_dns_transport_list() * instead of this function. + * @see getdns_context_get_dns_transport + * @see getdns_context_set_dns_transport_list + * @see getdns_context_get_dns_transport_list * @param context The context to configure * @param value The transport to use for DNS lookups. * The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP, @@ -1444,6 +1449,9 @@ getdns_context_set_dns_transport(getdns_context *context, * 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 getdns_context_get_dns_transport_list + * @see getdns_context_set_dns_transport + * @see getdns_context_get_dns_transport * @param context The context to configure * @param transport_count The number of values in the transports list. * @param transports An ordered list of transports that will be used for DNS @@ -1470,6 +1478,7 @@ getdns_context_set_dns_transport_list(getdns_context *context, * 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 getdns_context_get_idle_timeout * @param context The context to configure * @param timeout The number of milliseconds the API will leave an idle TCP * or TLS connection open for @@ -1487,6 +1496,7 @@ getdns_context_set_idle_timeout(getdns_context *context, uint64_t timeout); * 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 getdns_context_get_limit_outstanding_queries * @param context The context to configure * @param limit The maximum number of outstanding DNS queries. * @return GETDNS_RETURN_GOOD when successful. @@ -1499,6 +1509,7 @@ getdns_context_set_limit_outstanding_queries(getdns_context *context, /** * Specifies number of milliseconds the API will wait for request to return. * The default is 5000 (i.e. 5 seconds). + * @see getdns_context_get_timeout * @param context The context to configure * @param timeout The number of milliseconds the API will wait for request to * return. @@ -1517,6 +1528,7 @@ getdns_context_set_timeout(getdns_context *context, uint64_t timeout); * 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 getdns_context_get_follow_redirects * @param context The context to configure * @param value GETDNS_REDIRECTS_FOLLOW for normal following of redirects * through CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to @@ -1533,6 +1545,7 @@ getdns_context_set_follow_redirects(getdns_context *context, /** * 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 getdns_context_get_dns_root_servers * @param context The context to configure * @param addresses The list contains dicts that are addresses to be used for * looking up top-level domains. Each dict in the list @@ -1556,6 +1569,7 @@ getdns_context_set_dns_root_servers(getdns_context *context, * 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 getdns_context_get_append_name * @param context The context to configure * @param value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST, * GETDNS_APPEND_NAME_ALWAYS, @@ -1574,6 +1588,7 @@ getdns_context_set_append_name(getdns_context *context, * 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 getdns_context_get_suffix * @param context The context to configure * @param value A list of bindatas that are strings that are to be appended * based on the value off the append_name setting. @@ -1587,6 +1602,7 @@ getdns_context_set_suffix(getdns_context *context, getdns_list *value); /** * Specify the DNSSEC trust anchors. The default is to read it from * @TRUST_ANCHOR_FILE@. + * @see getdns_context_get_dnssec_trust_anchors * @param context The context to configure * @param value A list of rr_dicts for DS or DNSKEY that are the DNSSEC * trust anchors. @@ -1600,6 +1616,7 @@ getdns_context_set_dnssec_trust_anchors(getdns_context *context, /** * Specify the DNSSEC allowed skew. The default is 0. + * @see getdns_context_get_dnssec_allowed_skew * @param context The context to configure * @param value The number of seconds of skew that is allowed in either * direction when checking an RRSIG's Expiration and Inception @@ -1616,6 +1633,7 @@ getdns_context_set_dnssec_allowed_skew(getdns_context *context, * 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 getdns_context_get_upstream_recursive_servers * @param context The context to configure * @param upstream_list The upstreams are specified either by a getdns_bindata * containing a IPv4 or IPv6 address in network format @@ -1656,6 +1674,8 @@ getdns_context_set_upstream_recursive_servers(getdns_context *context, * 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 getdns_context_get_edns_maximum_udp_payload_size + * @see getdns_context_unset_edns_maximum_udp_payload_size * @param context The context to configure * @param value The maximum UDP payload size advertised in a EDNS0 OPT record. * The value must be between 512 and 65536 @@ -1668,6 +1688,7 @@ getdns_context_set_edns_maximum_udp_payload_size(getdns_context *context, /** * Set the rcode advertised in a EDNS0 OPT record. The default is 0. + * @see getdns_context_get_edns_extended_rcode * @param context The context to configure * @param value A value between 0 and 255. * @return GETDNS_RETURN_GOOD when successful. @@ -1679,6 +1700,7 @@ getdns_context_set_edns_extended_rcode(getdns_context *context, /** * Set the version advertised in a EDNS0 OPT record. The default is 0. + * @see getdns_context_get_edns_version * @param context The context to configure * @param value A value between 0 and 255. * @return GETDNS_RETURN_GOOD when successful. @@ -1688,9 +1710,10 @@ getdns_return_t getdns_context_set_edns_version(getdns_context *context, uint8_t value); /** - * Set the DO advertised in a EDNS0 OPT record. The default is 0. + * 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 getdns_context_get_edns_do_bit * @param context The context to configure * @param value A value between 0 and 1. * @return GETDNS_RETURN_GOOD when successful. diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index 02088978..bd41f51f 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -210,6 +210,7 @@ struct getdns_eventloop_event { }; typedef struct getdns_eventloop_vmt getdns_eventloop_vmt; + /** * The manifestation of the event loop abstraction layer. Event loop * extension implementers should extend this with attributed needed for the @@ -320,6 +321,7 @@ struct getdns_eventloop_vmt { * Configure a context to use the specified event loop abstraction extension. * This function must be called with an provisioned eventloop by the * event loop extension registration functions. + * @see getdns_context_get_eventloop * @param context The context to configure * @param eventloop The event loop abstraction extension with a completely * provisioned Virtual Method Table and other associated @@ -337,6 +339,7 @@ getdns_context_set_eventloop(getdns_context* context, * themselves directly to inherit the flexibility being immediately * compatible with all the event loop systems for which there is an extension * (i.e. libevent, libev and libuv). + * @see getdns_context_set_eventloop * @param context [in] The context to get the eventloop from * @param eventloop [out] The currently active event loop abstraction extension * @return GETDNS_RETURN_GOOD when successful @@ -346,17 +349,6 @@ getdns_return_t getdns_context_get_eventloop(getdns_context* context, getdns_eventloop **eventloop); -/** - * Detach the eventloop from the context. Resets the context with the default - * event loop based on poll(). WARNING! Do not use this function. It is For - * internal use only and may disappear in future releases. - * @param context The context to reset to default event loop usage - * @return GETDNS_RETURN_GOOD when successful - * @return GETDNS_RETURN_INVALID_PARAMETER when context is NULL - */ -getdns_return_t -getdns_context_detach_eventloop(getdns_context *context); - /** * Run the context's event loop until nothing more to do. * This is equivalend to: @@ -376,8 +368,10 @@ getdns_context_run(getdns_context *context); * \defgroup Ucontextset Additional getdns_context_set functions * @{ */ + /** * Register a callback function for context changes. + * @see getdns_context_set_context_update_callback * @param context The context to monitor for changes * @param userarg A user defined argument that will be passed to the callback * function. @@ -395,35 +389,23 @@ getdns_context_set_update_callback(getdns_context *context, void *userarg, /** * Enable the return_dnssec_status extension on every request. * @param context The context to configure - * @param value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE + * @param enabled is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_INVALID_PARAMETER if context or value is invalid */ getdns_return_t getdns_context_set_return_dnssec_status( getdns_context *context, int enabled); -/** - * Tell underlying unbound context to use background threads or fork. - * This is only relevant for libunbound version before 1.5.9. After this - * version the underlying unbound will share the event loop with getdns - * eliminating the use for threads. Since the need for this function is - * doubtful and likely to disappear in the future, use is strongly - * discouraged. - * @param context The context to configure - * @param use_threads is either 1 to use threads, or 0 to use fork - * @return GETDNS_RETURN_GOOD on success - * @return GETDNS_RETURN_INVALID_PARAMETER if context is NULL - */ -getdns_return_t getdns_context_set_use_threads(getdns_context* context, - int use_threads); - /** * Configure context for oppertunistic or scrict usage profile with DNS * over TLS. + * @see getdns_context_get_tls_authentication * @param context The context to configure * @param 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. * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_INVALID_PARAMETER if context is null or value has an * invalid value. @@ -435,6 +417,7 @@ getdns_context_set_tls_authentication( /** * Configure context to round robin queries over the available upstreams * when resolving with the stub resolution type. + * @see getdns_context_get_round_robin_upstreams * @param context The context to configure * @param value is either 1 to enable and 0 to disable round robin. * @return GETDNS_RETURN_GOOD on success @@ -448,6 +431,7 @@ getdns_context_set_round_robin_upstreams(getdns_context *context, uint8_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 getdns_context_get_tls_backoff_time * @param context The context to configure * @param value Number of seconds before an attempt to setup DNS over TLS, * with an upstream for which setting up an TLS connection has @@ -462,6 +446,7 @@ getdns_context_set_tls_backoff_time(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 getdns_context_get_tls_connection_retries * @param context The context to configure * @param value Number of attempts to retry setting up a DNS over TLS * connection before giving up. @@ -475,6 +460,7 @@ getdns_context_set_tls_connection_retries(getdns_context *context, uint16_t valu * 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 getdns_context_get_edns_client_subnet_private * @param context The context to configure * @param value is either 1 to enable and 0 to disable. * @return GETDNS_RETURN_GOOD on success @@ -488,6 +474,7 @@ getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t v * 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 getdns_context_get_tls_query_padding_blocksize * @param context The context to configure * @param value The requested block size to pad to, or 0 to disable, or 1 to * indicate that the library should use a sinsible policy. @@ -507,6 +494,8 @@ getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t * 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 getdns_context_set_edns_maximum_udp_payload_size + * @see getdns_context_get_edns_maximum_udp_payload_size * @param context The context to configure * @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_INVALID_PARAMETER if context is null. @@ -520,93 +509,345 @@ getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context); * \defgroup Ucontextget Additional getdns_context_get functions * @{ */ -/** begin getters **/ + +/** + * Get the current resolution type setting from this context. + * @see getdns_context_set_resolution_type + * @param context [in] The context from which to get the setting + * @param value [out] The resolution type, either GETDNS_RESOLUTION_RECURSING + * or GETDNS_RESOLUTION_STUB. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_resolution_type(getdns_context *context, getdns_resolution_t* value); -/** users must call free on the resulting namespaces if not NULL */ +/** + * Get a copy of the namespaces list setting from this context. + * Users must call free on the resulting namespaces if not NULL + * @see getdns_context_set_namespaces + * @param context [in] The context from which to get the setting + * @param namespace_count [out] The length of the list. + * @param namespaces [out] The returned namespaces list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL. + */ getdns_return_t getdns_context_get_namespaces(getdns_context *context, size_t* namespace_count, getdns_namespace_t **namespaces); +/** + * Get what transports are used for DNS lookups. + * @see getdns_context_set_dns_transport + * @see getdns_context_get_dns_transport_list + * @see getdns_context_set_dns_transport_list + * @param context [in] The context from which to get the setting + * @param value [out] The transport to use for DNS lookups. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL. + */ getdns_return_t getdns_context_get_dns_transport(getdns_context *context, getdns_transport_t* value); +/** + * Get a copy of the transports list setting from this context. + * Users must call free on the resulting transports if not NULL + * @see getdns_context_set_dns_transport_list + * @see getdns_context_get_dns_transport + * @see getdns_context_set_dns_transport + * @param context [in] The context from which to get the setting + * @param transport_count [out] The length of the list. + * @param transports [out] The returned transports list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL. + */ getdns_return_t getdns_context_get_dns_transport_list(getdns_context *context, size_t* transport_count, getdns_transport_list_t **transports); +/** + * Get the current limit for oustanding queries setting from this context. + * @see getdns_context_set_limit_outstanding_queries + * @param context [in] The context from which to get the setting + * @param limit [out] The current limit for oustanding queries + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL. + */ getdns_return_t getdns_context_get_limit_outstanding_queries(getdns_context *context, uint16_t* limit); +/** + * Get the current number of milliseconds the API will wait for request + * to return setting from this context. + * @see getdns_context_set_timeout + * @param context [in] The context from which to get the setting + * @param timeout [out] The number of milliseconds the API will wait for a + * response. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL. + */ getdns_return_t getdns_context_get_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 getdns_context_set_idle_timeout + * @param context [in] The context from which to get the setting + * @param timeout [out] The number of milliseconds the API will leave an idle TCP + * or TLS connection open for + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or timeout was NULL. + */ getdns_return_t getdns_context_get_idle_timeout(getdns_context *context, uint64_t* timeout); +/** + * Get the setting that says whether or not DNS queries follow redirects. + * @see getdns_context_set_follow_redirects + * @param context [in] The context from which to get the setting + * @param value [out] Either GETDNS_REDIRECTS_FOLLOW or GETDNS_REDIRECTS_DO_NOT_FOLLOW + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_follow_redirects(getdns_context *context, getdns_redirects_t* value); +/** + * 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 getdns_context_set_dns_root_servers + * @param context [in] The context from which to get the setting + * @param addresses [out] A copy of the list of dns root servers in use for + * looking up top level domains. The caller must + * destroy this list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or adresses was NULL. + * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated + */ getdns_return_t getdns_context_get_dns_root_servers(getdns_context *context, getdns_list **addresses); +/** + * Get whether, how and when a suffix is appended to a query string with + * the context. + * @see getdns_context_set_append_name + * @param context [in] The context from which to get the setting + * @param value [out] 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 + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_append_name(getdns_context *context, getdns_append_name_t* 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 getdns_context_set_suffix + * @param context [in] The context from which to get the setting + * @param value [out] A copy of the list of suffixes. The caller must destroy + * this list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated + */ getdns_return_t getdns_context_get_suffix(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 getdns_context_set_dnssec_trust_anchors + * @param context [in] The context from which to get the setting + * @param value [out] A copy of the list of DNSSEC trust anchors. + * The caller must destroy this list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated + */ getdns_return_t getdns_context_get_dnssec_trust_anchors(getdns_context *context, getdns_list **value); +/** + * Get the allowed DNSSEC skew setting from context + * @see getdns_context_set_dnssec_allowed_skew + * @param context [in] The context from which to get the setting + * @param value [out] The number of seconds of skew that is allowed in either + * direction when checking an RRSIG's Expiration and Inception + * fields. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_dnssec_allowed_skew(getdns_context *context, uint32_t* value); +/** + * 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 getdns_context_set_upstream_recursive_servers + * @param context [in] The context from which to get the setting + * @param upstream_list [out] A copy of the list of upstreams. + * The caller must destroy this list. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated + */ getdns_return_t getdns_context_get_upstream_recursive_servers(getdns_context *context, getdns_list **upstream_list); +/** + * Get the maximum UDP payload size advertised in an EDNS0 OPT record + * setting from context + * @see getdns_context_set_edns_maximum_udp_payload_size + * @see getdns_context_unset_edns_maximum_udp_payload_size + * @param context [in] The context from which to get the setting + * @param value [out] the maximum UDP payload size advertised in an EDNS0 + * OPT record. When the value is unset, 0 is returned. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_edns_maximum_udp_payload_size(getdns_context *context, uint16_t* value); +/** + * Get the rcode advertised in an EDNS0 OPT record setting from context + * @see getdns_context_set_edns_extended_rcode + * @param context [in] The context from which to get the setting + * @param value [out] The rcode advertised in an EDNS0 OPT record + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_edns_extended_rcode(getdns_context *context, uint8_t* value); +/** + * Get the version advertised in an EDNS0 OPT record setting from context + * @see getdns_context_set_edns_version + * @param context [in] The context from which to get the setting + * @param value [out] The version advertised in an EDNS0 OPT record + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_edns_version(getdns_context *context, uint8_t* value); +/** + * Get the DO bit advertised in an EDNS0 OPT record setting from context + * @see getdns_context_set_edns_do_bit + * @param context [in] The context from which to get the setting + * @param value [out] 1 if the DO bit is advertised in EDNS0 OPT records, + * 0 otherwise. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_edns_do_bit(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 getdns_context_set_edns_do_bit + * @param context [in] The context from which to get the setting + * @param value [out] 1 if the setting is on, 0 otherwise + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value); +/** + * Get the blocksize that will be used to pad outgoing queries over TLS. + * @see getdns_context_set_tls_query_padding_blocksize + * @param context [in] The context from which to get the setting + * @param value [out] The padding blocksize, or 0 if padding is disabled, + * or 1 if the setting is to pad using a sensible policy. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value); +/** + * Get whether the upstream needs to be authenticated whith DNS over TLS. + * @see getdns_context_set_tls_authentication + * @param context [in] The context from which to get the setting + * @param value [out] 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. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_tls_authentication(getdns_context *context, getdns_tls_authentication_t* value); +/** + * Get whether the context is configured to round robin queries over the available + * upstreams. + * @see getdns_context_get_round_robin_upstreams + * @param context [in] The context from which to get the setting + * @param value [out] 1 if the setting is on, 0 otherwise + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_round_robin_upstreams(getdns_context *context, uint8_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 getdns_context_set_tls_backoff_time + * @param context [in] The context from which to get the setting + * @param value [out] 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. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_tls_backoff_time(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 getdns_context_set_tls_connection_retries + * @param context [in] The context from which to get the setting + * @param value [out] Number of attempts to retry setting up a DNS over TLS + * connection before giving up. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context or value was NULL. + */ getdns_return_t getdns_context_get_tls_connection_retries(getdns_context *context, uint16_t* value); @@ -637,9 +878,36 @@ getdns_context_get_update_callback(getdns_context *context, void **userarg, * @{ */ +/** + * Get the version number of this implementation. + * @return The version number as string. For example "@GETDNS_VERSION@". + */ const char *getdns_get_version(void); + +/** + * Get the version number of this implementation as number. + * @return The version number as number. For example @GETDNS_NUMERIC_VERSION@. + * - The most significant byte of this uint32_t is the Major version. + * - The second most significant byte is the Minor version. + * - The third most significant byte the Patch version. + */ uint32_t getdns_get_version_number(void); + +/** + * Get the version of the getdns API specification this library implements + * as a string. + * @return The API specification version as string. For example "@API_VERSION@" + */ const char *getdns_get_api_version(void); + +/** + * Get the version of the getdns API specification this library implements + * as a number. + * @return The API specification version as number. For example "@API_NUMERIC_VERSION@" + * - The most significant 16 bits represent the year. + * - The third most significant byte the day. + */ + uint32_t getdns_get_api_version_number(void); /** @@ -651,16 +919,35 @@ uint32_t getdns_get_api_version_number(void); */ const char *getdns_get_errorstr_by_id(uint16_t err); -/* dict util */ -/* set a string as bindata */ -getdns_return_t getdns_dict_util_set_string(getdns_dict * dict, - char *name, const char *value); - -/* get a string from a dict. the result must be freed if valid */ -getdns_return_t getdns_dict_util_get_string(getdns_dict * dict, - char *name, char **result); - +/** + * Create a new entry in the dictionary, or replace the value of an existing + * entry, with a getdns_bindata representing a string. The string will be + * copied. The size of the bindata will be strlen(value), though there will + * be a '\0' byte directly after the size'd position even, though the size + * argument suggests that this would not be part of the bindata's date space. + * @see getdns_dict_set_bindata + * @param dict dictionary in which to add or change the value + * @param name key that identifies which item in the dictionary to add/change + * @param value string to be copied and stored in the bindata at key + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER when one of the arguments was NULL + * @return GETDNS_RETURN_MEMORY_ERROR when the copy could not be allocated + */ +getdns_return_t +getdns_dict_util_set_string(getdns_dict *dict, char *name, const char *value); +/** + * Get the string associated with the speicifed name. The string should not + * be free()'d by the caller. + * @see getdns_dict_get_bindata + * @param dict dictionary from which to fetch the bindata + * @param name a name/key value to look up in the dictionary + * @param result The bindata's data value + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_NO_SUCH_DICT_NAME if dict is invalid or name does not exist + */ +getdns_return_t +getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result); /** * Validate replies or resource records. @@ -1387,19 +1674,56 @@ getdns_reply(getdns_context *context, * \defgroup Uutilityfunctionsdeprecated Additional utility functions (will be deprecated) * @{ */ -/* WARNING! Function getdns_strerror is not in the API specification and +/** + * WARNING! Function getdns_strerror is not in the API specification and * is likely to be removed from future versions of our implementation, to be * replaced by getdns_get_errorstr_by_id or something similar. * Please use getdns_get_errorstr_by_id instead of getdns_strerror. */ getdns_return_t getdns_strerror(getdns_return_t err, char *buf, size_t buflen); +/** + * Runs the event loop once non blocking. + * WARNING! Do not use this function. This function will be removed in + * future versions of getdns. + */ getdns_return_t getdns_context_process_async(getdns_context* context); -/* Async support */ +/** + * Return the number of pending requests and the point of time of the next + * timeout. + * WARNING! Do not use this function. This function will be removed in + * future versions of getdns. + */ uint32_t getdns_context_get_num_pending_requests(getdns_context* context, struct timeval* next_timeout); +/** + * Detach the eventloop from the context. Resets the context with the default + * event loop based on poll(). WARNING! Do not use this function. It is For + * internal use only and may disappear in future releases. + * @param context The context to reset to default event loop usage + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context is NULL + */ +getdns_return_t +getdns_context_detach_eventloop(getdns_context *context); + +/** + * Tell underlying unbound context to use background threads or fork. + * This is only relevant for libunbound version before 1.5.9. After this + * version the underlying unbound will share the event loop with getdns + * eliminating the use for threads. Since the need for this function is + * doubtful and likely to disappear in the future, use is strongly + * discouraged. + * @param context The context to configure + * @param use_threads is either 1 to use threads, or 0 to use fork + * @return GETDNS_RETURN_GOOD on success + * @return GETDNS_RETURN_INVALID_PARAMETER if context is NULL + */ +getdns_return_t getdns_context_set_use_threads(getdns_context* context, + int use_threads); + /** @} */ /** @}