unbound/libunbound/unbound-event.h

   1 /*
   2  * unbound-event.h - unbound validating resolver public API with events
   3  *
   4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
   5  *
   6  * This software is open source.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * Neither the name of the NLNET LABS nor the names of its contributors may
  20  * be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains the unbound interface for use with libevent.
  40  * You have to use the same libevent that unbound was compiled with,
  41  * otherwise it wouldn't work, the event and event_base structures would
  42  * be different.  If unbound is compiled without libevent support then
  43  * this header file is not supposed to be installed on the system.
  44  *
  45  * Use ub_ctx_create_event_base() to create an unbound context that uses
  46  * the event base that you have made.  Then, use the ub_resolve_event call
  47  * to add DNS resolve queries to the context.  Those then run when you
  48  * call event_dispatch() on your event_base, and when they are done you
  49  * get a function callback.
  50  *
  51  * This method does not fork another process or create a thread, the effort
  52  * is done by the unbound state machines that are connected to the event_base.
  53  */
  54 #ifndef _UB_UNBOUND_EVENT_H
  55 #define _UB_UNBOUND_EVENT_H
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 struct ub_ctx;
  62 struct ub_result;
  63 struct event_base;
  64
  65 typedef void (*ub_event_callback_t)(void*, int, void*, int, int, char*);
  66
  67 /**
  68  * Create a resolving and validation context.
  69  * The information from /etc/resolv.conf and /etc/hosts is not utilised by
  70  * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.
  71  * @param base: the event base that the caller has created.  The unbound
  72  *      context uses this event base.
  73  * @return a new context. default initialisation.
  74  *      returns NULL on error.
  75  * You must use ub_resolve_event with this context.
  76  * Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done
  77  * with the event_base.  Setup the options you like with the other functions.
  78  */
  79 struct ub_ctx* ub_ctx_create_event(struct event_base* base);
  80
  81 /**
  82  * Set a new event_base on a context created with ub_ctx_create_event.
  83  * Any outbound queries will be canceled.
  84  * @param ctx the ub_ctx to update.  Must have been created with ub_ctx_create_event
  85  * @param base the new event_base to attach to the ctx
  86  * @return 0 if OK, else error
  87  */
  88 int ub_ctx_set_event(struct ub_ctx* ctx, struct event_base* base);
  89
  90 /**
  91  * Perform resolution and validation of the target name.
  92  * Asynchronous, after a while, the callback will be called with your
  93  * data and the result.  Uses the event_base user installed by creating the
  94  * context with ub_ctx_create_event().
  95  * @param ctx: context with event_base in it.
  96  *      The context is finalized, and can no longer accept all config changes.
  97  * @param name: domain name in text format (a string).
  98  * @param rrtype: type of RR in host order, 1 is A.
  99  * @param rrclass: class of RR in host order, 1 is IN (for internet).
 100  * @param mydata: this data is your own data (you can pass NULL),
 101  *      and is passed on to the callback function.
 102  * @param callback: this is called on completion of the resolution.
 103  *      It is called as:
 104  *      void callback(void* mydata, int rcode, void* packet, int packet_len,
 105  *              int sec, char* why_bogus)
 106  *      with mydata: the same as passed here, you may pass NULL,
 107  *      with rcode: 0 on no error, nonzero for mostly SERVFAIL situations,
 108  *              this is a DNS rcode.
 109  *      with packet: a buffer with DNS wireformat packet with the answer.
 110  *              do not inspect if rcode != 0.
 111  *              do not write or free the packet buffer, it is used internally
 112  *              in unbound (for other callbacks that want the same data).
 113  *      with packet_len: length in bytes of the packet buffer.
 114  *      with sec: 0 if insecure, 1 if bogus, 2 if DNSSEC secure.
 115  *      with why_bogus: text string explaining why it is bogus (or NULL).
 116  *      These point to buffers inside unbound; do not deallocate the packet or
 117  *      error string.
 118  *
 119  *      If an error happens during processing, your callback will be called
 120  *      with error set to a nonzero value (and result==NULL).
 121  *      For localdata (etc/hosts) the callback is called immediately, before
 122  *      resolve_event returns, async_id=0 is returned.
 123  * @param async_id: if you pass a non-NULL value, an identifier number is
 124  *      returned for the query as it is in progress. It can be used to
 125  *      cancel the query.
 126  * @return 0 if OK, else error.
 127  */
 128 int ub_resolve_event(struct ub_ctx* ctx, const char* name, int rrtype,
 129         int rrclass, void* mydata, ub_event_callback_t callback, int* async_id);
 130
 131 #ifdef __cplusplus
 132 }
 133 #endif
 134
 135 #endif /* _UB_UNBOUND_H */