From d3309e89e811396ce450489d9eefabccd4d0d8f8 Mon Sep 17 00:00:00 2001 From: Sara Dickinson Date: Fri, 17 Jun 2016 16:53:51 +0100 Subject: [PATCH 1/2] Initial pass at updating Doxygen modules for getdns.h. Also add info on using context_create multithreaded. - this is a rough first pass at making the oxygen Modules page more consistent and user navigable as a handy index into getdns - I think a further re-org is needed in a later update, also haven't touched getdns_extra.h yet - Added a few functions descriptions too, but still many functions without comments... a WIP - Updated man page for context_create with multi-threaded instructions as a short term fix --- doc/getdns_context.3.in | 10 + src/getdns/getdns.h.in | 470 +++++++++++++++++++++++++++-------- src/getdns/getdns_extra.h.in | 2 +- src/types-internal.h | 7 +- 4 files changed, 374 insertions(+), 115 deletions(-) diff --git a/doc/getdns_context.3.in b/doc/getdns_context.3.in index b2c6894f..71ed4b15 100644 --- a/doc/getdns_context.3.in +++ b/doc/getdns_context.3.in @@ -134,6 +134,16 @@ will be called with a callback_type of GETDNS_CALLBACK_CANCEL. getdns_context_destroy() returns after all of the needed cleanup is done and callbacks are made. +.LP +If you are using getdns in a multi-threaded manner, you are then of course using +the underlying OpenSSL library multi-threaded and the version of that library +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). +Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function. + .HP 3 .I context Used to return the pointer to an opaque structure. The caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function. The result is a newly allocated and initialized context (if there are no errors). In the getdns_destroy_context function this is the context whose associated memory will be released. diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index 65e0b2ee..fc19e2ad 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -46,7 +46,10 @@ extern "C" { #define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@" -/* Return values */ +/** + * \defgroup returntypes Return types + * @{ + */ typedef enum getdns_return_t { GETDNS_RETURN_GOOD = 0, GETDNS_RETURN_GENERIC_ERROR = 1, @@ -64,9 +67,11 @@ typedef enum getdns_return_t { GETDNS_RETURN_INVALID_PARAMETER = 311, GETDNS_RETURN_NOT_IMPLEMENTED = 312 } getdns_return_t; +/** @} + */ /** - * \defgroup Return values texts + * \defgroup returntypestext Return value texts * @{ */ #define GETDNS_RETURN_GOOD_TEXT "Good" @@ -93,20 +98,30 @@ typedef enum getdns_return_t { * @{ */ #define GETDNS_DNSSEC_SECURE 400 -#define GETDNS_DNSSEC_SECURE_TEXT "The record was determined to be secure in DNSSEC" #define GETDNS_DNSSEC_BOGUS 401 -#define GETDNS_DNSSEC_BOGUS_TEXT "The record was determined to be bogus in DNSSEC" #define GETDNS_DNSSEC_INDETERMINATE 402 -#define GETDNS_DNSSEC_INDETERMINATE_TEXT "The record was not determined to be any state in DNSSEC" #define GETDNS_DNSSEC_INSECURE 403 -#define GETDNS_DNSSEC_INSECURE_TEXT "The record was determined to be insecure in DNSSEC" #define GETDNS_DNSSEC_NOT_PERFORMED 404 +/** @} + */ + +/** + * \defgroup dnssecvaluestext DNSSEC value texts + * @{ + */ +#define GETDNS_DNSSEC_SECURE_TEXT "The record was determined to be secure in DNSSEC" +#define GETDNS_DNSSEC_BOGUS_TEXT "The record was determined to be bogus in DNSSEC" +#define GETDNS_DNSSEC_INDETERMINATE_TEXT "The record was not determined to be any state in DNSSEC" +#define GETDNS_DNSSEC_INSECURE_TEXT "The record was determined to be insecure in DNSSEC" #define GETDNS_DNSSEC_NOT_PERFORMED_TEXT "DNSSEC validation was not performed (only used for debugging)" /** @} */ -/* Namespace types */ +/** + * \defgroup namespacetypes Namespace types + * @{ + */ typedef enum getdns_namespace_t { GETDNS_NAMESPACE_DNS = 500, GETDNS_NAMESPACE_LOCALNAMES = 501, @@ -114,9 +129,11 @@ typedef enum getdns_namespace_t { GETDNS_NAMESPACE_MDNS = 503, GETDNS_NAMESPACE_NIS = 504 } getdns_namespace_t; +/** @} + */ /** - * \defgroup Namespace types texts + * \defgroup namespacetypestext Namespace type texts * @{ */ #define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()" @@ -128,14 +145,19 @@ typedef enum getdns_namespace_t { */ -/* Resolution types */ +/** + * \defgroup resolutiontypes Resolution types + * @{ + */ typedef enum getdns_resolution_t { GETDNS_RESOLUTION_STUB = 520, GETDNS_RESOLUTION_RECURSING = 521 } getdns_resolution_t; +/** @} + */ /** - * \defgroup Resolution types texts + * \defgroup resolutiontypestext Resolution types texts * @{ */ #define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()" @@ -144,14 +166,19 @@ typedef enum getdns_resolution_t { */ -/* Redirect policies */ +/** + * \defgroup redirectpolicytype Redirect policy types + * @{ + */ typedef enum getdns_redirects_t { GETDNS_REDIRECTS_FOLLOW = 530, GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531 } getdns_redirects_t; +/** @} + */ /** - * \defgroup Redirect policies texts + * \defgroup redirectpoliciestext Redirect policy type texts * @{ */ #define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" @@ -160,16 +187,21 @@ typedef enum getdns_redirects_t { */ -/* Transport arrangements */ +/** + * \defgroup transporttypes Transport arrangements types + * @{ + */ typedef enum getdns_transport_t { GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP = 540, GETDNS_TRANSPORT_UDP_ONLY = 541, GETDNS_TRANSPORT_TCP_ONLY = 542, GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543 } getdns_transport_t; +/** @} +*/ /** - * \defgroup Transport arrangements texts + * \defgroup transporttypestext Transport arrangement type texts * @{ */ #define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()" @@ -180,15 +212,21 @@ typedef enum getdns_transport_t { */ +/** + * \defgroup transportlisttypes Transport list types + * @{ + */ /* Base transports for use in transport list */ typedef enum getdns_transport_list_t { GETDNS_TRANSPORT_UDP = 1200, GETDNS_TRANSPORT_TCP = 1201, GETDNS_TRANSPORT_TLS = 1202, } getdns_transport_list_t; +/** @} + */ /** - * \defgroup Base transport texts + * \defgroup transportlisttypestext Transport list types texts * @{ */ #define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()" @@ -198,16 +236,21 @@ typedef enum getdns_transport_list_t { */ -/* Suffix appending methods */ +/** + * \defgroup suffixappendtypes Suffix appending types + * @{ + */ typedef enum getdns_append_name_t { GETDNS_APPEND_NAME_ALWAYS = 550, GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE = 551, GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552, GETDNS_APPEND_NAME_NEVER = 553 } getdns_append_name_t; +/** @} + */ /** - * \defgroup Suffix appending methods texts + * \defgroup suffixappendtypestext Suffix appending type texts * @{ */ #define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()" @@ -218,6 +261,10 @@ typedef enum getdns_append_name_t { */ + /** + * \defgroup contextcodetypes Context code types + * @{ + */ /* Context codes */ typedef enum getdns_context_code_t { GETDNS_CONTEXT_CODE_NAMESPACES = 600, @@ -239,9 +286,11 @@ typedef enum getdns_context_code_t { GETDNS_CONTEXT_CODE_TIMEOUT = 616, GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617 } getdns_context_code_t; +/** @} + */ /** - * \defgroup Context codes texts + * \defgroup contextcodetypestext Context code type texts * @{ */ #define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces" @@ -266,16 +315,21 @@ typedef enum getdns_context_code_t { */ -/* Callback Type Variables */ +/** + * \defgroup callbacktype Callback types + * @{ + */ typedef enum getdns_callback_type_t { GETDNS_CALLBACK_COMPLETE = 700, GETDNS_CALLBACK_CANCEL = 701, GETDNS_CALLBACK_TIMEOUT = 702, GETDNS_CALLBACK_ERROR = 703 } getdns_callback_type_t; +/** @} + */ /** - * \defgroup Callback type variables texts + * \defgroup callbacktypetext Callback type texts * @{ */ #define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it" @@ -285,54 +339,86 @@ typedef enum getdns_callback_type_t { /** @} */ + /** * \defgroup nametype Types of name services * @{ */ #define GETDNS_NAMETYPE_DNS 800 -#define GETDNS_NAMETYPE_DNS_TEXT "Normal DNS (RFC 1035)" #define GETDNS_NAMETYPE_WINS 801 +/** @} + */ + +/** + * \defgroup nametypetext Types of name service text + * @{ + */ +#define GETDNS_NAMETYPE_DNS_TEXT "Normal DNS (RFC 1035)" #define GETDNS_NAMETYPE_WINS_TEXT "The WINS name service (some reference needed)" /** @} */ + /** - * \defgroup respstatus Status Codes for Responses + * \defgroup respstatus Status Codes for responses * @{ */ #define GETDNS_RESPSTATUS_GOOD 900 -#define GETDNS_RESPSTATUS_GOOD_TEXT "At least one response was returned" #define GETDNS_RESPSTATUS_NO_NAME 901 -#define GETDNS_RESPSTATUS_NO_NAME_TEXT "Queries for the name yielded all negative responses" #define GETDNS_RESPSTATUS_ALL_TIMEOUT 902 -#define GETDNS_RESPSTATUS_ALL_TIMEOUT_TEXT "All queries for the name timed out" #define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS 903 -#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC." #define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS 904 +/** @} + */ + +/** + * \defgroup respstatustext Status Codes for responses texts + * @{ + */ +#define GETDNS_RESPSTATUS_GOOD_TEXT "At least one response was returned" +#define GETDNS_RESPSTATUS_NO_NAME_TEXT "Queries for the name yielded all negative responses" +#define GETDNS_RESPSTATUS_ALL_TIMEOUT_TEXT "All queries for the name timed out" +#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC." #define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but all received responses for the requested name were bogus." /** @} */ + /** - * \defgroup extvals Values Associated With Extensions + * \defgroup extvals Values associated with extensions * @{ */ #define GETDNS_EXTENSION_TRUE 1000 -#define GETDNS_EXTENSION_TRUE_TEXT "Turn on the extension" #define GETDNS_EXTENSION_FALSE 1001 -#define GETDNS_EXTENSION_FALSE_TEXT "Do not turn on the extension" /** @} */ /** - * \defgroup dnserrors Values Associated With DNS Errors Found By The API + * \defgroup extvalstext Values associated with extensions text + * @{ + */ +#define GETDNS_EXTENSION_TRUE_TEXT "Turn on the extension" +#define GETDNS_EXTENSION_FALSE_TEXT "Do not turn on the extension" +/** @} + */ + + +/** + * \defgroup dnserrors Values associated with DNS errors found by the API * @{ */ #define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100 -#define GETDNS_BAD_DNS_CNAME_IN_TARGET_TEXT "A DNS query type that does not allow a target to be a CNAME pointed to a CNAME" #define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL 1101 -#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL_TEXT "One or more labels in a returned domain name is all-numeric; this is not legal for a hostname" #define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE 1102 +/** @} + */ + +/** + * \defgroup dnserrorstext Values associated with DNS errors found by the API text + * @{ + */ +#define GETDNS_BAD_DNS_CNAME_IN_TARGET_TEXT "A DNS query type that does not allow a target to be a CNAME pointed to a CNAME" +#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL_TEXT "One or more labels in a returned domain name is all-numeric; this is not legal for a hostname" #define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE_TEXT "A DNS query for a type other than CNAME returned a CNAME response" /** @} */ @@ -427,7 +513,7 @@ typedef enum getdns_callback_type_t { */ /** - * \defgroup rrclasses RR classes + * \defgroup rrclasses RR Classes * @{ */ #define GETDNS_RRCLASS_IN 1 @@ -479,6 +565,8 @@ typedef enum getdns_callback_type_t { typedef struct getdns_context getdns_context; typedef uint64_t getdns_transaction_t; + + /** * used to check data types within complex types (dict, list) */ @@ -505,6 +593,81 @@ typedef struct getdns_dict getdns_dict; */ typedef struct getdns_list getdns_list; + +/** + * \defgroup list_create getdns_list creation/destruction functions + * @{ + */ + +/** + * create a new list with no items + * @return pointer to an allocated list, NULL if insufficient memory + */ +getdns_list *getdns_list_create(); +getdns_list *getdns_list_create_with_context(getdns_context *context); +getdns_list *getdns_list_create_with_memory_functions( + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); +getdns_list *getdns_list_create_with_extended_memory_functions( + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + + +/** + * free memory allocated to the list (also frees all children of the list) + * note that lists and bindata retrieved from the list via the getdns_list_get_* + * helper functions will be destroyed as well - if you fetched them previously + * you MUST copy those instances BEFORE you destroy the list else + * unpleasant things will happen at run-time + */ +void getdns_list_destroy(getdns_list *list); +/** @} + */ + + +/** + * \defgroup dict_create getdns_dict creation/destruction functions + * @{ + */ + +/** + * create a new dictionary with no items + * @return pointer to an allocated dictionary, NULL if insufficient memory + */ +getdns_dict *getdns_dict_create(); +getdns_dict *getdns_dict_create_with_context(getdns_context *context); +getdns_dict *getdns_dict_create_with_memory_functions( + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); +getdns_dict *getdns_dict_create_with_extended_memory_functions( + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + +/** + * destroy a dictionary and all items within that dictionary + * be aware that if you have fetched any data from the dictionary it will + * no longer be available (you are likely to experience bad things if you try) + */ +void getdns_dict_destroy(getdns_dict *dict); +/** @} + */ + + +/** + * \defgroup getdns_list_get_functions getdns_list_get functions + * @{ + */ + /** * get the length of the specified list (returned in *answer) * @param list list of any of the supported data types @@ -575,6 +738,14 @@ getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index, */ getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, uint32_t * answer); +/** @} + */ + + +/** + * \defgroup getdns_dict_get_functions getdns_dict_get functions + * @{ + */ /** * fetch a list of names from the dictionary, this list must be freed by the caller @@ -641,33 +812,14 @@ getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, */ getdns_return_t getdns_dict_get_int(const getdns_dict *dict, const char *name, uint32_t * answer); +/** @} + */ + /** - * create a new list with no items - * @return pointer to an allocated list, NULL if insufficient memory + * \defgroup getdns_list_set getdns_list_set functions + * @{ */ -getdns_list *getdns_list_create(); -getdns_list *getdns_list_create_with_context(getdns_context *context); -getdns_list *getdns_list_create_with_memory_functions( - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); -getdns_list *getdns_list_create_with_extended_memory_functions( - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - -/** - * free memory allocated to the list (also frees all children of the list) - * note that lists and bindata retrieved from the list via the getdns_list_get_* - * helper functions will be destroyed as well - if you fetched them previously - * you MUST copy those instances BEFORE you destroy the list else - * unpleasant things will happen at run-time - */ -void getdns_list_destroy(getdns_list *list); /** * assign the child_dict to an item in a parent list, the parent list copies @@ -710,31 +862,14 @@ getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index, */ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, uint32_t child_uint32); +/** @} + */ + /** - * create a new dictionary with no items - * @return pointer to an allocated dictionary, NULL if insufficient memory + * \defgroup getdns_dict_set getdns_dict_set functions + * @{ */ -getdns_dict *getdns_dict_create(); -getdns_dict *getdns_dict_create_with_context(getdns_context *context); -getdns_dict *getdns_dict_create_with_memory_functions( - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); -getdns_dict *getdns_dict_create_with_extended_memory_functions( - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - -/** - * destroy a dictionary and all items within that dictionary - * be aware that if you have fetched any data from the dictionary it will - * no longer be available (you are likely to experience bad things if you try) - */ -void getdns_dict_destroy(getdns_dict *dict); getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); @@ -767,6 +902,9 @@ 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); +/** @} + */ + /** * remove the value associated with the specified name @@ -777,14 +915,41 @@ 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); + +/** + * \defgroup callbacks getdns_callback functions + * @{ + */ + /* Callback arguments */ typedef void (*getdns_callback_t) (getdns_context *context, getdns_callback_type_t callback_type, getdns_dict * response, void *userarg, getdns_transaction_t transaction_id); -/* Function definitions */ +getdns_return_t +getdns_cancel_callback(getdns_context *context, + getdns_transaction_t transaction_id); +/** @} + */ + +/** + * \defgroup funcs Asynchronous API functions + * @{ + */ + +/** + * retrieve general DNS data + * @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 + * @param extensions dict data structures, NULL to use no extensions + * @param userarg void* returned to the callback untouched + * @param[out] transaction_id id used to identify the callback, NULL is ignored + * @param callbackfn callback function defined by the application + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_general(getdns_context *context, const char *name, @@ -792,52 +957,63 @@ getdns_general(getdns_context *context, getdns_dict *extensions, void *userarg, getdns_transaction_t * transaction_id, getdns_callback_t callbackfn); + +/** + * retrieve address assigned to a DNS name + * @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 + * @param extensions dict data structures, NULL to use no extensions + * @param userarg void* returned to the callback untouched + * @param[out] transaction_id id used to identify the callback, NULL is ignored + * @param callbackfn callback function defined by the application + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_address(getdns_context *context, const char *name, getdns_dict *extensions, void *userarg, getdns_transaction_t * transaction_id, getdns_callback_t callbackfn); + +/** + * retrieve hostname assigned to an IP address + * @param context pointer to a previously created context to be used for this call + * @param address the address to look up + * @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS + * @param extensions dict data structures, NULL to use no extensions + * @param userarg void* returned to the callback untouched + * @param[out] transaction_id id used to identify the callback, NULL is ignored + * @param callbackfn callback function defined by the application + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_hostname(getdns_context *context, getdns_dict *address, getdns_dict *extensions, void *userarg, getdns_transaction_t * transaction_id, getdns_callback_t callbackfn); + +/** + * retrieve a service assigned to a DNS name + * @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 + * @param extensions dict data structures, NULL to use no extensions + * @param userarg void* returned to the callback untouched + * @param[out] transaction_id id used to identify the callback, NULL is ignored + * @param callbackfn callback function defined by the application + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_service(getdns_context *context, const char *name, getdns_dict *extensions, void *userarg, getdns_transaction_t * transaction_id, getdns_callback_t callbackfn); +/** @} + */ -getdns_return_t -getdns_context_create(getdns_context ** context, int set_from_os); - -getdns_return_t -getdns_context_create_with_memory_functions( - getdns_context ** context, - int set_from_os, - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); - -getdns_return_t -getdns_context_create_with_extended_memory_functions( - getdns_context **context, - int set_from_os, - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - -void getdns_context_destroy(getdns_context *context); - -getdns_return_t -getdns_cancel_callback(getdns_context *context, - getdns_transaction_t transaction_id); /** * \defgroup syncfuns Synchronous API functions that do not use callbacks @@ -871,7 +1047,6 @@ getdns_general_sync(getdns_context *context, * @param extensions dict data structures, NULL to use no extensions * @param response response * @return GETDNS_RETURN_GOOD on success - */ getdns_return_t getdns_address_sync(getdns_context *context, @@ -910,6 +1085,11 @@ getdns_service_sync(getdns_context *context, /** @} */ +/** + * \defgroup utils Utility functions + * @{ + */ + getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, @@ -943,6 +1123,78 @@ char *getdns_pretty_print_dict(const getdns_dict *some_dict); char *getdns_display_ip_address(const getdns_bindata *bindata_of_ipv4_or_ipv6_address); +/** @} + */ + + +/** + * \defgroup context_create getdns_context creation/destruction functions + * @{ + */ + +/** + * creates a new getdns context with default settings. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @return GETDNS_RETURN_GOOD on success + */ +getdns_return_t +getdns_context_create(getdns_context ** context, int set_from_os); + + +/** + * creates a new getdns context with default settings using custom memory functions. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @param malloc custom malloc function + * @param realloc custom realloc function + * @param malloc custom free function + * @return GETDNS_RETURN_GOOD on success + */ +getdns_return_t +getdns_context_create_with_memory_functions( + getdns_context ** context, + int set_from_os, + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); + + +/** + * creates a new getdns context with default settings using extended custom memory functions. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @param malloc custom malloc function + * @param realloc custom realloc function + * @param malloc custom free function + * @return GETDNS_RETURN_GOOD on success + */ +getdns_return_t +getdns_context_create_with_extended_memory_functions( + getdns_context **context, + int set_from_os, + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + +void getdns_context_destroy(getdns_context *context); +/** @} + */ + + +/** + * \defgroup context_set getdns_context_set functions + * @{ + */ getdns_return_t getdns_context_set_context_update_callback( getdns_context *context, @@ -1031,6 +1283,8 @@ getdns_context_set_extended_memory_functions(getdns_context *context, void *(*realloc) (void *userarg, void *ptr, size_t sz), void (*free) (void *userarg, void *ptr) ); +/** @} + */ /* api information support */ getdns_dict* diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index dd0574c7..e9f1b331 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -426,7 +426,7 @@ typedef enum getdns_tls_authentication_t { #define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED /** - * \defgroup Base authentication texts + * \defgroup authtext Authentication texts * @{ */ #define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()" diff --git a/src/types-internal.h b/src/types-internal.h index 6f7d99ea..bf7bfd7e 100644 --- a/src/types-internal.h +++ b/src/types-internal.h @@ -62,10 +62,7 @@ struct getdns_context; struct getdns_upstreams; struct getdns_upstream; -/** - * \defgroup strings String Constants - * @{ - */ +/* String constants for internal use */ #define GETDNS_STR_IPV4 "IPv4" #define GETDNS_STR_IPV6 "IPv6" #define GETDNS_STR_ADDRESS_TYPE "address_type" @@ -119,8 +116,6 @@ struct getdns_upstream; #define GETDNS_TRANSPORTS_MAX 3 #define GETDNS_UPSTREAM_TRANSPORTS 2 -/** @} - */ /* declarations */ struct getdns_dns_req; From 75b0fef7414b3ebdfb4b505fd4a3aa3e7ed82224 Mon Sep 17 00:00:00 2001 From: Sara Dickinson Date: Sat, 25 Jun 2016 17:49:29 +0100 Subject: [PATCH 2/2] Update some type/value names and revert to original order of declarations with manual ordering within the page --- src/getdns/getdns.h.in | 417 ++++++++++++++++++++--------------------- 1 file changed, 203 insertions(+), 214 deletions(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index fc19e2ad..899b26ff 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -33,6 +33,7 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ + #ifndef GETDNS_H #define GETDNS_H @@ -47,7 +48,7 @@ extern "C" { #define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@" /** - * \defgroup returntypes Return types + * \defgroup returntypes Return values * @{ */ typedef enum getdns_return_t { @@ -71,7 +72,7 @@ typedef enum getdns_return_t { */ /** - * \defgroup returntypestext Return value texts + * \defgroup returntypestext Return values texts * @{ */ #define GETDNS_RETURN_GOOD_TEXT "Good" @@ -94,25 +95,18 @@ typedef enum getdns_return_t { /** - * \defgroup dnssecvalues DNSSEC values + * \defgroup dnssecvalues DNSSEC values and texts * @{ */ #define GETDNS_DNSSEC_SECURE 400 -#define GETDNS_DNSSEC_BOGUS 401 -#define GETDNS_DNSSEC_INDETERMINATE 402 -#define GETDNS_DNSSEC_INSECURE 403 -#define GETDNS_DNSSEC_NOT_PERFORMED 404 -/** @} - */ - -/** - * \defgroup dnssecvaluestext DNSSEC value texts - * @{ - */ #define GETDNS_DNSSEC_SECURE_TEXT "The record was determined to be secure in DNSSEC" +#define GETDNS_DNSSEC_BOGUS 401 #define GETDNS_DNSSEC_BOGUS_TEXT "The record was determined to be bogus in DNSSEC" +#define GETDNS_DNSSEC_INDETERMINATE 402 #define GETDNS_DNSSEC_INDETERMINATE_TEXT "The record was not determined to be any state in DNSSEC" +#define GETDNS_DNSSEC_INSECURE 403 #define GETDNS_DNSSEC_INSECURE_TEXT "The record was determined to be insecure in DNSSEC" +#define GETDNS_DNSSEC_NOT_PERFORMED 404 #define GETDNS_DNSSEC_NOT_PERFORMED_TEXT "DNSSEC validation was not performed (only used for debugging)" /** @} */ @@ -133,7 +127,7 @@ typedef enum getdns_namespace_t { */ /** - * \defgroup namespacetypestext Namespace type texts + * \defgroup namespacetypestext Namespace types texts * @{ */ #define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()" @@ -167,7 +161,7 @@ typedef enum getdns_resolution_t { /** - * \defgroup redirectpolicytype Redirect policy types + * \defgroup redirectpolicytype Redirect policies * @{ */ typedef enum getdns_redirects_t { @@ -178,7 +172,7 @@ typedef enum getdns_redirects_t { */ /** - * \defgroup redirectpoliciestext Redirect policy type texts + * \defgroup redirectpoliciestext Redirect policies texts * @{ */ #define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" @@ -188,7 +182,7 @@ typedef enum getdns_redirects_t { /** - * \defgroup transporttypes Transport arrangements types + * \defgroup transporttypes Transport arrangements * @{ */ typedef enum getdns_transport_t { @@ -201,7 +195,7 @@ typedef enum getdns_transport_t { */ /** - * \defgroup transporttypestext Transport arrangement type texts + * \defgroup transporttypestext Transport arrangements texts * @{ */ #define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()" @@ -213,7 +207,7 @@ typedef enum getdns_transport_t { /** - * \defgroup transportlisttypes Transport list types + * \defgroup transportlisttypes Transport list values * @{ */ /* Base transports for use in transport list */ @@ -226,7 +220,7 @@ typedef enum getdns_transport_list_t { */ /** - * \defgroup transportlisttypestext Transport list types texts + * \defgroup transportlisttypestext Transport list values texts * @{ */ #define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()" @@ -237,7 +231,7 @@ typedef enum getdns_transport_list_t { /** - * \defgroup suffixappendtypes Suffix appending types + * \defgroup suffixappendtypes Suffix appending values * @{ */ typedef enum getdns_append_name_t { @@ -250,7 +244,7 @@ typedef enum getdns_append_name_t { */ /** - * \defgroup suffixappendtypestext Suffix appending type texts + * \defgroup suffixappendtypestext Suffix appending values texts * @{ */ #define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()" @@ -261,10 +255,10 @@ typedef enum getdns_append_name_t { */ - /** - * \defgroup contextcodetypes Context code types - * @{ - */ +/** +* \defgroup contextcodetypes Context code values +* @{ +*/ /* Context codes */ typedef enum getdns_context_code_t { GETDNS_CONTEXT_CODE_NAMESPACES = 600, @@ -290,7 +284,7 @@ typedef enum getdns_context_code_t { */ /** - * \defgroup contextcodetypestext Context code type texts + * \defgroup contextcodetypestext Context code values texts * @{ */ #define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces" @@ -329,7 +323,7 @@ typedef enum getdns_callback_type_t { */ /** - * \defgroup callbacktypetext Callback type texts + * \defgroup callbacktypetext Callback types texts * @{ */ #define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it" @@ -341,84 +335,54 @@ typedef enum getdns_callback_type_t { /** - * \defgroup nametype Types of name services + * \defgroup nametype Types of name services and texts * @{ */ #define GETDNS_NAMETYPE_DNS 800 -#define GETDNS_NAMETYPE_WINS 801 -/** @} - */ - -/** - * \defgroup nametypetext Types of name service text - * @{ - */ #define GETDNS_NAMETYPE_DNS_TEXT "Normal DNS (RFC 1035)" +#define GETDNS_NAMETYPE_WINS 801 #define GETDNS_NAMETYPE_WINS_TEXT "The WINS name service (some reference needed)" /** @} */ /** - * \defgroup respstatus Status Codes for responses + * \defgroup respstatus Status Codes for responses and text * @{ */ #define GETDNS_RESPSTATUS_GOOD 900 -#define GETDNS_RESPSTATUS_NO_NAME 901 -#define GETDNS_RESPSTATUS_ALL_TIMEOUT 902 -#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS 903 -#define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS 904 -/** @} - */ - -/** - * \defgroup respstatustext Status Codes for responses texts - * @{ - */ #define GETDNS_RESPSTATUS_GOOD_TEXT "At least one response was returned" +#define GETDNS_RESPSTATUS_NO_NAME 901 #define GETDNS_RESPSTATUS_NO_NAME_TEXT "Queries for the name yielded all negative responses" +#define GETDNS_RESPSTATUS_ALL_TIMEOUT 902 #define GETDNS_RESPSTATUS_ALL_TIMEOUT_TEXT "All queries for the name timed out" +#define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS 903 #define GETDNS_RESPSTATUS_NO_SECURE_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC." +#define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS 904 #define GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS_TEXT "The context setting for getting only secure responses was specified, and at least one DNS response was received, but all received responses for the requested name were bogus." /** @} */ - /** * \defgroup extvals Values associated with extensions * @{ */ #define GETDNS_EXTENSION_TRUE 1000 -#define GETDNS_EXTENSION_FALSE 1001 -/** @} - */ - -/** - * \defgroup extvalstext Values associated with extensions text - * @{ - */ #define GETDNS_EXTENSION_TRUE_TEXT "Turn on the extension" +#define GETDNS_EXTENSION_FALSE 1001 #define GETDNS_EXTENSION_FALSE_TEXT "Do not turn on the extension" /** @} */ - /** - * \defgroup dnserrors Values associated with DNS errors found by the API + * \defgroup dnserrors Values associated with DNS errors found by the API and text * @{ */ #define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100 -#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL 1101 -#define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE 1102 -/** @} - */ - -/** - * \defgroup dnserrorstext Values associated with DNS errors found by the API text - * @{ - */ #define GETDNS_BAD_DNS_CNAME_IN_TARGET_TEXT "A DNS query type that does not allow a target to be a CNAME pointed to a CNAME" +#define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL 1101 #define GETDNS_BAD_DNS_ALL_NUMERIC_LABEL_TEXT "One or more labels in a returned domain name is all-numeric; this is not legal for a hostname" +#define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE 1102 #define GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE_TEXT "A DNS query for a type other than CNAME returned a CNAME response" /** @} */ @@ -593,78 +557,27 @@ typedef struct getdns_dict getdns_dict; */ typedef struct getdns_list getdns_list; +/* 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 - * @{ - */ - -/** - * create a new list with no items - * @return pointer to an allocated list, NULL if insufficient memory - */ -getdns_list *getdns_list_create(); -getdns_list *getdns_list_create_with_context(getdns_context *context); -getdns_list *getdns_list_create_with_memory_functions( - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); -getdns_list *getdns_list_create_with_extended_memory_functions( - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - - -/** - * free memory allocated to the list (also frees all children of the list) - * note that lists and bindata retrieved from the list via the getdns_list_get_* - * helper functions will be destroyed as well - if you fetched them previously - * you MUST copy those instances BEFORE you destroy the list else - * unpleasant things will happen at run-time - */ -void getdns_list_destroy(getdns_list *list); -/** @} - */ - - -/** - * \defgroup dict_create getdns_dict creation/destruction functions - * @{ - */ - -/** - * create a new dictionary with no items - * @return pointer to an allocated dictionary, NULL if insufficient memory - */ -getdns_dict *getdns_dict_create(); -getdns_dict *getdns_dict_create_with_context(getdns_context *context); -getdns_dict *getdns_dict_create_with_memory_functions( - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); -getdns_dict *getdns_dict_create_with_extended_memory_functions( - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - -/** - * destroy a dictionary and all items within that dictionary - * be aware that if you have fetched any data from the dictionary it will - * no longer be available (you are likely to experience bad things if you try) - */ -void getdns_dict_destroy(getdns_dict *dict); -/** @} - */ - - -/** + * \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 callbacks getdns_callback functions + * \defgroup funcs Asynchronous API functions + * \defgroup syncfuns Synchronous API functions that do not use callbacks + * \defgroup utils Utility functions + */ + + +/** + * \ingroup getdns_list_get_functions getdns_list_get functions * @{ */ @@ -743,7 +656,7 @@ getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, /** - * \defgroup getdns_dict_get_functions getdns_dict_get functions + * \ingroup getdns_dict_get_functions getdns_dict_get functions * @{ */ @@ -817,7 +730,43 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict, /** - * \defgroup getdns_list_set getdns_list_set functions + * \ingroup list_create getdns_list creation/destruction functions + * @{ + */ + +/** + * create a new list with no items + * @return pointer to an allocated list, NULL if insufficient memory + */ +getdns_list *getdns_list_create(); +getdns_list *getdns_list_create_with_context(getdns_context *context); +getdns_list *getdns_list_create_with_memory_functions( + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); +getdns_list *getdns_list_create_with_extended_memory_functions( + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + + +/** + * free memory allocated to the list (also frees all children of the list) + * note that lists and bindata retrieved from the list via the getdns_list_get_* + * helper functions will be destroyed as well - if you fetched them previously + * you MUST copy those instances BEFORE you destroy the list else + * unpleasant things will happen at run-time + */ +void getdns_list_destroy(getdns_list *list); +/** @} +*/ + + +/** + * \ingroup getdns_list_set getdns_list_set functions * @{ */ @@ -867,7 +816,40 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, /** - * \defgroup getdns_dict_set getdns_dict_set functions + * \ingroup dict_create getdns_dict creation/destruction functions + * @{ + */ + +/** + * create a new dictionary with no items + * @return pointer to an allocated dictionary, NULL if insufficient memory + */ +getdns_dict *getdns_dict_create(); +getdns_dict *getdns_dict_create_with_context(getdns_context *context); +getdns_dict *getdns_dict_create_with_memory_functions( + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); +getdns_dict *getdns_dict_create_with_extended_memory_functions( + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + +/** + * destroy a dictionary and all items within that dictionary + * be aware that if you have fetched any data from the dictionary it will + * no longer be available (you are likely to experience bad things if you try) + */ +void getdns_dict_destroy(getdns_dict *dict); +/** @} +*/ + + +/** + * \ingroup getdns_dict_set getdns_dict_set functions * @{ */ @@ -917,7 +899,7 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); /** - * \defgroup callbacks getdns_callback functions + * \ingroup callbacks getdns_callback functions * @{ */ @@ -926,16 +908,12 @@ typedef void (*getdns_callback_t) (getdns_context *context, getdns_callback_type_t callback_type, getdns_dict * response, void *userarg, getdns_transaction_t transaction_id); - -getdns_return_t -getdns_cancel_callback(getdns_context *context, - getdns_transaction_t transaction_id); /** @} */ /** - * \defgroup funcs Asynchronous API functions + * \ingroup funcs Asynchronous API functions * @{ */ @@ -1016,7 +994,82 @@ getdns_service(getdns_context *context, /** - * \defgroup syncfuns Synchronous API functions that do not use callbacks + * \ingroup context_create getdns_context creation/destruction functions + * @{ + */ + +/** + * creates a new getdns context with default settings. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @return GETDNS_RETURN_GOOD on success +*/ +getdns_return_t +getdns_context_create(getdns_context ** context, int set_from_os); + + +/** + * creates a new getdns context with default settings using custom memory functions. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @param malloc custom malloc function + * @param realloc custom realloc function + * @param malloc custom free function + * @return GETDNS_RETURN_GOOD on success +*/ +getdns_return_t +getdns_context_create_with_memory_functions( + getdns_context ** context, + int set_from_os, + void *(*malloc) (size_t), + void *(*realloc) (void *, size_t), + void (*free) (void *) +); + + +/** + * creates a new getdns context with default settings using extended custom memory functions. + * If used multi-threaded, user must define appropriate OpenSSL callback locking functions + * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. + * @param context context that can be used immediately with other API calls + * @param set_from_os select to use os defaults or to specify user defined values + * @param malloc custom malloc function + * @param realloc custom realloc function + * @param malloc custom free function + * @return GETDNS_RETURN_GOOD on success +*/ +getdns_return_t +getdns_context_create_with_extended_memory_functions( + getdns_context **context, + int set_from_os, + void *userarg, + void *(*malloc) (void *userarg, size_t), + void *(*realloc) (void *userarg, void *, size_t), + void (*free) (void *userarg, void *) +); + +void getdns_context_destroy(getdns_context *context); +/** @} + */ + + +/** +* \ingroup callbacks getdns_callback functions +* @{ +*/ +getdns_return_t +getdns_cancel_callback(getdns_context *context, + getdns_transaction_t transaction_id); +/** @} + */ + + +/** + * \ingroup syncfuns Synchronous API functions that do not use callbacks * These functions do not use callbacks, when the application calls one of these * functions the library retrieves all of the data before returning. Return * values are exactly the same as if you had used a callback with the @@ -1086,7 +1139,7 @@ getdns_service_sync(getdns_context *context, */ /** - * \defgroup utils Utility functions + * \ingroup utils Utility functions * @{ */ @@ -1128,71 +1181,7 @@ char *getdns_display_ip_address(const getdns_bindata /** - * \defgroup context_create getdns_context creation/destruction functions - * @{ - */ - -/** - * creates a new getdns context with default settings. - * If used multi-threaded, user must define appropriate OpenSSL callback locking functions - * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. - * @param context context that can be used immediately with other API calls - * @param set_from_os select to use os defaults or to specify user defined values - * @return GETDNS_RETURN_GOOD on success - */ -getdns_return_t -getdns_context_create(getdns_context ** context, int set_from_os); - - -/** - * creates a new getdns context with default settings using custom memory functions. - * If used multi-threaded, user must define appropriate OpenSSL callback locking functions - * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. - * @param context context that can be used immediately with other API calls - * @param set_from_os select to use os defaults or to specify user defined values - * @param malloc custom malloc function - * @param realloc custom realloc function - * @param malloc custom free function - * @return GETDNS_RETURN_GOOD on success - */ -getdns_return_t -getdns_context_create_with_memory_functions( - getdns_context ** context, - int set_from_os, - void *(*malloc) (size_t), - void *(*realloc) (void *, size_t), - void (*free) (void *) -); - - -/** - * creates a new getdns context with default settings using extended custom memory functions. - * If used multi-threaded, user must define appropriate OpenSSL callback locking functions - * (e.g. CRYPTO_THREADID_set_call) depending on the library version used. - * @param context context that can be used immediately with other API calls - * @param set_from_os select to use os defaults or to specify user defined values - * @param malloc custom malloc function - * @param realloc custom realloc function - * @param malloc custom free function - * @return GETDNS_RETURN_GOOD on success - */ -getdns_return_t -getdns_context_create_with_extended_memory_functions( - getdns_context **context, - int set_from_os, - void *userarg, - void *(*malloc) (void *userarg, size_t), - void *(*realloc) (void *userarg, void *, size_t), - void (*free) (void *userarg, void *) -); - -void getdns_context_destroy(getdns_context *context); -/** @} - */ - - -/** - * \defgroup context_set getdns_context_set functions + * \ingroup context_set getdns_context_set functions * @{ */ getdns_return_t