public API start.

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

diff --git a/doc/Changelog b/doc/Changelog
index 32872c2419de69623d037296093397f34d165004..1aaca44b7af98f54df36c03af2a2d6e1801c20c2 100644 (file)
--- a/doc/Changelog
+++ b/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.

diff --git a/libunbound/unbound.h b/libunbound/unbound.h
new file mode 100644 (file)
index 0000000..479396d
--- /dev/null
+++ b/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 */