From a060e723f2f054bb281c13ddd0a07f2023e4cfc7 Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Tue, 11 Apr 2017 23:29:33 +0200 Subject: [PATCH] Doxygen documentation for everything in getdns.h --- src/getdns/getdns.h.in | 436 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 432 insertions(+), 4 deletions(-) diff --git a/src/getdns/getdns.h.in b/src/getdns/getdns.h.in index 5851c023..618bb835 100644 --- a/src/getdns/getdns.h.in +++ b/src/getdns/getdns.h.in @@ -490,12 +490,30 @@ typedef enum getdns_callback_type_t { */ +/** + * Many calls in the DNS API require a DNS context. A DNS context contains + * the information that the API needs in order to process DNS calls, such + * as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. + * The internal structure of the DNS context is opaque, and might be different + * on each OS. When a context is passed to any function, it must be an + * allocated context; the context must not be NULL. + * + * Use getdns_context_set_* functions to configure a context. + */ typedef struct getdns_context getdns_context; + +/** + * When scheduling asynchronous requests, transaction identifiers associated + * with the request are returned. These identifiers are of the type: + * getdns_transaction_t. These identifiers can be used to associate answers + * with requests, and also to cancel outstanding requests. + */ typedef uint64_t getdns_transaction_t; /** - * used to check data types within complex types (dict, list) + * getdns_list_get_data_type() and getdns_dict_get_data_type() return the type + * of data on an index in a getdns_list, or on a name in a getdns_dict. */ typedef enum getdns_data_type { @@ -503,6 +521,9 @@ typedef enum getdns_data_type } getdns_data_type; +/** + * A struct to hold binary data. + */ typedef struct getdns_bindata { size_t size; @@ -893,8 +914,17 @@ void getdns_dict_destroy(getdns_dict *dict); * @{ */ +/** + * create a new entry in the dictionary, or replace the value of an existing entry + * this routine makes a copy of the child_dict_ + * @param dict dictionary in which to add or change the value + * @param name key that identifies which item in the dictionary to add/change + * @param child_dict value to assign to the node identified by name + * @return GETDNS_RETURN_GOOD on success + */ getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); + /** * create a new entry in the dictionary, or replace the value of an existing entry * this routine makes a copy of the child_list @@ -944,7 +974,28 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name); */ /** * The type of the callback function that must be registered when scheduling - * asynchronous requests. + * asynchronous requests. The registered function will be called from the + * eventloop with the following parameters. + * @param context The DNS context that was used in the calling function + * @param callback_type Supplies the reason for the callback. + * This will be one of: + * - GETDNS_CALLBACK_COMPLETE The response has the + * requested data in it + * - GETDNS_CALLBACK_CANCEL The calling program cancelled + * the callback; response is NULL + * - GETDNS_CALLBACK_TIMEOUT The requested action timed + * out; response is filled in with empty structures or + * will contain additional information about the timeout + * when used in combination with the + * return_call_reporting extension. + * - GETDNS_CALLBACK_ERROR The requested action had an + * error; response is NULL. + * @param response A response object with the response data. + * The application is responsible for cleaning up the response + * object with getdns_dict_destroy. + * @param userarg Identical to the userarg passed to the calling function. + * @param transaction_id The transaction identifier that was assigned by the + * calling function. */ typedef void (*getdns_callback_t) (getdns_context *context, getdns_callback_type_t callback_type, @@ -1196,27 +1247,90 @@ getdns_service_sync(getdns_context *context, /** * Convert a domain name in DNS wire format to presentation format. * The newly allocated string should be freed with free. + * @param dns_name_wire_fmt A bindata to the DNS name in wire format + * @param fqdn_as_string A reference to a pointer that will be set + * to a newly allocated string containing the + * presentation format of the name. The caller + * is responsible for deallocate this space with free(). + * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR + * when the wireformat name could not be parsed. */ getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, char **fqdn_as_string); +/** + * Convert a domain name in presentation format to DNS wire format. + * @param fqdn_as_string The name to convert in presentation format. + * @param dns_name_wire_fmt A reference to a pointer that will be set + * to a newly allocated bindata containing the + * DNS wire format of the name. The caller + * is responsible for deallocate this space with free(). + * @return GETDNS_RETURN_GOOD on success or GETDNS_RETURN_GENERIC_ERROR + * when the presentation format name could not be parsed. + */ getdns_return_t getdns_convert_fqdn_to_dns_name( const char *fqdn_as_string, getdns_bindata **dns_name_wire_fmt); +/** + * Convert an Unicode encoded label to ASCII encoding following the + * rules for IDNA 2008 described in RFC 5890-5892. + * @param ulabel The Unicode encoded label to convert. + * @return The ASCII encoding label. The caller is responsible for deallocate + * this space with free(). + */ char *getdns_convert_ulabel_to_alabel(const char *ulabel); +/** + * Convert an ASCII encoded label to Unicode encoding following the + * rules for IDNA 2008 described in RFC 5890-5892. + * @param alabel The ASCII encoded label to convert. + * @return The Unicode encoding label. The caller is responsible for + * deallocation with free(). + */ char *getdns_convert_alabel_to_ulabel(const char *alabel); +/** + * Offline DNSSEC validate Resource Records with the help of support + * records and a DNSSEC trust anchor. + * @param to_validate This is a list of reply_dicts to validate (as can + * be seen under "replies_tree" in a response dict), or + * an RRset with signatures represented as a list of + * rr_dicts. The format of rr_dict can be seen in + * the sections of reply_dicts in response dicts. + * It is also possible to validate the non-existance + * of a query. Besides all the necessary NSEC(3)s plus + * signature, the to_validate should then also contain + * a question rr_dict with a qname, qclass and qtype. + * @param support_records A list of all the DNSKEY, DS and NSEC(3) RRsets + * (in the form of rr_dicts) that may be used to + * validate the RRsets or replies in to_validate. + * The value returned under "validation_chain" in a + * response dict when the dnssec_return_validation_chain + * extension was used, can be used directly for this. + * @param trust_anchors A list of rr_dicts containing the DNSSEC trust anchors. + * The return value of the getdns_root_trust_anchor() + * can be used directly for this. + * @return The function returns one of GETDNS_DNSSEC_SECURE, + * GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, or GETDNS_DNSSEC_INSECURE + * depending on the validation status. + */ getdns_return_t getdns_validate_dnssec(getdns_list *to_validate, getdns_list *support_records, getdns_list *trust_anchors); -/* Get root trust anchor */ +/** + * Get the default list of trust anchor records that is used by the library + * to validate DNSSEC. + * @param utc_date_of_anchor Set to the number of seconds since epoch + * the trust anchors were obtained + * @return The list of DNSSEC trust anchors, or NULL on error. The caller is + * responsible for deallocating the list with getdns_list_destroy(). + */ getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor); /** @@ -1227,6 +1341,13 @@ getdns_list *getdns_root_trust_anchor(time_t *utc_date_of_anchor); */ char *getdns_pretty_print_dict(const getdns_dict *some_dict); +/** + * Converts a getdns_bindata representing an IPv4 or IPv6 address to a + * textual representation. + * @param bindata_of_ipv4_or_ipv6_address The IP address to convert. + * @return character array (caller must free this) containing the textual + * representation of the address. + */ char *getdns_display_ip_address(const getdns_bindata *bindata_of_ipv4_or_ipv6_address); @@ -1238,6 +1359,16 @@ char *getdns_display_ip_address(const getdns_bindata * \addtogroup context_set getdns_context_set functions * @{ */ + +/** + * An application can be notified when the context is changed. + * @param context The context for which to monitor changes + * @param value The callback function that will be called when any context is + * changed. A update callback function can be deregistered by + * passing NULL. + * @return GETDNS_RETURN_GOOD when succesful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_context_update_callback( getdns_context *context, @@ -1245,73 +1376,339 @@ getdns_context_set_context_update_callback( getdns_context_code_t changed_item) ); +/** + * Specify whether DNS queries are performed with recursive lookups or as a + * stub resolver. The default value is GETDNS_RESOLUTION_RECURSING. + * @param context The context to configure + * @param value GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown resolution types + * @return GETDNS_RETURN_NOT_IMPLEMENTED when getdns was compiled for stub + * resolution only and recursing resolution type was requested. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_resolution_type(getdns_context *context, getdns_resolution_t value); +/** + * Sets the ordered list of namespaces that will be queried. + * This context setting is ignored for the getdns_general and + * getdns_general_sync functions; it is used for the other funtions. + * When a normal lookup is done, the API does the lookups in the order given + * and stops when it gets the first result + * @param context The context to configure + * @param namespace_count The number of values in the namespaces list. + * @param namespaces An ordered list of namespaces that will be queried. + * The values are: GETDNS_NAMESPACE_DNS, + * GETDNS_NAMESPACE_LOCALNAMES, GETDNS_NAMESPACE_NETBIOS, + * GETDNS_NAMESPACE_MDNS, and GETDNS_NAMESPACE_NIS. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown namespace types + * @return GETDNS_RETURN_NOT_IMPLEMENTED when unsupported namespaces were + * given. Currently this implementation supports only + * GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES and has an + * draft implementation of GETDNS_NAMESPACE_MDNS, which has to be + * enabled at configure time. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_namespaces(getdns_context *context, size_t namespace_count, getdns_namespace_t *namespaces); +/** + * Specifies what transport are used for DNS lookups. The default is + * GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP. Use of this function + * is discouraged. Please use getdns_context_set_dns_transport_list() + * instead of this function. + * @param context The context to configure + * @param value The transport to use for DNS lookups. + * The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP, + * GETDNS_TRANSPORT_UDP_ONLY, GETDNS_TRANSPORT_TCP_ONLY, + * GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN, + * GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN or + * GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_dns_transport(getdns_context *context, getdns_transport_t value); +/** + * Specifies what transport is used for DNS lookups. The default is a list + * containing GETDNS_TRANSPORT_UDP then GETDNS_TRANSPORT_TCP. The API will + * return information on the actual transport used to fulfill the request in + * the response dict, when the return_call_reporting extension is used. + * @param context The context to configure + * @param transport_count The number of values in the transports list. + * @param transports An ordered list of transports that will be used for DNS + * lookups. If only one transport value is specified it will + * be the only transport used. Should it not be available + * basic resolution will fail. Fallback transport options are + * specified by including multiple values in the list. + * The values are: GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP, + * or GETDNS_TRANSPORT_TLS + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL with unknown values + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_dns_transport_list(getdns_context *context, size_t transport_count, getdns_transport_list_t *transports); +/** + * Specify number of milliseconds the API will leave an idle TCP or TLS + * connection open for (idle means no outstanding responses and no pending + * queries). When set to 0, all currently open idle connections will be + * closed immediately. The default is 0. + * Note with synchronous queries, idle connections can not reliably be timed. + * Each new synchronous request, will reset the counter no matter the time + * in between requests, and thus leave the connection open always. This + * setting is thus only meaningful when doing requests asynchronously. + * @param context The context to configure + * @param timeout The number of milliseconds the API will leave an idle TCP + * or TLS connection open for + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_idle_timeout(getdns_context *context, uint64_t timeout); +/** + * Limit the number of outstanding DNS queries. When more than limit requests + * are scheduled, they are kept on an internal queue, to be rescheduled when + * the number of outstanding queries drops below the limit again. + * A value of 0 indicates that the number of outstanding DNS queries is + * unlimited, however, queries will be put on the internal queue too when + * system resources are exhausted (i.e. number of available sockets). + * The default value is 0. + * @param context The context to configure + * @param limit The maximum number of outstanding DNS queries. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ getdns_return_t getdns_context_set_limit_outstanding_queries(getdns_context *context, uint16_t limit); +/** + * Specifies number of milliseconds the API will wait for request to return. + * The default is 5000 (i.e. 5 seconds). + * @param context The context to configure + * @param timeout The number of milliseconds the API will wait for request to + * return. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER for a timeout 0, + * or when context was NULL + */ getdns_return_t getdns_context_set_timeout(getdns_context *context, uint64_t timeout); +/** + * Specifies whether or not DNS queries follow redirects. + * The default value is GETDNS_REDIRECTS_FOLLOW. + * In this implementation, redirects are only actively followed in the recursing + * resolution mode. The GETDNS_REDIRECTS_DO_NOT_FOLLOW will not prevent this, + * but the response will be stripped of all resource records that could only be + * found through following redirects. The setting will do this with answers + * provided by an upstream in stub resolution mode too. + * @param context The context to configure + * @param value GETDNS_REDIRECTS_FOLLOW for normal following of redirects + * through CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to + * cause any lookups that would have gone through CNAME and DNAME + * to return the CNAME or DNAME, not the eventual target. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER for an unknown value, + * or when context was NULL + */ getdns_return_t getdns_context_set_follow_redirects(getdns_context *context, getdns_redirects_t value); +/** + * Configure the list of addresses to be used for looking up top-level domains. + * The default is the list of "normal" IANA root servers + * @param context The context to configure + * @param addresses The list contains dicts that are addresses to be used for + * looking up top-level domains. Each dict in the list + * contains at least two names: address_type (whose value is + * a bindata; it is currently either "IPv4" or "IPv6") and + * address_data (whose value is a bindata). + * This implementation also accepts a list of addressxi + * bindatas. Or a list of rr_dicts for address records (i.e. + * the additional section of a NS query for ".", or a with + * getdns_fp2rr_list() converted root.hints file). + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL when there were problems + * parsing the provided addresses list. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dns_root_servers(getdns_context *context, getdns_list *addresses); +/** + * Specifies whether, how and when to append a suffix to the query string. + * The non-standard implementation default is + * GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST. + * @param context The context to configure + * @param value GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST, + * GETDNS_APPEND_NAME_ALWAYS, + * GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE, + * GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, + * or GETDNS_APPEND_NAME_NEVER. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_append_name(getdns_context *context, getdns_append_name_t value); +/** + * Specify the list of suffixes to be appended based on the value off the + * append_name setting. The default is read from OS, or an empty list when + * the context is not initialized with OS defaults. + * @param context The context to configure + * @param value A list of bindatas that are strings that are to be appended + * based on the value off the append_name setting. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_suffix(getdns_context *context, getdns_list *value); +/** + * Specify the DNSSEC trust anchors. The default is to read it from + * @TRUST_ANCHOR_FILE@. + * @param context The context to configure + * @param value A list of rr_dicts for DS or DNSKEY that are the DNSSEC + * trust anchors. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_ CONTEXT_UPDATE_FAIL with unknown values. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dnssec_trust_anchors(getdns_context *context, getdns_list *value); +/** + * Specify the DNSSEC allowed skew. The default is 0. + * @param context The context to configure + * @param value The number of seconds of skew that is allowed in either + * direction when checking an RRSIG's Expiration and Inception + * fields. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_dnssec_allowed_skew(getdns_context *context, uint32_t value); + +/** + * Specify where a stub resolver will send queries. The default value is set + * from the OS when the context is created with the set_from_os flag, or + * empty otherwise. + * @param context The context to configure + * @param upstream_list The upstreams are specified either by a getdns_bindata + * containing a IPv4 or IPv6 address in network format + * or a `getdns_dict`, containing at least a name + * `address_data` whose value is the address bindata, and + * optionally also: + * - `scode_id` containing an getdns_bindata with the + * scope ID for IPv6 link-local addresses. + * - `port` an integer specifying which port to use to + * contact this upstream over UDP and TCP; + * the default is 53 + * - `tsig_algorithm` (a bindata) that is the name of the + * TSIG hash algorithm + * - `tsig_name` (a bindata) that is the name of the TSIG key + * - `tsig_secret` (a bindata) that is the TSIG key + * - `tls_port` (a integer) that is the port to use to + * contact this upstream over TLS + * - `tls_auth_name` (a bindata) that is the name of the + * upstream (as a bindata containing a string) which + * must be verified to confirm its identity. + * - `tls_pubkey_pinset` (a list) containing dicts with + * - `digest` which must be a bindata containing the + * text sha256 + * - `value` A SHA256 hash of the `SubjectPublicKeyInfo` + * of the upstream, which will be used to authenticate + * it. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when `context` or `upstream_list` was `NULL` + * @return GETDNS_RETURN_CONTEXT_UPDATE_FAIL when there were problems parsing + * the `upstream_list`. + */ getdns_return_t getdns_context_set_upstream_recursive_servers(getdns_context *context, getdns_list *upstream_list); +/** + * Set the maximum UDP payload size advertised in a EDNS0 OPT record. + * When not set (the default), outgoing values will adhere to the suggestions + * in RFC 6891 and may follow a scheme that uses multiple values to maximize + * receptivity. + * @param context The context to configure + * @param value The maximum UDP payload size advertised in a EDNS0 OPT record. + * The value must be between 512 and 65536 + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_maximum_udp_payload_size(getdns_context *context, uint16_t value); +/** + * Set the rcode advertised in a EDNS0 OPT record. The default is 0. + * @param context The context to configure + * @param value A value between 0 and 255. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_extended_rcode(getdns_context *context, uint8_t value); +/** + * Set the version advertised in a EDNS0 OPT record. The default is 0. + * @param context The context to configure + * @param value A value between 0 and 255. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_version(getdns_context *context, uint8_t value); +/** + * Set the DO advertised in a EDNS0 OPT record. The default is 0. + * However use of any of the dnssec_* extension will override this setting + * and set the DO bit. + * @param context The context to configure + * @param value A value between 0 and 1. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_edns_do_bit(getdns_context *context, uint8_t value); +/** + * Specify custom memory management functions to be used with this context. + * The given memory management functions will be used for creating the response + * dicts. The response dicts inherit the custom memory management functions + * from the context and will deallocate themselves (and their members) with the + * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used. + * @param context The context to configure + * @param malloc A custom memory allocator. The default is `malloc`. + * @param realloc A custom memory reallocator. The default is `realloc`. + * @param free A custom memory deallocator. The default is `free`. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_memory_functions(getdns_context *context, void *(*malloc) (size_t), @@ -1319,6 +1716,22 @@ getdns_context_set_memory_functions(getdns_context *context, void (*free) (void *) ); +/** + * Specify custom extended memory management functions to be used with this + * context. The value of `userarg` argument will be passed to the custom + * `malloc`, `realloc`, and `free`. + * The response dicts inherit the custom memory management functions + * from the context and will deallocate themselves (and their members) with the + * custom deallocator. By default, the system `malloc`, `realloc`, and `free` are used. + * @param context The context to configure + * @param userarg This value will be passed as the `userarg` argument to the + * custom `malloc`, `realloc` and `free` function. + * @param malloc A custom memory allocator. The default is a wrapper for `malloc`. + * @param realloc A custom memory reallocator. The default is a wrapper for `realloc`. + * @param free A custom memory deallocator. The default is a wrapper for `free`. + * @return GETDNS_RETURN_GOOD when successful. + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL + */ getdns_return_t getdns_context_set_extended_memory_functions(getdns_context *context, void *userarg, @@ -1329,7 +1742,22 @@ getdns_context_set_extended_memory_functions(getdns_context *context, /** @} */ -/* api information support */ +/** + * Retrieve information about the API itself and inspect the current context. + * The returned dictionary can be used with getdns_context_config() directly + * to configure another context with precisely these settings. + * @param context The context from which to get the information + * @return A getdns_dict containing the following name/value pairs: + * - `version_string` (a bindata) represents the version string for this version of the DNS API. + * - `implementation_string` (a bindata) is a string showing which + * implementation of the getdns API this is. In our implementation + * this will always be set to "https://getdnsapi.net" + * - resolution_type (an int) is the type of resolver that the API is + * acting as in this context: GETDNS_RESOLUTION_RECURSING or + * GETDNS_RESOLUTION_STUB. + * - all_context (a dict) with names for all the other settings in + * context. + */ getdns_dict* getdns_context_get_api_information(getdns_context* context);