interesting
/
getdns
mirror of https://github.com/getdnsapi/getdns.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Rearrange doxygen into subject groups

This commit is contained in:
Willem Toorop 2017-04-13 20:30:59 +02:00
parent b4eecd59ab
commit a670606849
3 changed files with 1756 additions and 1144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2497
src/Doxyfile.in
View File

File diff suppressed because it is too large Load Diff

111
src/getdns/getdns.h.in
View File

@ -47,12 +47,12 @@ extern "C" {
#define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@"
/** \defgroup getdnsAPI Official getdns API
* @{
/**
* \defgroup functions Functions
* \defgroup valuesandtexts Values and texts
*/
/** \defgroup valuesandtexts Values and texts
/** \addtogroup valuesandtexts Values and texts
* @{
*/
@ -120,6 +120,7 @@ typedef enum getdns_return_t {
* \defgroup namespacetypestext Namespace types and texts
* @{
*/
typedef enum getdns_namespace_t {
GETDNS_NAMESPACE_DNS = 500,
GETDNS_NAMESPACE_LOCALNAMES = 501,
@ -546,31 +547,27 @@ typedef struct getdns_list getdns_list;
*/
/** \defgroup functions Functions
/** \addtogroup functions Functions
* @{
*/
/* Specify the order of the following groups manually here so they appear in
a better order in doxygen */
/**
* \defgroup list_create getdns_list creation/destruction functions
* \defgroup getdns_list_set getdns_list_set functions
* \defgroup getdns_list_get_functions getdns_list_get functions
* \defgroup dict_create getdns_dict creation/destruction functions
* \defgroup getdns_dict_set getdns_dict_set functions
* \defgroup getdns_dict_get_functions getdns_dict_get functions
* \defgroup context_create getdns_context creation/destruction functions
* \defgroup context_set getdns_context_set functions
* \defgroup callbackfns getdns_callback functions
* \defgroup eventloops getdns event loop extension functions
* \defgroup funcs Asynchronous API functions
* \defgroup syncfuncs Synchronous API functions that do not use callbacks
* \defgroup getdns_context Creating, destroying, configuring and reading configuration from getdns_contexts
* \defgroup getdns_dict Creating, destroying, reading from and manipulating getdns_dicts
* \defgroup getdns_list Creating, destroying, reading from and manipulating getdns_lists
* \defgroup asyncfuncs Scheduling asynchronous requests
* \defgroup syncfuncs Performing synchronous requests
* \defgroup eventloops Event loop extension functions
* \defgroup versionfuncs Version functions
* \defgroup dnssecfuncs DNSSEC functions
* \defgroup utils Utility functions
*/
/**
* \addtogroup getdns_list_get_functions getdns_list_get functions
* \addtogroup getdns_list
* @{
*/
@ -649,7 +646,7 @@ getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index,
/**
* \addtogroup getdns_dict_get_functions getdns_dict_get functions
* \addtogroup getdns_dict
* @{
*/
@ -723,7 +720,7 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
/**
* \addtogroup list_create getdns_list creation/destruction functions
* \addtogroup getdns_list
* @{
*/
@ -793,7 +790,7 @@ void getdns_list_destroy(getdns_list *list);
/**
* \addtogroup getdns_list_set getdns_list_set functions
* \addtogroup getdns_list
* @{
*/
@ -843,7 +840,7 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
/**
* \addtogroup dict_create getdns_dict creation/destruction functions
* \addtogroup getdns_dict
* @{
*/
@ -910,7 +907,7 @@ void getdns_dict_destroy(getdns_dict *dict);
/**
* \addtogroup getdns_dict_set getdns_dict_set functions
* \addtogroup getdns_dict
* @{
*/
@ -954,6 +951,14 @@ getdns_return_t getdns_dict_set_bindata(getdns_dict *dict,
*/
getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
uint32_t child_uint32);
/**
* creates a string that describes the dictionary in a human readable form
* one line per item in the dictionary
* @param some_dict dictionary to pretty print
* @return character array (caller must free this) containing pretty string
*/
char *getdns_pretty_print_dict(const getdns_dict *some_dict);
/** @}
*/
@ -968,14 +973,15 @@ getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
*/
getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
/**
* \addtogroup callbackfns getdns_callback functions
* \addtogroup asyncfuncs
* @{
*/
/**
* The type of the callback function that must be registered when scheduling
* asynchronous requests. The registered function will be called from the
* eventloop with the following parameters.
* @see callbacktype
* @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:
@ -1002,13 +1008,11 @@ typedef void (*getdns_callback_t) (getdns_context *context,
getdns_dict * response,
void *userarg, getdns_transaction_t transaction_id);
/**
* \addtogroup funcs Asynchronous API functions
* @{
*/
/**
* retrieve general DNS data
* @see rrtypes
* @see getdns_general_sync
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
@ -1028,6 +1032,7 @@ getdns_general(getdns_context *context,
/**
* retrieve address assigned to a DNS name
* @see getdns_address_sync
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param extensions dict data structures, NULL to use no extensions
@ -1045,6 +1050,7 @@ getdns_address(getdns_context *context,
/**
* retrieve hostname assigned to an IP address
* @see getdns_hostname_sync
* @param context pointer to a previously created context to be used for this call
* @param address the address to look up
* @param extensions dict data structures, NULL to use no extensions
@ -1062,6 +1068,7 @@ getdns_hostname(getdns_context *context,
/**
* retrieve a service assigned to a DNS name
* @see getdns_service_sync
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param extensions dict data structures, NULL to use no extensions
@ -1081,7 +1088,7 @@ getdns_service(getdns_context *context,
/**
* \addtogroup context_create getdns_context creation/destruction functions
* \addtogroup getdns_context
* @{
*/
@ -1153,7 +1160,7 @@ void getdns_context_destroy(getdns_context *context);
/**
* \addtogroup callbackfns getdns_callback functions
* \addtogroup asyncfuncs
* @{
*/
/**
@ -1169,7 +1176,7 @@ getdns_cancel_callback(getdns_context *context,
/**
* \addtogroup syncfuncs Synchronous API functions that do not use callbacks
* \addtogroup syncfuncs
* @{
*/
/** These functions do not use callbacks, when the application calls one of these
@ -1180,6 +1187,8 @@ getdns_cancel_callback(getdns_context *context,
/**
* retrieve general DNS data
* @see rrtypes
* @see getdns_general
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
@ -1196,6 +1205,7 @@ getdns_general_sync(getdns_context *context,
/**
* retrieve address assigned to a DNS name
* @see getdns_address
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param extensions dict data structures, NULL to use no extensions
@ -1210,6 +1220,7 @@ getdns_address_sync(getdns_context *context,
/**
* retrieve hostname assigned to an IP address
* @see getdns_hostname
* @param context pointer to a previously created context to be used for this call
* @param address the address to look up
* @param extensions dict data structures, NULL to use no extensions
@ -1224,6 +1235,7 @@ getdns_hostname_sync(getdns_context *context,
/**
* retrieve a service assigned to a DNS name
* @see getdns_service
* @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup
* @param extensions dict data structures, NULL to use no extensions
@ -1293,9 +1305,18 @@ char *getdns_convert_ulabel_to_alabel(const char *ulabel);
*/
char *getdns_convert_alabel_to_ulabel(const char *alabel);
/** @}
*/
/**
* \addtogroup dnssecfuncs
* @{
*/
/**
* Offline DNSSEC validate Resource Records with the help of support
* records and a DNSSEC trust anchor.
* @see dnssecvalues
* @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
@ -1333,13 +1354,13 @@ getdns_validate_dnssec(getdns_list *to_validate,
*/
getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor);
/**
* creates a string that describes the dictionary in a human readable form
* one line per item in the dictionary
* @param some_dict dictionary to pretty print
* @return character array (caller must free this) containing pretty string
/** @}
*/
/**
* \addtogroup utils
* @{
*/
char *getdns_pretty_print_dict(const getdns_dict *some_dict);
/**
* Converts a getdns_bindata representing an IPv4 or IPv6 address to a
@ -1356,7 +1377,7 @@ char *getdns_display_ip_address(const getdns_bindata
/**
* \addtogroup context_set getdns_context_set functions
* \addtogroup getdns_context
* @{
*/
@ -1365,6 +1386,7 @@ char *getdns_display_ip_address(const getdns_bindata
* Note that this implementation has an extended version of this function
* in which an additional userarg parameter can be registered:
* #getdns_context_set_update_callback .
* @see contextcodetypestext
* @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
@ -1383,6 +1405,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
* @see resolutiontypestext
* @param context The context to configure
* @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB.
* @return GETDNS_RETURN_GOOD when successful
@ -1402,6 +1425,7 @@ getdns_context_set_resolution_type(getdns_context *context,
* 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
* @see namespacetypestext
* @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.
@ -1427,8 +1451,8 @@ getdns_context_set_namespaces(getdns_context *context,
* is discouraged. Please use #getdns_context_set_dns_transport_list()
* instead of this function.
* @see getdns_context_get_dns_transport
* @see transporttypestext
* @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,
@ -1450,8 +1474,8 @@ getdns_context_set_dns_transport(getdns_context *context,
* 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 transportlisttypestext
* @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
@ -1529,6 +1553,7 @@ getdns_context_set_timeout(getdns_context *context, uint64_t timeout);
* 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
* @see redirectpoliciestext
* @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
@ -1570,6 +1595,7 @@ getdns_context_set_dns_root_servers(getdns_context *context,
* The non-standard implementation default is
* GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST.
* @see getdns_context_get_append_name
* @see suffixappendtypestext
* @param context The context to configure
* @param value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST,
* GETDNS_APPEND_NAME_ALWAYS,
@ -1787,9 +1813,6 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
getdns_dict*
getdns_context_get_api_information(getdns_context* context);
/** @}
*/
/** @}
*/

264
src/getdns/getdns_extra.h.in
View File

@ -44,16 +44,12 @@
extern "C" {
#endif
/** \defgroup UnofficialgetdnsAPI Additional API for getdns implementation
* @{
*/
/** \defgroup Uvaluesandtexts Additional values and texts
/** \addtogroup valuesandtexts Values and texts
* @{
*/
/**
* \defgroup Ureturnvaluesandtext Additional return values and texts
* \addtogroup returntypestext Return values and texts
* @{
*/
#define GETDNS_RETURN_NO_UPSTREAM_AVAILABLE ((getdns_return_t) 398 )
@ -65,7 +61,7 @@ extern "C" {
/**
* \defgroup Ucontextcodes Additional context codes and texts
* \addtogroup contextcodetypestext Context code values and texts
* @{
*/
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION 618
@ -87,7 +83,7 @@ extern "C" {
/**
* \defgroup versions Additional version values
* \defgroup versions Version values
* @{
*/
#define GETDNS_VERSION "@GETDNS_VERSION@"
@ -102,7 +98,7 @@ extern "C" {
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
/**
* \defgroup authvaulesandtext Additional authentication values and texts
* \defgroup authvaulesandtext Authentication values and texts
* @{
*/
/* Authentication options used when doing TLS */
@ -118,7 +114,7 @@ typedef enum getdns_tls_authentication_t {
/**
* \defgroup appendname Additional append name values and texts
* \addtogroup suffixappendtypestext Suffix appending values and texts
* @{
*/
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST ((getdns_append_name_t) 554 )
@ -127,11 +123,12 @@ typedef enum getdns_tls_authentication_t {
*/
/**
* \defgroup Uvaluesandtextsdepricated Additional transport values and texts (will be deprecated)
* \addtogroup transporttypestext Transport arrangements and texts
* @{
*/
/** WARNING! Do not use the constants below. They will be removed from future
/**
* WARNING! Do not use the constants below. They will be removed from future
* releases. Please use the getdns_context_set_dns_transport_list with the
* GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_TLS
* constants instead.
@ -148,12 +145,12 @@ typedef enum getdns_tls_authentication_t {
/**
* \defgroup Ufunctions Additional functions
* \addtogroup functions Functions
* @{
*/
/**
* \defgroup Ueventloops Additional event loop extension functions
* \addtogroup eventloops Event loop extension functions
* @{
*/
@ -261,7 +258,7 @@ typedef getdns_return_t (*getdns_eventloop_schedule)(getdns_eventloop *loop,
* 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
* @param[in,out] ev 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.
@ -340,8 +337,8 @@ getdns_context_set_eventloop(getdns_context* context,
* 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
* @param[in] context The context to get the eventloop from
* @param[out] eventloop The currently active event loop abstraction extension
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or evenloop were NULL
*/
@ -365,13 +362,14 @@ getdns_context_run(getdns_context *context);
/**
* \defgroup Ucontextset Additional getdns_context_set functions
* \addtogroup getdns_context
* @{
*/
/**
* Register a callback function for context changes.
* @see getdns_context_set_context_update_callback
* @see contextcodetypestext
* @param context The context to monitor for changes
* @param userarg A user defined argument that will be passed to the callback
* function.
@ -400,6 +398,7 @@ getdns_return_t getdns_context_set_return_dnssec_status(
* Configure context for oppertunistic or scrict usage profile with DNS
* over TLS.
* @see getdns_context_get_tls_authentication
* @see authvaulesandtext
* @param context The context to configure
* @param value is either GETDNS_AUTHENTICATION_REQUIRED for the strict
* usage profile or GETDNS_AUTHENTICATION_NONE for opportunistic
@ -506,15 +505,16 @@ getdns_context_unset_edns_maximum_udp_payload_size(getdns_context *context);
*/
/**
* \defgroup Ucontextget Additional getdns_context_get functions
* \addtogroup getdns_context
* @{
*/
/**
* 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
* @see resolutiontypestext
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -527,9 +527,10 @@ getdns_context_get_resolution_type(getdns_context *context,
* 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.
* @see namespacetypestext
* @param[in] context The context from which to get the setting
* @param[out] namespace_count The length of the list.
* @param[out] namespaces The returned namespaces list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
*/
@ -540,10 +541,10 @@ getdns_context_get_namespaces(getdns_context *context,
/**
* Get what transports are used for DNS lookups.
* @see getdns_context_set_dns_transport
* @see transporttypestext
* @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.
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -555,11 +556,11 @@ getdns_context_get_dns_transport(getdns_context *context,
* 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 transportlisttypestext
* @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.
* @param[in] context The context from which to get the setting
* @param[out] transport_count The length of the list.
* @param[out] transports The returned transports list.
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when any of the arguments was NULL.
*/
@ -570,8 +571,8 @@ getdns_context_get_dns_transport_list(getdns_context *context,
/**
* 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
* @param[in] context The context from which to get the setting
* @param[out] limit The current limit for oustanding queries
* @return GETDNS_RETURN_GOOD when successful
* @return GETDNS_RETURN_INVALID_PARAMETER when context or limit was NULL.
*/
@ -583,8 +584,8 @@ getdns_context_get_limit_outstanding_queries(getdns_context *context,
* 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
* @param[in] context The context from which to get the setting
* @param[out] timeout 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.
@ -597,8 +598,8 @@ getdns_context_get_timeout(getdns_context *context, uint64_t* timeout);
* 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
* @param[in] context The context from which to get the setting
* @param[out] 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 or timeout was NULL.
@ -609,8 +610,9 @@ 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
* @see redirectpoliciestext
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -624,8 +626,8 @@ getdns_context_get_follow_redirects(getdns_context *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
* @param[in] context The context from which to get the setting
* @param[out] addresses A copy of the list of dns root servers in use for
* looking up top level domains. The caller must
* destroy this list.
* @return GETDNS_RETURN_GOOD when successful
@ -640,8 +642,9 @@ getdns_context_get_dns_root_servers(getdns_context *context,
* 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,
* @see suffixappendtypestext
* @param[in] context The context from which to get the setting
* @param[out] value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST,
* GETDNS_APPEND_NAME_ALWAYS,
* GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
* GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE,
@ -659,8 +662,8 @@ getdns_context_get_append_name(getdns_context *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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -674,8 +677,8 @@ getdns_context_get_suffix(getdns_context *context, getdns_list **value);
* 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.
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -688,8 +691,8 @@ getdns_context_get_dnssec_trust_anchors(getdns_context *context,
/**
* 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
* @param[in] context The context from which to get the setting
* @param[out] 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
@ -705,8 +708,8 @@ getdns_context_get_dnssec_allowed_skew(getdns_context *context,
* 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.
* @param[in] context The context from which to get the setting
* @param[out] upstream_list 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.
@ -721,8 +724,8 @@ getdns_context_get_upstream_recursive_servers(getdns_context *context,
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -734,8 +737,8 @@ getdns_context_get_edns_maximum_udp_payload_size(getdns_context *context,
/**
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -746,8 +749,8 @@ getdns_context_get_edns_extended_rcode(getdns_context *context,
/**
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -757,8 +760,8 @@ 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,
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -771,8 +774,8 @@ getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value);
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -782,8 +785,8 @@ getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t*
/**
* 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,
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -794,8 +797,9 @@ getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t
/**
* 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
* @see authvaulesandtext
* @param[in] context The context from which to get the setting
* @param[out] value is either GETDNS_AUTHENTICATION_REQUIRED if
* authentication is required, or GETDNS_AUTHENTICATION_NONE
* if authentication is optional. When credentials are
* available, the API will still try to authenticate the
@ -813,8 +817,8 @@ getdns_context_get_tls_authentication(getdns_context *context,
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
*/
@ -826,8 +830,8 @@ getdns_context_get_round_robin_upstreams(getdns_context *context,
* 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,
* @param[in] context The context from which to get the setting
* @param[out] value Number of seconds before an attempt to setup DNS over TLS,
* with an upstream for which setting up an TLS connection has
* never been successful before, will be retried.
* @return GETDNS_RETURN_GOOD when successful
@ -842,8 +846,8 @@ getdns_context_get_tls_backoff_time(getdns_context *context,
* 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
* @param[in] context The context from which to get the setting
* @param[out] value 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.
@ -855,9 +859,10 @@ getdns_context_get_tls_connection_retries(getdns_context *context,
/**
* Get the currently registered callback function and user defined argument
* for context changes.
* Combined with getdns_context_set_update_callback this can be used to
* Combined with #getdns_context_set_update_callback this can be used to
* "chain" context update callbacks and in this way create a subscription
* service catering multiple interested parties.
* @see contextcodetypestext
* @param context The context to monitor for changes
* @param userarg A user defined argument to be passed to the callback
* function.
@ -874,18 +879,20 @@ getdns_context_get_update_callback(getdns_context *context, void **userarg,
/**
* \defgroup Uutilityfunctions Additional utility functions
* \addtogroup versionfuncs Version functions
* @{
*/
/**
* Get the version number of this implementation.
* @see versions
* @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.
* @see versions
* @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.
@ -896,6 +903,7 @@ uint32_t getdns_get_version_number(void);
/**
* Get the version of the getdns API specification this library implements
* as a string.
* @see versions
* @return The API specification version as string. For example "@API_VERSION@"
*/
const char *getdns_get_api_version(void);
@ -903,6 +911,7 @@ const char *getdns_get_api_version(void);
/**
* Get the version of the getdns API specification this library implements
* as a number.
* @see versions
* @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.
@ -910,6 +919,14 @@ const char *getdns_get_api_version(void);
uint32_t getdns_get_api_version_number(void);
/** @}
*/
/**
* \addtogroup utils Utility functions
* @{
*/
/**
* Returns a text describing the getdns error code, or NULL when the error
* code is unkown.
@ -919,6 +936,15 @@ uint32_t getdns_get_api_version_number(void);
*/
const char *getdns_get_errorstr_by_id(uint16_t err);
/** @}
*/
/**
* \addtogroup getdns_dict
* @{
*/
/**
* 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
@ -949,9 +975,19 @@ getdns_dict_util_set_string(getdns_dict *dict, char *name, const char *value);
getdns_return_t
getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result);
/** @}
*/
/**
* \addtogroup dnssecfuncs
* @{
*/
/**
* Validate replies or resource records.
*
* @see dnssecvalues
* @param to_validate A list of RR-dicts with companion RRSIG-RR-dicts
* which will be validated. Or a list of reply-dicts
* that will be validated. The "replies_tree" list
@ -983,6 +1019,16 @@ getdns_validate_dnssec2(getdns_list *to_validate,
getdns_list *trust_anchors,
time_t validation_time, uint32_t skew);
/** @}
*/
/**
* \addtogroup utils
* @{
*/
/**
* Public Key Pinning functionality:
*
@ -1035,6 +1081,15 @@ getdns_return_t getdns_pubkey_pinset_sanity_check(
const getdns_list* pinset,
getdns_list* errorlist);
/** @}
*/
/**
* \addtogroup getdns_context
* @{
*/
/**
* Configure a context with settings given in a getdns_dict.
*
@ -1077,7 +1132,7 @@ getdns_context_config(getdns_context *context, const getdns_dict *config_dict);
*/
/**
* \defgroup UXTRAPrettyPrinting Pretty printing of getdns dicts and lists
* \addtogroup getdns_dict
* @{
*/
@ -1094,27 +1149,6 @@ getdns_context_config(getdns_context *context, const getdns_dict *config_dict);
int
getdns_pretty_snprint_dict(char *str, size_t size, const getdns_dict *dict);
/**
* creates a string that describes the list in a human readable form.
* @param some_list list to pretty print
* @return character array (caller must free this) containing pretty string
*/
char *
getdns_pretty_print_list(const getdns_list *some_list);
/**
* Pretty print the getdns_list in a given buffer snprintf style.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param list getdns_list to print
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_pretty_snprint_list(char *str, size_t size, const getdns_list *list);
/**
* creates a string containing a json representation of some_dict.
* bindatas are converted to strings when possible, including bindatas for
@ -1145,6 +1179,35 @@ int
getdns_snprint_json_dict(
char *str, size_t size, const getdns_dict *dict, int pretty);
/** @}
*/
/**
* \addtogroup getdns_list
* @{
*/
/**
* creates a string that describes the list in a human readable form.
* @param some_list list to pretty print
* @return character array (caller must free this) containing pretty string
*/
char *
getdns_pretty_print_list(const getdns_list *some_list);
/**
* Pretty print the getdns_list in a given buffer snprintf style.
* @param str pointer to the buffer to print to
* @param size size of the given buffer. No more than size bytes (including
* the terminating null byte) will be written to str.
* @param list getdns_list to print
* @return The number of characters written excluding the terminating null byte
* or the number of characters which would have been written if enough space
* had been available.
*/
int
getdns_pretty_snprint_list(char *str, size_t size, const getdns_list *list);
/**
* creates a string containing a json representation of some_list.
* bindatas are converted to strings when possible, including bindatas for
@ -1180,7 +1243,7 @@ getdns_snprint_json_list(
*/
/**
* \defgroup UDNSDataConversionFunctions Functions for converting between getdns DNS dicts, DNS wire format and DNS presentation format
* \defgroup UDNSDataConversionFunctions Converting between getdns DNS dicts, DNS wire format and DNS presentation format
* @{
*/
@ -1501,7 +1564,7 @@ getdns_msg_dict2str_scan(
*/
/**
* \defgroup Ustring2getdns_data Functions for converting strings to getdns data structures
* \defgroup Ustring2getdns_data Converting strings to getdns data structures
* @{
*/
@ -1598,7 +1661,7 @@ getdns_str2int(const char *str, uint32_t *value);
*/
/**
* \defgroup UServerFunctions Functions for creating simple DNS servers
* \defgroup UServerFunctions Creating simple DNS servers
* @{
*/
@ -1671,7 +1734,7 @@ getdns_reply(getdns_context *context,
/**
* \defgroup Uutilityfunctionsdeprecated Additional utility functions (will be deprecated)
* \defgroup Uutilityfunctionsdeprecated Deptricated utility functions
* @{
*/
/**
@ -1728,9 +1791,6 @@ getdns_return_t getdns_context_set_use_threads(getdns_context* context,
*/
/** @}
*/
/** @}
*/
#ifdef __cplusplus
}
#endif