new libunbound calls documented.

git-svn-id: file:///svn/unbound/trunk@1571 be551aaa-1e26-0410-a405-d3ace91eadb9

doc/Changelog

@@ -3,6 +3,7 @@
 	  ipv6 AAAA records for their nameservers with ipv4 mapped contents.
 	  Still tries to do so, could work when deployed in intranet.
 	  Higher verbosity shows the error.
+	- new libunbound calls documented.
 
 30 March 2009: Wouter
 	- Fixup LDFLAGS from libevent sourcedir compile configure restore.

doc/libunbound.3.in

@@ -35,7 +35,12 @@
 .B ub_resolve_async,
 .B ub_cancel,
 .B ub_resolve_free,
-.B ub_strerror
+.B ub_strerror,
+.B ub_ctx_print_local_zones,
+.B ub_ctx_zone_add,
+.B ub_ctx_zone_remove,
+.B ub_ctx_data_add,
+.B ub_ctx_data_remove
 \- Unbound DNS validating resolver @version@ functions.
 .SH "SYNOPSIS"
 .LP
@@ -114,6 +119,21 @@
 .LP
 \fIconst char *\fR
 \fBub_strerror\fR(\fIint\fR err);
+.LP
+\fIint\fR
+\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
+.LP
+\fIint\fR
+\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
+.LP
+\fIint\fR
+\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
+.LP
+\fIint\fR
+\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
+.LP
+\fIint\fR
+\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 .SH "DESCRIPTION"
 .LP
 .B Unbound 
@@ -278,7 +298,8 @@ void my_callback_function(void* my_arg, int err,
                   struct ub_result* result);
 .IP
 The async_id is returned so you can (at your option) decide to track it
-and cancel the request if needed.
+and cancel the request if needed.  If you pass a NULL pointer the async_id
+is not returned. 
 .TP
 .B ub_cancel
 Cancel an async query in progress.  This may return an error if the query
@@ -291,6 +312,23 @@ Free struct ub_result contents after use.
 .B ub_strerror
 Convert error value from one of the unbound library functions 
 to a human readable string.
+.TP
+.B ub_ctx_print_local_zones
+Debug printout the local authority information to stdout.
+.TP
+.B ub_ctx_zone_add
+Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) 
+statement.
+.TP
+.B ub_ctx_zone_remove
+Delete zone from local authority info.
+.TP
+.B ub_ctx_data_add
+Add resource record data to local authority info, like local\-data
+\fIunbound.conf\fR(5) statement.
+.TP
+.B ub_ctx_data_remove
+Delete local authority data from the name given.
 .SH "RESULT DATA STRUCTURE"
 .LP
 The result of the DNS resolution and validation is returned as 

doc/unbound.doxygen

@@ -496,6 +496,9 @@ EXCLUDE                = ./build \
                          util/configlexer.c \
                          util/locks.h \
 			 pythonmod/Unbound.py \
+			 pythonmod/interface.h \
+			 pythonmod/examples/resgen.py \
+			 pythonmod/examples/resmod.py \
 			 ./ldns-src
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 

libunbound/libunbound.c

@@ -907,7 +907,8 @@ ub_ctx_hosts(struct ub_ctx* ctx, char* fname)
 	return UB_NOERROR;
 }
 
-static int ub_ctx_check_finalize(struct ub_ctx* ctx)
+/** finalize the context, if not already finalized */
+static int ub_ctx_finalize(struct ub_ctx* ctx)
 {
 	int res = 0;
 	lock_basic_lock(&ctx->cfglock);
@@ -918,10 +919,10 @@ static int ub_ctx_check_finalize(struct ub_ctx* ctx)
 	return res;
 }
 
-/** Print local zones and RR data */
+/* Print local zones and RR data */
 int ub_ctx_print_local_zones(struct ub_ctx* ctx)
 {   
-    int res = ub_ctx_check_finalize(ctx);
+	int res = ub_ctx_finalize(ctx);
 	if (res) return res;
 
 	local_zones_print(ctx->local_zones);
@@ -929,7 +930,7 @@ int ub_ctx_print_local_zones(struct ub_ctx* ctx)
 	return UB_NOERROR;
 }
 
-/** Add a new zone */
+/* Add a new zone */
 int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type)
 {
 	enum localzone_type t;
@@ -938,7 +939,7 @@ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type)
 	int nmlabs;
 	size_t nmlen;
 
-    int res = ub_ctx_check_finalize(ctx);
+	int res = ub_ctx_finalize(ctx);
 	if (res) return res;
 
 	if(!local_zone_str2type(zone_type, &t)) {
@@ -950,16 +951,18 @@ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type)
 	}
 
 	lock_quick_lock(&ctx->local_zones->lock);
-	if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN))) {
+	if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, 
+		LDNS_RR_CLASS_IN))) {
 		/* already present in tree */
 		lock_rw_wrlock(&z->lock);
 		z->type = t; /* update type anyway */
 		lock_rw_unlock(&z->lock);
-		free(nm);
 		lock_quick_unlock(&ctx->local_zones->lock);
+		free(nm);
 		return UB_NOERROR;
 	}
-	if(!local_zones_add_zone(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN, t)) {
+	if(!local_zones_add_zone(ctx->local_zones, nm, nmlen, nmlabs, 
+		LDNS_RR_CLASS_IN, t)) {
 		lock_quick_unlock(&ctx->local_zones->lock);
 		return UB_NOMEM;
 	}
@@ -967,7 +970,7 @@ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type)
 	return UB_NOERROR;
 }
 
-/** Remove zone */
+/* Remove zone */
 int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name)
 {   
 	struct local_zone* z;
@@ -975,7 +978,7 @@ int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name)
 	int nmlabs;
 	size_t nmlen;
 
-    int res = ub_ctx_check_finalize(ctx);
+	int res = ub_ctx_finalize(ctx);
 	if (res) return res;
 
 	if(!parse_dname(zone_name, &nm, &nmlen, &nmlabs)) {
@@ -983,25 +986,27 @@ int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name)
 	}
 
 	lock_quick_lock(&ctx->local_zones->lock);
-	if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN))) {
+	if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, 
+		LDNS_RR_CLASS_IN))) {
 		/* present in tree */
 		local_zones_del_zone(ctx->local_zones, z);
 	}
-	free(nm);
 	lock_quick_unlock(&ctx->local_zones->lock);
+	free(nm);
 	return UB_NOERROR;
 }
 
-/** Add new RR data */
+/* Add new RR data */
 int ub_ctx_data_add(struct ub_ctx* ctx, char *data)
 {
 	ldns_buffer* buf;
-    int res = ub_ctx_check_finalize(ctx);
+	int res = ub_ctx_finalize(ctx);
 	if (res) return res;
 
 	lock_basic_lock(&ctx->cfglock);
 	buf = ldns_buffer_new(ctx->env->cfg->msg_buffer_size);
 	lock_basic_unlock(&ctx->cfglock);
+	if(!buf) return UB_NOMEM;
 
 	res = local_zones_add_RR(ctx->local_zones, data, buf);
 
@@ -1015,13 +1020,14 @@ int ub_ctx_data_remove(struct ub_ctx* ctx, char *data)
 	uint8_t* nm;
 	int nmlabs;
 	size_t nmlen;
-    int res = ub_ctx_check_finalize(ctx);
+	int res = ub_ctx_finalize(ctx);
 	if (res) return res;
 
 	if(!parse_dname(data, &nm, &nmlen, &nmlabs)) 
 		return UB_SYNTAX;
 
-	local_zones_del_data(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN);
+	local_zones_del_data(ctx->local_zones, nm, nmlen, nmlabs, 
+		LDNS_RR_CLASS_IN);
 
 	free(nm);
 	return UB_NOERROR;

libunbound/unbound.h

@@ -470,10 +470,49 @@ void ub_resolve_free(struct ub_result* result);
  */
 const char* ub_strerror(int err);
 
+/**
+ * Debug routine.  Print the local zone information to stdout.
+ * @param ctx: context.  Is finalized by the routine.
+ * @return 0 if OK, else error.
+ */
 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
+
+/**
+ * Add a new zone with the zonetype to the local authority info of the 
+ * library.
+ * @param ctx: context.  Is finalized by the routine.
+ * @param zone_name: name of the zone in text, "example.com"
+ *	If it already exists, the type is updated.
+ * @param zone_type: type of the zone (like for unbound.conf) in text.
+ * @return 0 if OK, else error.
+ */
 int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type);
+
+/**
+ * Remove zone from local authority info of the library.
+ * @param ctx: context.  Is finalized by the routine.
+ * @param zone_name: name of the zone in text, "example.com"
+ *	If it does not exist, nothing happens.
+ * @return 0 if OK, else error.
+ */
 int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name);
+
+/**
+ * Add localdata to the library local authority info.
+ * Similar to local-data config statement.
+ * @param ctx: context.  Is finalized by the routine.
+ * @param data: the resource record in text format, for example
+ *	"www.example.com IN A 127.0.0.1"
+ * @return 0 if OK, else error.
+ */
 int ub_ctx_data_add(struct ub_ctx* ctx, char *data);
+
+/**
+ * Remove localdata from the library local authority info.
+ * @param ctx: context.  Is finalized by the routine.
+ * @param data: the name to delete all data from, like "www.example.com".
+ * @return 0 if OK, else error.
+ */
 int ub_ctx_data_remove(struct ub_ctx* ctx, char *data);
 
 #endif /* _UB_UNBOUND_H */

pythonmod/pythonmod.c

@@ -33,6 +33,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \file
+ * Python module for unbound.  Calls python script.
+ */
 
 /* ignore the varargs unused warning from SWIGs internal vararg support */
 #ifdef __GNUC__

pythonmod/pythonmod.h

@@ -33,6 +33,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \file
+ * Python module for unbound.  Calls python script.
+ */
 #ifndef PYTHONMOD_H
 #define PYTHONMOD_H
 #include "util/module.h"
@@ -55,10 +59,13 @@ struct pythonmod_env {
    /** Python module. */
    PyObject* module;
 
-   /** Module functions */
+   /** Module init function */
    PyObject* func_init;
+   /** Module deinit function */
    PyObject* func_deinit;
+   /** Module operate function */
    PyObject* func_operate;
+   /** Module super_inform function */
    PyObject* func_inform;
 
    /** Python dictionary. */

services/localzone.c

@@ -119,7 +119,7 @@ local_data_cmp(const void* d1, const void* d2)
 		b->namelabs, &m);
 }
 
-/** form wireformat from text format domain name */
+/* form wireformat from text format domain name */
 int
 parse_dname(const char* str, uint8_t** res, size_t* len, int* labs)
 {

services/localzone.h

@@ -297,6 +297,11 @@ void local_zones_del_data(struct local_zones* zones,
 
 /** 
  * Form wireformat from text format domain name. 
+ * @param str: the domain name in text "www.example.com"
+ * @param res: resulting wireformat is stored here with malloc.
+ * @param len: length of resulting wireformat.
+ * @param labs: number of labels in resulting wireformat.
+ * @return false on error, syntax or memory. Also logged.
  */
 int parse_dname(const char* str, uint8_t** res, size_t* len, int* labs);