From: Miek Gieben Date: Wed, 19 Jan 2005 15:15:44 +0000 (+0000) Subject: xmlified documentation. It's almost there X-Git-Tag: release-0.50~558 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ca725cbab1592612a738ba72a9e1dcd14426e35f;p=thirdparty%2Fldns.git xmlified documentation. It's almost there --- diff --git a/doc/API.xml b/doc/API.xml index f7129291..a355c2f4 100644 --- a/doc/API.xml +++ b/doc/API.xml @@ -65,10 +65,287 @@ A small abstract will come here, TBD. -
+
+LibDNS (or lDNS) is modelled after the Net::DNS perl library. It has +been shown that Net::DNS can be used vefficiently for +programming DNS aware applications. We want to bring the same +level of efficiency to C programmers. -
+ +The lDNS API consist of two layers. The top-layer, this is +what is actually exported to the application via the library. And the +bottom-layer, this is what lDNS needs to compile and function. + +
+ +
+ +Short intermezzo detailing differences with other libraries. Most important +ones are the libc resolver interface (from BIND8) and the lwres_ interface +from BIND9. + +
+ +
+ +At its lowest level lDNS is only dependent on libc. It uses a +few networking systems calls; socket, bind, send/recv and friends. + + +Further more it is to be expected that lDNS will depend on OpenSSL for +its cryptography. + + +As said, lDNS is modelled after Net::DNS, therefor its application API +looks very much like the one used for Net::DNS. Some modification are made +ofcourse, because not all functionality of Perl can be caught in C. + + + +This API document was written by carefully looking at the documentation +contained in the Net::DNS Perl module. + +
+ +
+ +These functions operate on ldns_rr structures. + + + + +Returns a pointer to the newly created ldns_rr structure. + + +Prints the record to the stream s. + + +Returns a pointer to a ldns_buffer containing with string containing +RR-specific data. + + +Returns the record's owner name as a ldns_rdf type. + + +Returns the record's type. + + +Returns the record's class. + + +Returns the record's time-to-live (TTL). + + + + + +TODO the 'set' functions of the 'get' + +
+ +
+ +In the DNS the atomic data type is an RRset. This is a list +of RRs with the same ownername, type and class. Net::DNS doesn't +have rrsets as a seperate object. + + +In lDNS we have the ldns_rr_list, which just holds a bunch of RR's. +No specific check are made on the RRs that can be put in such a list. +Special wrapper functions exist which allow the usage of ldns_rr_list +of real (RFC compliant) RR sets. + + +TODO: See rr.c + +
+ +
+ + + +Create a new resolver structure and return the pointer to that. + + +Returns the version of lDNS. + + +Returns a ldns_pkt representing the MX records +for the specified dname. Function is documented differently in Net::DNS. +Do we need stuff like this?? XXX + + + Set the default domain for this resolver. This domain is added + when a query is made with a name without a trailing dot. + + + + +Add a new nameserver to the resolver. These nameservers are queried + when a search() or query() is done. + + + + Add a domain to the searchlist of a resolver. + + + Perform a query. Try all the nameservers in the *res structure. Apply + the search list. And default domain. +If type is NULL it defaults to 'A', +If class is NULL it default to 'IN'. + + +Perform a query. Only the default domain is added. +If type is NULL it defaults to 'A', +If class is NULL it default to 'IN'. + + +No search list nor default domain is applied. Return a pointer to a ldns_pkt +structure with the information from the nameserver. +If type is NULL it defaults to 'A', +If class is NULL it default to 'IN'. + + + + +TODO XX Gazillion helper functions to set port, src-port, etc. etc. + +
+ +
+ +A packet structure (ldns_pkt) has five sections: + +The header section, a ldns_hdr structure. +The question section, a ldns_rr_list structure. +The answer section, a ldns_rr_list structure. +The authority section, a ldns_rr_list structure. +The additional section, a ldns_rr_list structure. + + + + + +ldns_hdr represents the header section of a DNS packet. + + +A list of RRs in the Question section of a DNS packet. + + +A list of RRs in the Question section of a DNS packet. + + +A list of RRs in the Question section of a DNS packet. + + +A list of RRs in the Question section of a DNS packet. + + + + + + + +Creates a new empty packet. + + +Returns the packet data in binary format, suitable for sending to a +nameserver. [XXX, suitable for sending to a NS?] + + +Returns a ldns_hdr structure representing the header section of +the packet. + + + Returns a pointer to a ldns_rr_list representing the question section +of the packet. + + + Returns a pointer to a ldns_rr_list representing the answer section of +the packet. + + + +Returns a pointer to a ldns_rr_list representing the authority section +of the packet. + + + +Returns a pointer to a ldns_rr_list of representing the additional +section of the packet. + + + +Prints the packet data on the standard output in an ASCII format similar +to that used in DNS zone files. See RFC1035. + + + +Returns a ldns_buffer containing the string representation of the packet. + + + +Returns the IP address from which we received this packet. User-created +packets will return NULL. + + + +Returns the size of the packet in bytes as it was received from a +nameserver. User-created packets will return 0. [XXX +user-created??] + + + +Adds *rr to the specified section of the packet. Return LDNS_STATUS_OK +on success, LDNS_STATUS_ERR otherwise. + + + +Adds *rr to the specified section of the packet provided that the RR +does not already exist in the packet. Return LDNS_STATUS_OK +on success, LDNS_STATUS_ERR otherwise. + + +Removes a RR from the specified section of the packet. Returns NULL if +no RR's could be popped. + + +Retrieve all RRs in a packet matching certain criteria. XXX function needs +to be specified better. + + + + +
+ +
+ +Some resource records can have special access function no other RR has. +Those are detailed here. XXX TODO don't exist (yet?). + +
+ +
+ +insert your long list here. + +
+