[getdns-api] New version of the API proposal

[Paul Hoffman]

Greetings again. I have updated the API again based on input from this list and a lot of off-list input. The new version is at <http://www.vpnc.org/getdns-api/>. Here are the changes between 0.252 and 0.268:

=====

Reorganized the C files to match the definitions in this document.

Made it a requirement that the API be a recursing resolver that can possibly be turned into a stub resolver. This caused a few changes in the structure of the context  section, including creating a new subsection and renaming getdns_context_set_upstream_recursive_servers() to getdns_context_set_stub_resolution(). Also added getdns_validate_dnssec() helper function.

Changed all instances of _dict, _list, and _bindata to getdns_dict, getdns_list, and getdns_bindata. Also fixed the bare "dict", "list", "bindata" and "datatype" in the function definitions. Updated the definitions near the end of the document to support this.

Described how to use the callback interface to easily create a polling interface, for applications that prefer polling.

Added the "add_warning_for_bad_dns" extension to point out bad DNS responses.

Changed the name "maximum_payload_size" to "maximum_udp_payload_size". Changed "do-bit" to "do_bit" for consistency.

Fixed the spelling of "return_api_information". Added a sentence about getting "return_api_information" with a PTR query for 127.0.0.1.

Made the "just_address_answers" name appear only if the query was for an A or AAAA record.

Added the "intermediate_aliases" name to the top level of the reply to identify all CNAMEs and DNAMEs traversed through.

Added the "srv_addresses" name in the top level of a query for SRV records to simplify service discovery processing if that is desired.

Removed "SRV" from the things that the getdns_context_set_follow_redirects() context setting affects.

Changed the value arguments for getdns_context_set_dns_root_servers(), getdns_context_set_suffix(), and getdns_context_set_dnssec_trust_anchors() to be a getdns_list, and got rid of sockaddr as a requirement.

Added Section 8.6 on context settings for EDNS.

Removed the statement that C99 is needed, and fixed the getdns_core_only.c and example-all-functions.c files to work fine under C89. Updated the make files to reflect this.

Added GETDNS_COMPILATION_COMMENT macro description.

=====

I'm still quite interested in comments. If I messed anything up with the additions, but all means let me know. Extra points for *not* commenting on this thread, but instead starting a new thread with an appropriate subject.

--Paul Hoffman