From: Wouter Wijngaards Date: Fri, 30 Nov 2007 14:53:57 +0000 (+0000) Subject: More api work, makefile links library. X-Git-Tag: release-0.9~143 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=83f8775d5adf1020ebb1091137e46ae0e870ca9b;p=thirdparty%2Funbound.git More api work, makefile links library. git-svn-id: file:///svn/unbound/trunk@792 be551aaa-1e26-0410-a405-d3ace91eadb9 --- diff --git a/Makefile.in b/Makefile.in index 42c87f4e8..d9523d0a0 100644 --- a/Makefile.in +++ b/Makefile.in @@ -84,17 +84,20 @@ SIGNIT_SRC=testcode/signit.c checkconf/worker_cb.c $(COMMON_SRC) SIGNIT_OBJ=$(addprefix $(BUILD),$(SIGNIT_SRC:.c=.o)) $(COMPAT_OBJ) MEMSTATS_SRC=testcode/memstats.c checkconf/worker_cb.c $(COMMON_SRC) MEMSTATS_OBJ=$(addprefix $(BUILD),$(MEMSTATS_SRC:.c=.o)) $(COMPAT_OBJ) +LIBUNBOUND_SRC=$(patsubst $(srcdir)/%,%, \ + $(wildcard $(srcdir)/libunbound/*.c) $(COMMON_SRC)) +LIBUNBOUND_OBJ=$(addprefix $(BUILD),$(LIBUNBOUND_SRC:.c=.o)) $(COMPAT_OBJ) ALL_SRC=$(COMMON_SRC) $(UNITTEST_SRC) $(DAEMON_SRC) \ $(TESTBOUND_SRC) $(LOCKVERIFY_SRC) $(PKTVIEW_SRC) $(SIGNIT_SRC) \ - $(MEMSTATS_SRC) $(CHECKCONF_SRC) + $(MEMSTATS_SRC) $(CHECKCONF_SRC) $(LIBUNBOUND_SRC) ALL_OBJ=$(addprefix $(BUILD),$(ALL_SRC:.c=.o) \ $(addprefix compat/,$(LIBOBJS))) $(COMPAT_OBJ) COMPILE=$(LIBTOOL) --tag=CC --mode=compile $(CC) $(CPPFLAGS) $(CFLAGS) LINK=$(LIBTOOL) --tag=CC --mode=link $(CC) $(staticexe) $(RUNTIME_PATH) $(CFLAGS) $(LDFLAGS) -LINK_LIB=$(LIBTOOL) --tag=CC --mode=link $(CC) $(CFLAGS) $(LDFLAGS) -release $(VERSION) +LINK_LIB=$(LIBTOOL) --tag=CC --mode=link $(CC) $(CFLAGS) $(LDFLAGS) $(staticexe) -release $(VERSION) -no-undefined -.PHONY: clean realclean doc lint all install uninstall tests test download_ldns strip +.PHONY: clean realclean doc lint all install uninstall tests test download_ldns strip lib $(BUILD)%.o: $(srcdir)/%.c $(INFO) Build $< @@ -103,13 +106,19 @@ $(BUILD)%.o: $(srcdir)/%.c @if test ! -d $(dir $@); then $(INSTALL) -d $(patsubst %/,%,$(dir $@)); fi $Q$(COMPILE) -c $< -o $@ -all: $(COMMON_OBJ) unbound unbound-checkconf +all: $(COMMON_OBJ) unbound unbound-checkconf lib tests: all unittest testbound lock-verify pktview signit memstats test: tests bash testcode/do-tests.sh +lib: libunbound.la + +libunbound.la: $(LIBUNBOUND_OBJ) + $(INFO) Link $@ + $Q$(LINK_LIB) --export-symbols $(srcdir)/libunbound/ubsyms.def -o $@ $(sort $(LIBUNBOUND_OBJ:.o=.lo)) -rpath $(libdir) $(RUNTIME_PATH) + ifeq ($(patsubst ldns-src%,ldns-src,$(ldnsdir)),ldns-src) ldnslib=$(ldnsdir)/lib/libldns.a $(ldnslib): @@ -208,16 +217,20 @@ install: $(INSTALL) -d $(mandir) $(INSTALL) -d $(mandir)/man8 $(INSTALL) -d $(mandir)/man5 + $(INSTALL) -m 755 -d $(libdir) $(LIBTOOL) --mode=install cp unbound $(bindir)/unbound $(LIBTOOL) --mode=install cp unbound-checkconf $(bindir)/unbound-checkconf $(INSTALL) -c -m 644 $(srcdir)/doc/unbound.8 $(mandir)/man8 $(INSTALL) -c -m 644 $(srcdir)/doc/unbound-checkconf.8 $(mandir)/man8 $(INSTALL) -c -m 644 $(srcdir)/doc/unbound.conf.5 $(mandir)/man5 if test ! -e $(configfile); then $(INSTALL) -d `dirname $(configfile)`; $(INSTALL) -c -m 644 $(srcdir)/doc/example.conf $(configfile); fi + $(LIBTOOL) --mode=install cp libunbound.la $(libdir) + $(LIBTOOL) --mode=finish $(libdir) uninstall: rm -f -- $(bindir)/unbound $(bindir)/unbound-checkconf rm -f -- $(mandir)/man8/unbound.8 $(mandir)/man8/unbound-checkconf.8 $(mandir)/man5/unbound.conf.5 + $(LIBTOOL) --mode=uninstall rm -f $(libdir)/libunbound.la @echo @echo "You still need to remove `dirname $(configfile)` , $(configfile) by hand" diff --git a/doc/Changelog b/doc/Changelog index 1aaca44b7..53fde11ee 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -1,3 +1,8 @@ +30 November 2007: Wouter + - makefile that creates libunbound.la, basic file or libunbound.a + when creating static executables (no libtool). + - more API setup. + 29 November 2007: Wouter - 0.9 public API start. diff --git a/libunbound/ubsyms.def b/libunbound/ubsyms.def new file mode 100644 index 000000000..d984cdf4d --- /dev/null +++ b/libunbound/ubsyms.def @@ -0,0 +1,15 @@ +ub_val_ctx_create +ub_val_ctx_delete +ub_val_ctx_config +ub_val_ctx_add_ta +ub_val_ctx_trustedkeys +ub_val_ctx_async +ub_val_ctx_poll +ub_val_ctx_wait +ub_val_ctx_fd +ub_val_ctx_process +ub_val_resolve +ub_val_resolve_async +ub_val_cancel +ub_val_result_free +ub_val_strerror diff --git a/libunbound/unbound.c b/libunbound/unbound.c new file mode 100644 index 000000000..b4856ad3a --- /dev/null +++ b/libunbound/unbound.c @@ -0,0 +1,280 @@ +/* + * unbound.c - unbound validating resolver public API implementation + * + * 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. + * + */ + +/* include the public api first, it should be able to stand alone */ +#include "libunbound/unbound.h" +#include "config.h" +#include "util/locks.h" +#include "util/config_file.h" +#include "util/alloc.h" + +/** + * The context structure + * + * Contains two pipes for async service + * qq : write queries to the async service pid/tid. + * rr : read results from the async service pid/tid. + */ +struct ub_val_ctx { + /** mutex on query write pipe */ + lock_basic_t qqpipe_lock; + /** the query write pipe, [0] read from, [1] write on */ + int qqpipe[2]; + /** mutex on result read pipe */ + lock_basic_t rrpipe_lock; + /** the result read pipe, [0] read from, [1] write on */ + int rrpipe[2]; + + /** configuration options */ + struct config_file* cfg; + /** do threading (instead of forking) */ + int dothread; + + /** shared caches, and so on */ + struct alloc_cache superalloc; + /** module env master value */ + struct module_env* env; + /** number of modules active, ids from 0 to num-1. */ + int num_modules; + /** the module callbacks, array of num_modules length */ + struct module_func_block** modfunc; + /** local authority zones */ + struct local_zones* local_zones; + + /** TODO list of outstanding queries */ +}; + +/** + * The error constants + */ +enum ub_ctx_err { + /** no error */ + UB_NOERROR = 0, + /** alloc failure */ + UB_NOMEM, + /** socket operation */ + UB_SOCKET, + /** syntax error */ + UB_SYNTAX, + /** DNS service failed */ + UB_SERVFAIL +}; + + +struct ub_val_ctx* +ub_val_ctx_create() +{ + struct ub_val_ctx* ctx = (struct ub_val_ctx*)calloc(1, sizeof(*ctx)); + if(!ctx) { + errno = ENOMEM; + return NULL; + } + if(socketpair(AF_UNIX, SOCK_STREAM, 0, ctx->qqpipe) == -1) { + free(ctx); + return NULL; + } + if(socketpair(AF_UNIX, SOCK_STREAM, 0, ctx->rrpipe) == -1) { + int e = errno; + close(ctx->qqpipe[0]); + close(ctx->qqpipe[1]); + free(ctx); + errno = e; + return NULL; + } + lock_basic_init(&ctx->qqpipe_lock); + lock_basic_init(&ctx->rrpipe_lock); + ctx->cfg = config_create(); + if(!ctx->cfg) { + ub_val_ctx_delete(ctx); + errno = ENOMEM; + return NULL; + } + return ctx; +} + +void +ub_val_ctx_delete(struct ub_val_ctx* ctx) +{ + if(!ctx) return; + lock_basic_destroy(&ctx->qqpipe_lock); + lock_basic_destroy(&ctx->rrpipe_lock); + close(ctx->qqpipe[0]); + close(ctx->qqpipe[1]); + close(ctx->rrpipe[0]); + close(ctx->rrpipe[1]); + config_delete(ctx->cfg); + free(ctx); +} + +int +ub_val_ctx_config(struct ub_val_ctx* ctx, char* fname) +{ + if(!config_read(ctx->cfg, fname)) { + return UB_SYNTAX; + } + return UB_NOERROR; +} + +int +ub_val_ctx_add_ta(struct ub_val_ctx* ctx, char* ta) +{ + char* dup = strdup(ta); + if(!dup) return UB_NOMEM; + if(!cfg_strlist_insert(&ctx->cfg->trust_anchor_list, dup)) { + free(dup); + return UB_NOMEM; + } + return UB_NOERROR; +} + +int +ub_val_ctx_trustedkeys(struct ub_val_ctx* ctx, char* fname) +{ + char* dup = strdup(fname); + if(!dup) return UB_NOMEM; + if(!cfg_strlist_insert(&ctx->cfg->trusted_keys_file_list, dup)) { + free(dup); + return UB_NOMEM; + } + return UB_NOERROR; +} + +int +ub_val_ctx_async(struct ub_val_ctx* ctx, int dothread) +{ + ctx->dothread = dothread; + return UB_NOERROR; +} + +static int +pollit(struct ub_val_ctx* ctx, struct timeval* t) +{ + fd_set r; + FD_ZERO(&r); + FD_SET(ctx->rrpipe[0], &r); + if(select(ctx->rrpipe[0]+1, &r, NULL, NULL, t) == -1) { + return 0; + } + errno = 0; + return FD_ISSET(ctx->rrpipe[0], &r); +} + +int +ub_val_ctx_poll(struct ub_val_ctx* ctx) +{ + struct timeval t; + memset(&t, 0, sizeof(t)); + return pollit(ctx, &t); +} + +int +ub_val_ctx_wait(struct ub_val_ctx* ctx) +{ + /* TODO until no more queries outstanding */ + while(1) { + (void)pollit(ctx, NULL); + ub_val_ctx_process(ctx); + } + return UB_NOERROR; +} + +int +ub_val_ctx_fd(struct ub_val_ctx* ctx) +{ + return ctx->rrpipe[0]; +} + +int +ub_val_ctx_process(struct ub_val_ctx* ctx) +{ + return UB_NOERROR; +} + +int +ub_val_resolve(struct ub_val_ctx* ctx, char* name, int rrtype, + int rrclass, int* secure, int* data, struct ub_val_result** result) +{ + /* become a resolver thread for a bit */ + + return UB_NOERROR; +} + +int +ub_val_resolve_async(struct ub_val_ctx* ctx, char* name, int rrtype, + int rrclass, void* mydata, ub_val_callback_t callback, int* async_id) +{ + return UB_NOERROR; +} + +int +ub_val_cancel(struct ub_val_ctx* ctx, int async_id) +{ + return UB_NOERROR; +} + +void +ub_val_result_free(struct ub_val_result* result) +{ + char** p; + if(!result) return; + free(result->qname); + free(result->canonname); + for(p = result->data; *p; p++) + free(*p); + free(result->data); + free(result->len); + free(result); +} + +const char* +ub_val_strerror(int err) +{ + switch(err) { + case UB_NOERROR: return "no error"; + case UB_NOMEM: return "out of memory"; + case UB_SOCKET: return "socket io error"; + case UB_SYNTAX: return "syntax error"; + case UB_SERVFAIL: return "server failure"; + default: return "unknown error"; + } +} diff --git a/libunbound/unbound.h b/libunbound/unbound.h index 1655830c3..82a065482 100644 --- a/libunbound/unbound.h +++ b/libunbound/unbound.h @@ -38,9 +38,60 @@ * * This file contains functions to resolve DNS queries and * validate the answers. Synchonously and asynchronously. + * + * Several ways to use this interface from an application wishing + * to perform (validated) DNS lookups. + * + * All start with + * ctx = ub_val_ctx_create(); + * err = ub_val_ctx_add_ta(ctx, "..."); + * err = ub_val_ctx_add_ta(ctx, "..."); + * ... some lookups + * ... call ub_val_ctx_delete(ctx); when you want to stop. + * + * Application not threaded. Blocking. + * int err = ub_val_resolve(ctx, "www.example.com", ... + * if(err) fprintf(stderr, "lookup error: %s\n", ub_val_strerror(err)); + * ... use the answer + * + * Application not threaded. Non-blocking ('asynchronous'). + * err = ub_val_resolve_async(ctx, "www.example.com", ... my_callback); + * ... application resumes processing ... + * ... and when either ub_val_ctx_poll(ctx) is true + * ... or when the file descriptor ub_val_ctx_fd(ctx) is readable, + * ... or whenever, the app calls ... + * ub_val_ctx_process(ctx); + * ... if no result is ready, the app resumes processing above, + * ... or process() calls my_callback() with results. + * + * ... if the application has nothing more to do, wait for answer + * ub_val_ctx_wait(ctx); + * + * Application threaded. Blocking. + * Blocking, same as above. The current thread does the work. + * Multiple threads can use the *same context*, each does work and uses + * shared cache data from the context. + * + * Application threaded. Non-blocking ('asynchronous'). + * err = ub_val_ctx_async(ctx, 1); + * ... same as async for non-threaded + * ... the callbacks are called in the thread that calls process(ctx) + * + * If not threading is compiled in, the above async example uses fork(2) to + * create a process to perform the work. The forked process exits when the + * calling process exits, or ctx_delete() is called. + * Otherwise, for asynchronous with threading, a worker thread is created. + * + * The blocking calls use shared ctx-cache when threaded. Thus + * ub_val_resolve() and ub_val_resolve_async() && ub_val_ctx_wait() are + * not the same. The first makes the current thread do the work, setting + * up buffers, etc, to perform its thing (but using shared cache data). + * The second calls another worker thread (or process) to perform the work. + * And no buffers need to be setup, but a context-switch happens. */ -#ifdef _UB_UNBOUND_H +#ifndef _UB_UNBOUND_H #define _UB_UNBOUND_H +#include /** * The validation context is created to hold the resolver status, @@ -57,23 +108,79 @@ struct ub_val_ctx; * with ub_val_result_free(). */ struct ub_val_result { - /** a list of network order DNS rdata items, terminated with a + /** The original question, name text string. */ + char* qname; + /** the type asked for */ + int qtype; + /** the class asked for */ + int qclass; + + /** + * a list of network order DNS rdata items, terminated with a * NULL pointer, so that data[0] is the first result entry, - * data[1] the second, and the last entry is NULL. */ + * data[1] the second, and the last entry is NULL. + * If there was no data, data[0] is NULL. + */ char** data; - /** the length in bytes of the data items */ + + /** the length in bytes of the data items, len[i] for data[i] */ size_t* len; + + /** + * canonical name for the result (the final cname). + * zero terminated string. + * May be NULL if no canonical name exists. + */ + char* canonname; + + /** + * If there was no data, and the domain did not exist, this is true. + * If it is false, and there was no data, then the domain name + * is purported to exist, but the requested data type is not available. + */ + int nxdomain; + + /** + * If the result was not secure (secure==0), and this result is due + * to a security failure, bogus is true. + * This means the data has been actively tampered with, signatures + * failed, expected signatures were not present, timestamps on + * signatures were out of date and so on. + * + * If !secure and !bogus, this can happen if the data is not secure + * because security is disabled for that domain name. + * This means the data is from a domain where data is not signed. + */ + int bogus; }; +/** + * Callback for results of async queries. + * The readable function definition looks like: + * void my_callback(void* my_arg, int err, int secure, int havedata, + * struct ub_val_result* result); + * It is called with + * my_arg: your pointer to a (struct of) data of your choice, or NULL. + * err: if 0 all is OK, otherwise an error occured and no results + * are forthcoming. + * secure: if true, the result is validated securely. + * havedata: if true, there was data, false if no data. + * result: pointer to more detailed result structure. + * This structure is allocated on the heap and needs to be + * freed with ub_val_result_free(result); + */ +typedef void (*ub_val_callback_t)(void*, int, int, int, struct ub_val_result*); + /** * Create a resolving and validation context. * @return a new context. default initialisation. - * returns NULL on error (malloc failure). + * returns NULL on error. */ struct ub_val_ctx* ub_val_ctx_create(); /** * Destroy a validation context and free all its resources. + * Outstanding async queries are killed and callbacks are not called for them. * @param ctx: context to delete. */ void ub_val_ctx_delete(struct ub_val_ctx* ctx); @@ -95,6 +202,8 @@ int ub_val_ctx_config(struct ub_val_ctx* ctx, char* fname); * The trust anchor is a string, on one line, that holds a valid DNSKEY or * DS RR. * @param ctx: context. + * At this time it is only possible to add trusted keys before the + * first resolve is done. * @param ta: string, with zone-format RR on one line. * * @return 0 if OK, else error. @@ -105,6 +214,8 @@ int ub_val_ctx_add_ta(struct ub_val_ctx* ctx, char* ta); * Add trust anchors to the given context. * The trust anchor the name of a bind-style config file with trusted-keys{}. * @param ctx: context. + * At this time it is only possible to add trusted keys before the + * first resolve is done. * @param fname: filename of file with bind-style config entries with trust * anchors. * @return 0 if OK, else error. @@ -112,20 +223,22 @@ int ub_val_ctx_add_ta(struct ub_val_ctx* ctx, char* ta); int ub_val_ctx_trustedkeys(struct ub_val_ctx* ctx, char* fname); /** - * Set a context to be synchronous or asynchronous. + * Set a context behaviour for asynchronous action. * @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). + * @param dothread: if true, enables threading and a call to resolve_async() + * creates a thread to handle work in the background. + * If false, a process is forked to handle work in the background. + * Changes to this setting after async() calls have been made have + * no effect (delete and re-create the context to change). * @return 0 if OK, else error. */ -int ub_val_ctx_async(struct ub_val_ctx* ctx, int async); +int ub_val_ctx_async(struct ub_val_ctx* ctx, int dothread); /** * 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. + * @param ctx: context. * @return: 0 if nothing to read, or nonzero if a result is available. * If nonzero, call ctx_process() to get do any callbacks. */ @@ -134,7 +247,7 @@ int ub_val_ctx_poll(struct ub_val_ctx* ctx); /** * Wait for a context to finish with results. Calls ctx_process() after * the wait for you. After the wait, there are no more outstanding queries. - * @param ctx: asynchronous context. + * @param ctx: context. * @return: 0 if OK, else error. */ int ub_val_ctx_wait(struct ub_val_ctx* ctx); @@ -143,7 +256,9 @@ 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. * Then call the ub_val_ctx_process to continue processing. - * @param ctx: asynchronous context. + * This routine works immediately after context creation, the fd + * does not change. + * @param ctx: context. * @return: -1 on error, or file descriptor to use select(2) with. */ int ub_val_ctx_fd(struct ub_val_ctx* ctx); @@ -152,7 +267,7 @@ int ub_val_ctx_fd(struct ub_val_ctx* ctx); * Call this routine to continue processing results from the validating * resolver (when the fd becomes readable). * Will perform necessary callbacks. - * @param ctx: context, asynchronous + * @param ctx: context * @return: 0 if OK, else error. */ int ub_val_ctx_process(struct ub_val_ctx* ctx); @@ -160,11 +275,14 @@ int ub_val_ctx_process(struct ub_val_ctx* ctx); /** * Perform resolution and validation of the target name. * @param ctx: context. - * @param name: domain name in text format (a string). - * @param rrtype: type of RR in host order, 1 is A. + * @param name: domain name in text format (a zero terminated text string). + * @param rrtype: type of RR in host order, 1 is A (address). * @param rrclass: class of RR in host order, 1 is IN (for internet). * @param secure: returns true if the answer validated securely. * false if not. + * It is possible to get a result with no data (data is false), + * and secure is true. This means that the non-existance of the data + * was cryptographically proven (with signatures). * @param data: returns false if there was no data, or the domain did not exist, * else true. * @param result: the result data is returned in a newly allocated result @@ -172,13 +290,15 @@ int ub_val_ctx_process(struct ub_val_ctx* ctx); * @return 0 if OK, else error. */ int ub_val_resolve(struct ub_val_ctx* ctx, char* name, int rrtype, - int rrclass, int* secure, int* data, struct ub_val_result** data); + int rrclass, int* secure, int* data, struct ub_val_result** result); /** * Perform resolution and validation of the target name. * Asynchronous, after a while, the callback will be called with your * data and the result + secure status. - * @param ctx: context, asynchronous. + * @param ctx: context. + * If no thread or process has been created yet to perform the + * work in the background, it is created now. * @param name: domain name in text format (a string). * @param rrtype: type of RR in host order, 1 is A. * @param rrclass: class of RR in host order, 1 is IN (for internet). @@ -186,18 +306,32 @@ int ub_val_resolve(struct ub_val_ctx* ctx, char* name, int rrtype, * and is passed on to the callback function. * @param callback: this is called on completion of the resolution. * It is called as: - * void callback(void* mydata, int secure, int data, + * void callback(void* mydata, int err, int secure, int havedata, * struct ub_val_result* result) * with mydata, the same as passed here, + * with err is 0 when a result has been found. * with secure true if the answer validated securely. - * with data true if any data was found. + * with havedata true if any data was found. * with result newly allocated result structure. - * TODO return errors in async case. + * + * If an error happens during processing, your callback will be called + * with error set to a nonzero value (and secure=0, data=0, result=0). + * @param async_id: if you pass a non-NULL value, an identifier number is + * returned for the query as it is in progress. It can be used to + * cancel the query. * @return 0 if OK, else error. */ int ub_val_resolve_async(struct ub_val_ctx* ctx, char* name, int rrtype, - int rrclass, void* mydata, void (*callback)(void*, int, int, - struct ub_val_result*)); + int rrclass, void* mydata, ub_val_callback_t callback, int* async_id); + +/** + * Cancel an async query in progress. + * Its callback will not be called. + * + * @param ctx: context. + * @return 0 if OK, else error. + */ +int ub_val_cancel(struct ub_val_ctx* ctx, int async_id); /* function to get dns result message in its entirety (a buf) */ /* convenience function to get A */ @@ -205,8 +339,17 @@ int ub_val_resolve_async(struct ub_val_ctx* ctx, char* name, int rrtype, /* convenience to get PTR */ /* convenience to get 'addrinfo', A, AAAA, canonname */ -/* neat error; with errnumber to string conversion. the enum is hidden. */ +/** + * Free storage associated with a result structure. + * @param result: to free + */ +void ub_val_result_free(struct ub_val_result* result); -/* more detail function. with lots of information */ +/** + * Convert error value to a human readable string. + * @param err: error code from one of the ub_val* functions. + * @return pointer to constant text string, zero terminated. + */ +const char* ub_val_strerror(int err); #endif /* _UB_UNBOUND_H */