From: Jelte Jansen <jeltejan@NLnetLabs.nl>
Date: Wed, 24 May 2006 12:54:34 +0000 (+0000)
Subject: small example tutorial
X-Git-Tag: release-1.1.0~138
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4228abf2e074ff93b9ac4db46c0797efb3aefe63;p=thirdparty%2Fldns.git

small example tutorial
---

diff --git a/doc/tutorial1_mx.doxygen b/doc/tutorial1_mx.doxygen
new file mode 100644
index 00000000..915e4b2d
--- /dev/null
+++ b/doc/tutorial1_mx.doxygen
@@ -0,0 +1,47 @@
+/**
+   \page tutorial1_mx Tutorial 1: Qeurying for MX records
+   \dontinclude ldns-mx.c 
+   
+   The full source code can be found in \link examples/ldns-mx.c \endlink
+   
+   This is a simple example that queries for an MX record
+  
+   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 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 (todo link) overview for a description about the building blocks of DNS.
+     \c domain will contain 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
+
+   Then, we create the resolver structure:
+   \skipline ldns_resolver_new
+
+   We tell the resolver to query for our domain, type MX, of class IN:
+   \skipline ldns_resolver_query
+   \until )
+
+   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
+*/
diff --git a/examples/ldns-mx.c b/examples/ldns-mx.c
index 7ddb38d8..265d0b86 100644
--- a/examples/ldns-mx.c
+++ b/examples/ldns-mx.c
@@ -52,7 +52,11 @@ main(int argc, char *argv[])
 	/* use the resolver to send it a query for the mx 
 	 * records of the domain given on the command line
 	 */
-	p = ldns_resolver_query(res, domain, LDNS_RR_TYPE_MX, LDNS_RR_CLASS_IN, LDNS_RD);
+	p = ldns_resolver_query(res,
+	                        domain,
+	                        LDNS_RR_TYPE_MX,
+	                        LDNS_RR_CLASS_IN,
+	                        LDNS_RD);
 
 	ldns_rdf_deep_free(domain);
 	
@@ -62,7 +66,9 @@ main(int argc, char *argv[])
 		/* retrieve the MX records from the answer section of that
 		 * packet
 		 */
-		mx = ldns_pkt_rr_list_by_type(p, LDNS_RR_TYPE_MX, LDNS_SECTION_ANSWER);
+		mx = ldns_pkt_rr_list_by_type(p,
+		                              LDNS_RR_TYPE_MX,
+		                              LDNS_SECTION_ANSWER);
 		if (!mx) {
 			fprintf(stderr, 
 					" *** invalid answer name %s after MX query for %s\n",
diff --git a/ldns/dns.h b/ldns/dns.h
index 1e1db9c7..a29019ec 100644
--- a/ldns/dns.h
+++ b/ldns/dns.h
@@ -11,6 +11,14 @@
  * A bunch of defines that are used in the DNS.
  */
 
+
+/**
+ * \mainpage LDNS Documentation
+ *
+ * \section introduction Introduction
+ *
+ * ldns is a general DNS library
+ */
 #ifndef LDNS_DNS_H
 #define LDNS_DNS_H
 
diff --git a/libdns.doxygen b/libdns.doxygen
index 48dcb4b8..cff5cefe 100644
--- a/libdns.doxygen
+++ b/libdns.doxygen
@@ -423,7 +423,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = . ldns/
+INPUT                  = . ldns/ doc/ examples/
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -432,7 +432,7 @@ INPUT                  = . ldns/
 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp 
 # *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
 
-FILE_PATTERNS          = *.h
+FILE_PATTERNS          = *.h *.c *.doxygen
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 
@@ -461,7 +461,7 @@ EXCLUDE_PATTERNS       =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp