public API start.

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

doc/Changelog

@@ -1,3 +1,6 @@
+29 November 2007: Wouter
+	- 0.9 public API start.
+
 28 November 2007: Wouter
 	- Changeup plan for 0.8 - no complication needed, a simple solution
 	  has been chosen for authoritative features.

libunbound/unbound.h

@@ -0,0 +1,134 @@
+/*
+ * unbound.h - unbound validating resolver public API
+ *
+ * Copyright (c) 2007, NLnet Labs. All rights reserved.
+ *
+ * This software is open source.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 
+ * Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ * 
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * 
+ * Neither the name of the NLNET LABS nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * \file
+ *
+ * This file contains functions to resolve DNS queries and 
+ * validate the answers. Synchonously and asynchronously.
+ */
+#ifdef _UB_UNBOUND_H
+#define _UB_UNBOUND_H
+
+/**
+ * The validation context is created to hold the resolver status,
+ * validation keys and a small cache (containing messages, rrsets,
+ * roundtrip times, trusted keys, lameness information).
+ *
+ * Its contents are internally defined.
+ */
+struct ub_val_ctx;
+
+/**
+ * Create a resolving and validation context.
+ * @return a new context. default initialisation.
+ * 	returns NULL on error (malloc failure).
+ */
+struct ub_val_ctx* ub_val_ctx_create();
+
+/**
+ * Destroy a validation context and free all its resources.
+ * @param ctx: context to delete.
+ */
+void ub_val_ctx_delete(struct ub_val_ctx* ctx);
+
+/**
+ * setup configuration for the given context.
+ * @param ctx: context.
+ * @param fname: unbound config file (not all settings applicable).
+ * 	This is a power-users interface that lets you specify all sorts
+ * 	of options.
+ * 	For some specific options, such as adding trust anchors, special
+ * 	routines exist.
+ * @return: 0 if OK, else error.
+ */
+int ub_val_ctx_config(struct ub_val_ctx* ctx, char* fname);
+
+/**
+ * Add a trust anchor to the given context.
+ * The trust anchor is a string, on one line, that holds a valid DNSKEY or
+ * DS RR. 
+ * @param ctx: context.
+ * @param ta: string, with zone-format RR on one line.
+ * 	<domainname> <TTL optional> <type> <class optional> <rdata contents>
+ * @return 0 if OK, else error.
+ */
+int ub_val_ctx_add_ta(struct ub_val_ctx* ctx, char* fname);
+
+/**
+ * Add trust anchors to the given context.
+ * The trust anchor the name of a bind-style config file with trusted-keys{}.
+ * @param ctx: context.
+ * @param fname: filename of file with bind-style config entries with trust
+ * 	anchors.
+ * @return 0 if OK, else error.
+ */
+int ub_val_ctx_trustedkeys(struct ub_val_ctx* ctx, char* fname);
+
+/**
+ * Set a context to be synchronous or asynchronous.
+ * @param ctx: context.
+ * @param async: set false if it should be synchronous (waiting) or
+ * 	true if it should be asynchronous (resolving and validating in the
+ * 	background).
+ * @return 0 if OK, else error.
+ */
+int ub_val_ctx_async(struct ub_val_ctx* ctx, int async);
+
+/**
+ * Poll a context to see if it has any new results
+ * Do not poll in a loop, instead extract the fd below to poll for readiness,
+ * and then check, or wait using the wait routine.
+ * @param ctx: asynchronous context.
+ * @return: 0 if nothing to read, or nonzero if a result is available.
+ */
+int ub_val_ctx_poll(struct ub_val_ctx* ctx);
+
+/**
+ * Wait for an context to finish with results.
+ * @param ctx: asynchronous context.
+ * @return: 0 if OK, else error.
+ */
+int ub_val_ctx_wait(struct ub_val_ctx* ctx);
+
+/**
+ * Get file descriptor. Wait for it to become readable, at this point
+ * answers are returned from the asynchronous validating resolver.
+ * @param ctx: asynchronous context.
+ * @return: -1 on error, or file descriptor to use select(2) with.
+ */
+int ub_val_ctx_fd(struct ub_val_ctx* ctx);
+
+#endif /* _UB_UNBOUND_H */