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..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 @@ -46,7 +47,10 @@ extern "C" { #define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@" -/* Return values */ +/** + * \defgroup returntypes Return values + * @{ + */ typedef enum getdns_return_t { GETDNS_RETURN_GOOD = 0, GETDNS_RETURN_GENERIC_ERROR = 1, @@ -64,9 +68,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 values texts * @{ */ #define GETDNS_RETURN_GOOD_TEXT "Good" @@ -89,7 +95,7 @@ typedef enum getdns_return_t { /** - * \defgroup dnssecvalues DNSSEC values + * \defgroup dnssecvalues DNSSEC values and texts * @{ */ #define GETDNS_DNSSEC_SECURE 400 @@ -106,7 +112,10 @@ typedef enum getdns_return_t { */ -/* Namespace types */ +/** + * \defgroup namespacetypes Namespace types + * @{ + */ typedef enum getdns_namespace_t { GETDNS_NAMESPACE_DNS = 500, GETDNS_NAMESPACE_LOCALNAMES = 501, @@ -114,9 +123,11 @@ typedef enum getdns_namespace_t { GETDNS_NAMESPACE_MDNS = 503, GETDNS_NAMESPACE_NIS = 504 } getdns_namespace_t; +/** @} + */ /** - * \defgroup Namespace types texts + * \defgroup namespacetypestext Namespace types texts * @{ */ #define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()" @@ -128,14 +139,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 +160,19 @@ typedef enum getdns_resolution_t { */ -/* Redirect policies */ +/** + * \defgroup redirectpolicytype Redirect policies + * @{ + */ 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 policies texts * @{ */ #define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" @@ -160,16 +181,21 @@ typedef enum getdns_redirects_t { */ -/* Transport arrangements */ +/** + * \defgroup transporttypes Transport arrangements + * @{ + */ 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 arrangements texts * @{ */ #define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()" @@ -180,15 +206,21 @@ typedef enum getdns_transport_t { */ +/** + * \defgroup transportlisttypes Transport list values + * @{ + */ /* 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 values texts * @{ */ #define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()" @@ -198,16 +230,21 @@ typedef enum getdns_transport_list_t { */ -/* Suffix appending methods */ +/** + * \defgroup suffixappendtypes Suffix appending values + * @{ + */ 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 values texts * @{ */ #define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()" @@ -218,6 +255,10 @@ typedef enum getdns_append_name_t { */ +/** +* \defgroup contextcodetypes Context code values +* @{ +*/ /* Context codes */ typedef enum getdns_context_code_t { GETDNS_CONTEXT_CODE_NAMESPACES = 600, @@ -239,9 +280,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 values texts * @{ */ #define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces" @@ -266,16 +309,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 types texts * @{ */ #define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it" @@ -285,8 +333,9 @@ 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 @@ -296,8 +345,9 @@ typedef enum getdns_callback_type_t { /** @} */ + /** - * \defgroup respstatus Status Codes for Responses + * \defgroup respstatus Status Codes for responses and text * @{ */ #define GETDNS_RESPSTATUS_GOOD 900 @@ -314,7 +364,7 @@ typedef enum getdns_callback_type_t { */ /** - * \defgroup extvals Values Associated With Extensions + * \defgroup extvals Values associated with extensions * @{ */ #define GETDNS_EXTENSION_TRUE 1000 @@ -325,7 +375,7 @@ typedef enum getdns_callback_type_t { */ /** - * \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 @@ -427,7 +477,7 @@ typedef enum getdns_callback_type_t { */ /** - * \defgroup rrclasses RR classes + * \defgroup rrclasses RR Classes * @{ */ #define GETDNS_RRCLASS_IN 1 @@ -479,6 +529,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 +557,30 @@ 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 + * \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 + * @{ + */ + /** * get the length of the specified list (returned in *answer) * @param list list of any of the supported data types @@ -575,6 +651,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); +/** @} + */ + + +/** + * \ingroup 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,6 +725,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); +/** @} + */ + + +/** + * \ingroup list_create getdns_list creation/destruction functions + * @{ + */ /** * create a new list with no items @@ -660,6 +752,7 @@ getdns_list *getdns_list_create_with_extended_memory_functions( 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_* @@ -668,6 +761,14 @@ getdns_list *getdns_list_create_with_extended_memory_functions( * unpleasant things will happen at run-time */ void getdns_list_destroy(getdns_list *list); +/** @} +*/ + + +/** + * \ingroup getdns_list_set getdns_list_set functions + * @{ + */ /** * assign the child_dict to an item in a parent list, the parent list copies @@ -710,6 +811,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); +/** @} + */ + + +/** + * \ingroup dict_create getdns_dict creation/destruction functions + * @{ + */ /** * create a new dictionary with no items @@ -735,6 +844,14 @@ getdns_dict *getdns_dict_create_with_extended_memory_functions( * 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 + * @{ + */ getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); @@ -767,6 +884,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 +897,37 @@ 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); + +/** + * \ingroup 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 */ +/** + * \ingroup 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,28 +935,92 @@ 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); +/** @} + */ + +/** + * \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, @@ -823,6 +1030,18 @@ getdns_context_create_with_memory_functions( 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, @@ -834,13 +1053,23 @@ getdns_context_create_with_extended_memory_functions( ); 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); +/** @} + */ + /** - * \defgroup syncfuns Synchronous API functions that do not use callbacks + * \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 @@ -871,7 +1100,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 +1138,11 @@ getdns_service_sync(getdns_context *context, /** @} */ +/** + * \ingroup utils Utility functions + * @{ + */ + getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, @@ -943,6 +1176,14 @@ char *getdns_pretty_print_dict(const getdns_dict *some_dict); char *getdns_display_ip_address(const getdns_bindata *bindata_of_ipv4_or_ipv6_address); +/** @} + */ + + +/** + * \ingroup context_set getdns_context_set functions + * @{ + */ getdns_return_t getdns_context_set_context_update_callback( getdns_context *context, @@ -1031,6 +1272,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;