From: Miek Gieben Date: Tue, 18 Jan 2005 14:28:54 +0000 (+0000) Subject: concatted all _api files together. forget doxygen for this X-Git-Tag: release-0.50~564 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d8fb38201de41356f67b27c8011b5c8012b4fe1a;p=thirdparty%2Fldns.git concatted all _api files together. forget doxygen for this --- diff --git a/doc/LDNS_API b/doc/LDNS_API new file mode 100644 index 00000000..d8895717 --- /dev/null +++ b/doc/LDNS_API @@ -0,0 +1,287 @@ +LibDNS - API + + 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. + +Differences with other DNS libraries + * lwres - TODO + * ??? + +Bottom Layer + lDNS is currently only dependent on libc and uses a few networking + system calls (send/recv and friends). + + Furhter more, it is to be expected that lDNS is going to depend on + a cryptographic library. This will probably be OpenSSL. + +Top Layer + As said, lDNS is modelled after Net::DNS, therefor its 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. + + The following API details are a rewrite of 'perldoc Net::DNS:XXX' where + XXX is the actual manpage. At the top of each section it will state from + which Perl manual page it has been converted. + +API +* From: Net::DNS - Perl interface to the DNS resolver + + Resolver Structures [ldns_resolver] + ldns_resolver* ldns_resolver_new(void) + + A program can have multiple resolver structurs, each maintaining its own + state information such as the nameservers to be queried, whether + recursion is desired, etc. + + Packet Structures [ldns_pkt] + ldns_pkt* ldns_pkt_new(void) + + ldns_resolver queries return ldns_pkt structures. A ldns_pkt structure + has five sections: + + 1 The header section, a ldns_hdr structure. + 2 The question section, a ldns_rr_list structure. + 3 The answer section, a ldns_rr_list structure. + 4 The authority section, a ldns_rr_list structure. + 5 The additional section, a ldns_rr_list structure. + + Header Structure [ldns_hdr] + ldns_hdr represents the header section of a DNS packet. + + Question Section [no special type is used] + ldns_rr_list structure. A list of RRs in the Question section of a DNS + packet. + + Answer Section [no special type is used] + ldns_rr_list structure. A list of RRs in the Question section of a DNS + packet. + + Authority Section [no special type is used] + ldns_rr_list structure. A list of RRs in the Question section of a DNS + packet. + + Additional Section [no special type is used] + ldns_rr_list structure. A list of RRs in the Question section of a DNS + packet. + + RR List Structure [ldns_rr_list] + An array containing Resource Records (RR). + + RR Structures [ldns_rr] + A single Resource Record. + +Functions on ldns_resolver + + ldns_version(resolver *res) + Returns the version of lDNS. + + ldns_mx(ldns_resolver *res, char *dname) + Returns a ldns_rr_list representing the MX records + for the specified name; the list will be sorted by preference. Returns + an empty list if the query failed or no MX records were found. + + This method does not look up A records -- it only performs MX queries. + +* From: Net::DNS::Packet - DNS packet object class + + ldns_pkt * ldns_pkt_new() + Creates a new empty packet. + + ldns_buffer* ldns_pkt_data(ldns_pkt *pkt) + Returns the packet data in binary format, suitable for sending to a + nameserver. [XXX, suitable for sending to a NS?] + + ldns_hdr *ldns_header(ldn_pkt *pkt) + Returns a ldns_hdr structure representing the header section of + the packet. + + ldns_rr_list *ldns_question(ldns_pkt *pkt) + Returns a pointer to a ldns_rr_list representing the question section + of the packet. + + ldns_rr_list *ldns_answer(ldns_pkt *pkt) + Returns a pointer to a ldns_rr_list representing the answer section of + the packet. + + ldns_rr_list *ldns_authority(ldns_pkt *pkt) + Returns a pointer to a ldns_rr_list representing the authority section + of the packet. + + ldns_rr_list *ldns_additional(ldns_pkt *pkt) + Returns a pointer to a ldns_rr_list of representing the additional + section of the packet. + + void ldsn_pkt_print(ldns_pkt *pkt) + Prints the packet data on the standard output in an ASCII format similar + to that used in DNS zone files. See RFC1035. + + ldns_buffer *ldns_pkt_string(ldns_pkt *pkt) + Returns a ldns_buffer containing the string representation of the packet. + + ldns_pkt_answerfrom(ldns_pkt *pkt) + Returns the IP address from which we received this packet. User-created + packets will return NULL. + + uint16_t ldns_pkt_answersize(ldns_pkt *pkt) + Returns the size of the packet in bytes as it was received from a + nameserver. User-created packets will return 0. [XXX user-created??] + + ldns_status ldns_push(ldns_pkt *pkt, ldns_pkt_section section, ldns_rr *rr) + Adds *rr to the specified section of the packet. Return LDNS_STATUS_OK + on success, LDNS_STATUS_ERR otherwise. + + ldns_status ldns_unique_push(ldns_pkt *pkt, ldns_pkt_section section, ldns_rr *rr) + 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. + + ldns_rr *ldns_pop(ldns_pkt, ldns_pkt_section) + Removes a RR from the specified section of the packet. Returns NULL if + no RR's could be popped. + + + ldns_rr_list *ldns_pkt_rrset(ldns_pkt *pkt, .... + Retrieve all RRs in a packet matching certain criteria + +-- STUFF BELOW IS TODO --- +Tsig is implemented after basic functionality is done + + dn_comp [TODO] + $compname = $packet->dn_comp("foo.example.com", $offset); + + Returns a domain name compressed for a particular packet object, to be + stored beginning at the given offset within the packet data. The name + will be added to a running list of compressed domain names for future + use. + + dn_expand [TODO] + use Net::DNS::Packet qw(dn_expand); + ($name, $nextoffset) = dn_expand(\$data, $offset); + + ($name, $nextoffset) = Net::DNS::Packet::dn_expand(\$data, $offset); + + Expands the domain name stored at a particular location in a DNS packet. + The first argument is a reference to a scalar containing the packet + data. The second argument is the offset within the packet where the + (possibly compressed) domain name is stored. + + Returns the domain name and the offset of the next location in the + packet. + + sign_tsig + $key_name = "tsig-key"; + $key = "awwLOtRfpGE+rRKF2+DEiw=="; + + $update = Net::DNS::Update->new("example.com"); + $update->push("update", rr_add("foo.example.com A 10.1.2.3")); + + $update->sign_tsig($key_name, $key); + + $response = $res->send($update); + + Signs a packet with a TSIG resource record (see RFC 2845). Uses the + following defaults: + + algorithm = HMAC-MD5.SIG-ALG.REG.INT + time_signed = current time + fudge = 300 seconds + + If you wish to customize the TSIG record, you'll have to create it + yourself and call the appropriate Net::DNS::RR::TSIG methods. The + following example creates a TSIG record and sets the fudge to 60 + seconds: + + $key_name = "tsig-key"; + $key = "awwLOtRfpGE+rRKF2+DEiw=="; + + $tsig = Net::DNS::RR->new("$key_name TSIG $key"); + $tsig->fudge(60); + + $query = Net::DNS::Packet->new("www.example.com"); + $query->sign_tsig($tsig); + + $response = $res->send($query); + + You shouldn't modify a packet after signing it; otherwise authentication + will probably fail. + + sign_sig0 + SIG0 support is provided through the Net::DNS::RR::SIG class. This class + is not part of the default Net::DNS distribution but resides in the + Net::DNS::SEC distribution. + + $update = Net::DNS::Update->new("example.com"); + $update->push("update", rr_add("foo.example.com A 10.1.2.3")); + $update->sign_sig0("Kexample.com+003+25317.private"); + + SIG0 support is experimental see Net::DNS::RR::SIG for details. + +--- END TODO --- + +* From: Net::DNS::RR - DNS Resource Record class + + ldns_rr is the base structure for DNS Recorce Records. + [ See also the manual pages for each RR type. - TODO??] + + ldns_rr *ldns_rr_new(void) + Returns a pointer to a newly created ldns_rr structure. + + [TODO: do we want the stuff descibed below?] + ldns_rr_new (from string) + $a = Net::DNS::RR->new("foo.example.com. 86400 A 10.1.2.3"); + $mx = Net::DNS::RR->new("example.com. 7200 MX 10 mailhost.example.com."); + $cname = Net::DNS::RR->new("www.example.com 300 IN CNAME www1.example.com"); + $txt = Net::DNS::RR->new("baz.example.com 3600 HS TXT 'text record'"); + + Returns a "Net::DNS::RR" object of the appropriate type and initialized + from the string passed by the user. The format of the string is that + used in zone files, and is compatible with the string returned by + "Net::DNS::RR->string". + + The name and RR type are required; all other information is optional. If + omitted, the TTL defaults to 0 and the RR class defaults to IN. Omitting + the optional fields is useful for creating the empty RDATA sections + required for certain dynamic update operations. See the + "Net::DNS::Update" manual page for additional examples. + + All names must be fully qualified. The trailing dot (.) is optional. + + void ldns_rr_print(ldns_rr *r) + Prints the record to the standard output. + + ldns_buffer *ldns_rr_string(ldns_rr *r) + Returns a ldns_buffer with the string representation of the RR. Calls the rdatastr method to + get the RR-specific data. + + ldns_buffer ldns_rr_rdatastr(ldns_rr *r) + Returns a pointer to a ldns_buffer containing with string containing + RR-specific data. + + ldns_rdf *ldns_rr_name(ldns_rr *r) + Returns the record's domain name as a ldns_rdf type. [XXX how should we + return stuff like this? ldns_rdf, uint8_t, ldns_buffer? + + ldns_rdf_type ldns_rr_get_type(ldns_rr *r) + Returns the record's type. + + ldns_rr_class ldns_rr_get_class(ldns_rr *r) + Returns the record's class. + + uint32_t ldns_rr_get_ttl(ldns_rr *r) + Returns the record's time-to-live (TTL). + + [TODO nodig??] rdlength + $rdlength = $rr->rdlength; + + Returns the length of the record's data section. + + [TODO nodig??] rdata + $rdata = $rr->rdata + + Returns the record's data section as binary data.