diff --git a/README.md b/README.md index 4f802fca..f89b77aa 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Traditional access to DNS data from applications has several limitations: * Sophisticated uses of the DNS (things like IDNA and DNSSEC validation) require considerable application work, possibly by application developers with little experience with the vagaries of DNS. -getdns also provides a experimental DNS Privacy enabled client called 'stubby' - see below for more details. +getdns also provides an experimental DNS Privacy enabled client called 'stubby' - see below for more details. ## Motivation for providing the API @@ -78,7 +78,7 @@ before building. As well as building the getdns library 2 other tools are installed by default by the above process: * getdns_query: a command line test script wrapper for getdns -* stubby: a experimental DNS Privacy enabled client +* stubby: an experimental DNS Privacy enabled client Note: If you only want to build stubby, then use the `--enable-stub-only` and `--without-libidn` options when running 'configure'. @@ -344,6 +344,7 @@ Contributors * Robert Groenenberg * Paul Hoffman * Scott Hollenbeck, Verising, Inc. +* Christian Huitema * Shumon Huque, Verisign Labs * Jelte Janssen * Guillem Jover @@ -358,6 +359,7 @@ Contributors * Joel Purra * Tom Pusateri * Prithvi Ranganath, Verisign, Inc. +* Hoda Rohani, NLnet Labs * Rushi Shah, Verisign, Inc. * Vinay Soni, Verisign, Inc. * Melinda Shore, No Mountain Software LLC diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index a6e82c6f..9d5274f6 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -126,7 +126,6 @@ typedef enum getdns_tls_authentication_t { /** @} */ - /** * \defgroup Uvaluesandtextsdepricated Additional transport values and texts (will be deprecated) * @{ @@ -227,15 +226,6 @@ getdns_context_run(getdns_context *context); */ -/** - * \defgroup contextfunction Additional getdns_context async functions - * @{ - */ -/* process async reqs */ -getdns_return_t getdns_context_process_async(getdns_context* context); -/** @} - */ - /** * \defgroup Ucontextset Additional getdns_context_set functions * @{ @@ -400,9 +390,6 @@ getdns_return_t getdns_context_get_update_callback(getdns_context *context, void **userarg, void (**value) (getdns_context *, getdns_context_code_t, void *)); -/* Async support */ -uint32_t getdns_context_get_num_pending_requests(getdns_context* context, - struct timeval* next_timeout); /** @} */ @@ -435,6 +422,8 @@ getdns_return_t getdns_dict_util_set_string(getdns_dict * dict, getdns_return_t getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result); + + /** * Validate replies or resource records. * @@ -521,6 +510,51 @@ getdns_return_t getdns_pubkey_pinset_sanity_check( const getdns_list* pinset, getdns_list* errorlist); +/** + * Configure a context with settings given in a getdns_dict. + * + * @param context The context to be configured. + * @param config_dict The getdns_dict containing the settings. + * The settings have the same name as returned by the + * getdns_context_get_api_information() function, or as + * used in the names of the getdns_context_get_*() and + * getdns_context_set_*() functions. + * - The dict returned by + * getdns_context_get_api_information() can be used + * as the config_dict directly, but context settings + * do *not* have to be below a `"all_context"` key. + * - It is possible to set default values for extensions + * that could otherwise only be given on a per query + * basis. For example: + * `{ dnssec_return_status: GETDNS_EXTENSION_TRUE }` is + * equivalent to using the + * getdns_context_set_return_dnssec_status() function + * with that value, but default values for the other + * extensions can be set by this method now too. + * For example + * `{ return_call_reporting: GETDNS_EXTENSION_TRUE}` + * - Trust anchor files and root hints content can also be + * given by file, for example: + * + * { dns_root_servers : "named.root" + * , dnssec_trust_anchors: "/etc/unbound/getdns-root.key" + * } + * @return GETDNS_RETURN_GOOD on success or an error code on failure. + * **Beware** that context might be partially configured on error. For retry + * strategies it is advised to recreate a new config. + */ +getdns_return_t +getdns_context_config(getdns_context *context, const getdns_dict *config_dict); + + + +/** @} + */ + +/** + * \defgroup UXTRAPrettyPrinting Pretty printing of getdns dicts and lists + * @{ + */ /** * Pretty print the getdns_dict in a given buffer snprintf style. @@ -617,6 +651,14 @@ getdns_snprint_json_list( char *str, size_t size, const getdns_list *list, int pretty); +/** @} + */ + +/** + * \defgroup UDNSDataConversionFunctions Functions for converting between getdns DNS dicts, DNS wire format and DNS presentation format + * @{ + */ + /** * Convert rr_dict to wireformat representation of the resource record. * @@ -930,6 +972,14 @@ getdns_return_t getdns_msg_dict2str_scan( const getdns_dict *msg_dict, char **str, int *str_len); +/** @} + */ + +/** + * \defgroup Ustring2getdns_data Functions for converting strings to getdns data structures + * @{ + */ + /** * Convert string text to a getdns_dict. * @@ -1018,42 +1068,13 @@ getdns_str2bindata(const char *str, getdns_bindata **bindata); getdns_return_t getdns_str2int(const char *str, uint32_t *value); -/** - * Configure a context with settings given in a getdns_dict. - * - * @param context The context to be configured. - * @param config_dict The getdns_dict containing the settings. - * The settings have the same name as returned by the - * getdns_context_get_api_information() function, or as - * used in the names of the getdns_context_get_*() and - * getdns_context_set_*() functions. - * - The dict returned by - * getdns_context_get_api_information() can be used - * as the config_dict directly, but context settings - * do *not* have to be below a `"all_context"` key. - * - It is possible to set default values for extensions - * that could otherwise only be given on a per query - * basis. For example: - * `{ dnssec_return_status: GETDNS_EXTENSION_TRUE }` is - * equivalent to using the - * getdns_context_set_return_dnssec_status() function - * with that value, but default values for the other - * extensions can be set by this method now too. - * For example - * `{ return_call_reporting: GETDNS_EXTENSION_TRUE}` - * - Trust anchor files and root hints content can also be - * given by file, for example: - * - * { dns_root_servers : "named.root" - * , dnssec_trust_anchors: "/etc/unbound/getdns-root.key" - * } - * @return GETDNS_RETURN_GOOD on success or an error code on failure. - * **Beware** that context might be partially configured on error. For retry - * strategies it is advised to recreate a new config. +/** @} */ -getdns_return_t -getdns_context_config(getdns_context *context, const getdns_dict *config_dict); +/** + * \defgroup UServerFunctions Functions for creating simple DNS servers + * @{ + */ /** * The user defined request handler that will be called on incoming requests. @@ -1133,6 +1154,13 @@ getdns_reply(getdns_context *context, * 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); + +getdns_return_t getdns_context_process_async(getdns_context* context); + +/* Async support */ +uint32_t getdns_context_get_num_pending_requests(getdns_context* context, + struct timeval* next_timeout); + /** @} */ /** @}