unbound-event.h revision 356345
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 user defined 40 * pluggable event bases. 41 * 42 * Use ub_ctx_create_event_ub_base() to create an unbound context that uses 43 * the user provided event base API. Then, use the ub_resolve_event call 44 * to add DNS resolve queries to the context. Those then run whith the 45 * provided event_base, and when they are done you get a function callback. 46 * 47 * This method does not fork another process or create a thread, the effort 48 * is done by the unbound state machines that are connected to the event base. 49 * 50 * It is also possible to provide a libevent based event base by using 51 * ub_ctx_create_event_base(). But you have to use the same libevent that 52 * unbound was compiled with, otherwise it wouldn't work, the event and 53 * event_base structures would be different. 54 */ 55#ifndef _UB_UNBOUND_EVENT_H 56#define _UB_UNBOUND_EVENT_H 57 58#ifdef __cplusplus 59extern "C" { 60#endif 61 62struct ub_ctx; 63struct ub_result; 64struct event_base; 65 66/** event timeout */ 67#define UB_EV_TIMEOUT 0x01 68/** event fd readable */ 69#define UB_EV_READ 0x02 70/** event fd writable */ 71#define UB_EV_WRITE 0x04 72/** event signal */ 73#define UB_EV_SIGNAL 0x08 74/** event must persist */ 75#define UB_EV_PERSIST 0x10 76 77/** magic number to identify this version of the pluggable event api */ 78#define UB_EVENT_MAGIC 0x44d74d78 79 80struct ub_event; 81struct ub_event_base; 82struct timeval; 83 84/** 85 * The Virtual Method Table for and ub_event_base "object" 86 */ 87struct ub_event_base_vmt { 88 /** Destructor for the ub_event_base object, 89 * (not called by libunbound) */ 90 void (*free)(struct ub_event_base*); 91 /** Run the event loop 92 * (not called by libunbound when using ub_resolve_event) */ 93 int (*dispatch)(struct ub_event_base*); 94 /** Exit the given event loop */ 95 int (*loopexit)(struct ub_event_base*, struct timeval*); 96 /** Instantiate a new ub_event associated with this event base */ 97 struct ub_event* (*new_event)(struct ub_event_base*, 98 int fd, short bits, void (*cb)(int, short, void*), void* arg); 99 /** Instantiate a new signal associated with this event base, 100 * (not called by libunbound) */ 101 struct ub_event* (*new_signal)(struct ub_event_base*, int fd, 102 void (*cb)(int, short, void*), void* arg); 103 /** Create a new ub_event associated with the given wsaevent, 104 * (not called by libunbound) */ 105 struct ub_event* (*winsock_register_wsaevent)(struct ub_event_base*, 106 void* wsaevent, void (*cb)(int, short, void*), void* arg); 107}; 108 109/** 110 * A user defined pluggable event base is registered by providing a 111 * ub_event_base "object" with the ub_ctx_create_ub_event() function. 112 * The magic number must be correct and the Virtual Method Table must be 113 * fully equipped providing the event base API to be used by libunbound. 114 */ 115struct ub_event_base { 116 /** magic must be UB_EVENT_MAGIC (0x44d74d78) */ 117 unsigned long magic; 118 /** Virtual Method Table for ub_event_base */ 119 struct ub_event_base_vmt* vmt; 120}; 121 122/** 123 * The Virtual Method Table for and ub_event "object" 124 */ 125struct ub_event_vmt { 126 /** Add event bits for this event to fire on. 127 * The event will be deactivated before this function is called. */ 128 void (*add_bits)(struct ub_event*, short); 129 /** Configure the event so it will not longer fire on given bits 130 * The event will be deactivated before this function is called. */ 131 void (*del_bits)(struct ub_event*, short); 132 /** Change or set the file descriptor on the event 133 * The event will be deactivated before this function is called. */ 134 void (*set_fd)(struct ub_event*, int); 135 /** Destructor for the ub_event object */ 136 void (*free)(struct ub_event*); 137 /** Activate the event. The given timeval is an timeout value. */ 138 int (*add)(struct ub_event*, struct timeval*); 139 /** Deactivate the event */ 140 int (*del)(struct ub_event*); 141 /** Reconfigure and activate a timeout event */ 142 int (*add_timer)(struct ub_event*, struct ub_event_base*, 143 void (*cb)(int, short, void*), void* arg, struct timeval*); 144 /** Deactivate the timeout event */ 145 int (*del_timer)(struct ub_event*); 146 /** Activate a signal event (not called by libunbound). */ 147 int (*add_signal)(struct ub_event*, struct timeval*); 148 /** Deactivate a signal event (not called by libunbound). */ 149 int (*del_signal)(struct ub_event*); 150 /** Destructor for a ub_event associated with a wsaevent, 151 * (not called by libunbound) 152 */ 153 void (*winsock_unregister_wsaevent)(struct ub_event* ev); 154 /** Libunbound will signal the eventloop when a TCP windows socket 155 * will block on next read or write (given by the eventbits), to work 156 * around edge trigger event behaviour of select on windows with TCP. 157 */ 158 void (*winsock_tcp_wouldblock)(struct ub_event*, int eventbit); 159}; 160 161/** 162 * An "object" comprising a user defined pluggable event. 163 * The magic number must be correct and the Virtual Method Table must be 164 * fully equipped providing the ub_event API to be used by libunbound. 165 */ 166struct ub_event { 167 /** magic must be UB_EVENT_MAGIC (0x44d74d78) */ 168 unsigned long magic; 169 /** Virtual Method Table for ub_event */ 170 struct ub_event_vmt* vmt; 171}; 172 173typedef void (*ub_event_callback_type)(void*, int, void*, int, int, char*, int); 174 175/** 176 * Create a resolving and validation context. 177 * The information from /etc/resolv.conf and /etc/hosts is not utilised by 178 * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. 179 * @param base: the pluggable event base that the caller has created. 180 * The unbound context uses this event base. 181 * @return a new context. default initialisation. 182 * returns NULL on error. 183 * You must use ub_resolve_event with this context. 184 * Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done 185 * with the event_base. Setup the options you like with the other functions. 186 */ 187struct ub_ctx* ub_ctx_create_ub_event(struct ub_event_base* base); 188 189/** 190 * Create a resolving and validation context. 191 * The information from /etc/resolv.conf and /etc/hosts is not utilised by 192 * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. 193 * You have to use the same libevent that unbound was compiled with, 194 * otherwise it wouldn't work, the event and event_base structures would 195 * be different. 196 * @param base: the event base that the caller has created. The unbound 197 * context uses this event base. 198 * @return a new context. default initialisation. 199 * returns NULL on error. 200 * You must use ub_resolve_event with this context. 201 * Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done 202 * with the event_base. Setup the options you like with the other functions. 203 */ 204struct ub_ctx* ub_ctx_create_event(struct event_base* base); 205 206/** 207 * Set a new libevent event_base on a context created with ub_ctx_create_event. 208 * You have to use the same libevent that unbound was compiled with, 209 * otherwise it wouldn't work, the event and event_base structures would 210 * be different. 211 * Any outbound queries will be canceled. 212 * @param ctx the ub_ctx to update. Must have been created with ub_ctx_create_event 213 * @param base the new event_base to attach to the ctx 214 * @return 0 if OK, else error 215 */ 216int ub_ctx_set_event(struct ub_ctx* ctx, struct event_base* base); 217 218/** 219 * Perform resolution and validation of the target name. 220 * Asynchronous, after a while, the callback will be called with your 221 * data and the result. Uses the event_base user installed by creating the 222 * context with ub_ctx_create_event(). 223 * @param ctx: context with event_base in it. 224 * The context is finalized, and can no longer accept all config changes. 225 * @param name: domain name in text format (a string). 226 * @param rrtype: type of RR in host order, 1 is A. 227 * @param rrclass: class of RR in host order, 1 is IN (for internet). 228 * @param mydata: this data is your own data (you can pass NULL), 229 * and is passed on to the callback function. 230 * @param callback: this is called on completion of the resolution. 231 * It is called as: 232 * void callback(void* mydata, int rcode, void* packet, int packet_len, 233 * int sec, char* why_bogus) 234 * with mydata: the same as passed here, you may pass NULL, 235 * with rcode: 0 on no error, nonzero for mostly SERVFAIL situations, 236 * this is a DNS rcode. 237 * with packet: a buffer with DNS wireformat packet with the answer. 238 * do not inspect if rcode != 0. 239 * do not write or free the packet buffer, it is used internally 240 * in unbound (for other callbacks that want the same data). 241 * with packet_len: length in bytes of the packet buffer. 242 * with sec: 0 if insecure, 1 if bogus, 2 if DNSSEC secure. 243 * with why_bogus: text string explaining why it is bogus (or NULL). 244 * These point to buffers inside unbound; do not deallocate the packet or 245 * error string. 246 * 247 * If an error happens during processing, your callback will be called 248 * with error set to a nonzero value (and result==NULL). 249 * For localdata (etc/hosts) the callback is called immediately, before 250 * resolve_event returns, async_id=0 is returned. 251 * @param async_id: if you pass a non-NULL value, an identifier number is 252 * returned for the query as it is in progress. It can be used to 253 * cancel the query. 254 * @return 0 if OK, else error. 255 */ 256int ub_resolve_event(struct ub_ctx* ctx, const char* name, int rrtype, 257 int rrclass, void* mydata, ub_event_callback_type callback, 258 int* async_id); 259 260#ifdef __cplusplus 261} 262#endif 263 264#endif /* _UB_UNBOUND_H */ 265