diff options
Diffstat (limited to 'doc/tutorial1_mx.dox')
-rw-r--r-- | doc/tutorial1_mx.dox | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/tutorial1_mx.dox b/doc/tutorial1_mx.dox new file mode 100644 index 0000000..f442e7f --- /dev/null +++ b/doc/tutorial1_mx.dox @@ -0,0 +1,98 @@ +/** + \page tutorial1_mx Tutorial 1: Querying for MX records + \dontinclude ldns-mx.c + + The full source code can be found in \link examples/ldns-mx.c \endlink + + ldns-mx is a simple tool that queries your default caching forwarder for + the MX (Mail exchange) record of the given domain. + + <pre> + % ldns-mx nlnetlabs.nl + nlnetlabs.nl. 86400 IN MX 100 omval.tednet.nl. + nlnetlabs.nl. 86400 IN MX 50 open.nlnetlabs.nl. + </pre> + + First of all, we need to include the correct header files, so + that all functions are available to us: + + \skip include + \until dns.h + + In this case we have used a configure script to generate a config.h file + that does all our inclusions for us, so that it can be compiled on + multiple platforms. If your platform supports the include files \c + stdint.h and \c stdlib.h, you can include these instead of using a + configure script. + + The first included files are prerequisites that ldns needs to function. + The last one, of course, includes the functions of ldns itself. + + In our main function, we declare some variables that we are going to use: + + \skipline ldns_resolver + \until ldns_status + + - The \c ldns_resolver structure keeps a list of nameservers, and can perform queries for us + - An \c ldns_rdf is a basic data type of dns, the RDATA. See \ref design for a description about the building blocks of DNS. + In this case, \c domain will be used to store the name the user specifies when calling the program + - An \c ldns_pkt is a DNS packet, for instance a complete query, or an answer + - The \c ldns_rr_list structure contains a list of DNS Resource Records (RRs). In this case, we will store the MX records we find in the list. + - \c ldns_status is the basic type for status messages in ldns. Most functions will return a value of this type. + + First, we parse the command line argument (checks omitted on this page, see full source code), and store it in our \c domain variable: + \skipline ldns_dname_new_frm_str + + This function takes a string containing a domain name (like + "nlnetlabs.nl") and returns an \c ldns_rdf representing that name. If + somehow the given string can not be parsed it returns NULL. + + Then, we create the resolver structure: + \skipline ldns_resolver_new + + Most of the functions work like this, the first argument is a pointer to + the structure where ldns should store its results (which is also a + pointer). The function returns a status code indicating success + (\ref LDNS_STATUS_OK) or an error number. Remember that these types of + functions allocate memory that you should free later (using the + ldns_free_<type> functions). + + The second argument is the filename that contains information about the + resolver structure that is to be created. If this argument is NULL, + /etc/resolv.conf is used. The syntax of the file is like that of + /etc/resolv.conf. + + + + We tell the resolver to query for our domain, type MX, of class IN: + \skipline ldns_resolver_query + \until ) + + The last argument contains flags to influence the type of query the + resolver structure sends. In this case, we want the nameserver to use + recursion, so that we'll get the final answer. Therefore, we specify the + \ref LDNS_RD (Recursion Desired) flag. + + This should return a packet if everything goes well. + + We get all RRs of type MX from the answer packet and store them in our list: + \skipline ldns_pkt_rr_list_by_type + \until ) + + If this list is not empty, we sort and print it: + \skipline ldns_rr_list_sort + \skipline ldns_rr_list_print + + And finally, just to be proper, we free our allocated data: + \skipline free( + \until resolver_deep_free + + For structures that can contain other ldns structures, there are two types of free() function available + - \c ldns_free_<type> frees only the allocated data for the structure itself. + - \c ldns_deep_free_<type> frees the structure, and ALL structures that + are nested in it. For example, of you \c deep_free an ldns_rr_list, + all \c ldns_rr structures that were present in the list are also + freed. + + +*/ |