mirror of https://github.com/getdnsapi/getdns.git
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
This commit is contained in:
Sara Dickinson
parent
b56fbbb604
commit
d3309e89e8
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
|
|
@ -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()"
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue