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;