diff options
Diffstat (limited to 'contrib/unbound/libunbound/unbound-event.h')
| -rw-r--r-- | contrib/unbound/libunbound/unbound-event.h | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/contrib/unbound/libunbound/unbound-event.h b/contrib/unbound/libunbound/unbound-event.h new file mode 100644 index 000000000000..5ca81908a904 --- /dev/null +++ b/contrib/unbound/libunbound/unbound-event.h @@ -0,0 +1,265 @@ +/* + * unbound-event.h - unbound validating resolver public API with events + * + * 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 COPYRIGHT + * HOLDER 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 the unbound interface for use with user defined + * pluggable event bases. + * + * Use ub_ctx_create_event_ub_base() to create an unbound context that uses + * the user provided event base API. Then, use the ub_resolve_event call + * to add DNS resolve queries to the context. Those then run with the + * provided event_base, and when they are done you get a function callback. + * + * This method does not fork another process or create a thread, the effort + * is done by the unbound state machines that are connected to the event base. + * + * It is also possible to provide a libevent based event base by using + * ub_ctx_create_event_base(). But you have to use the same libevent that + * unbound was compiled with, otherwise it wouldn't work, the event and + * event_base structures would be different. + */ +#ifndef UB_UNBOUND_EVENT_H +#define UB_UNBOUND_EVENT_H + +#ifdef __cplusplus +extern "C" { +#endif + +struct ub_ctx; +struct ub_result; +struct event_base; + +/** event timeout */ +#define UB_EV_TIMEOUT 0x01 +/** event fd readable */ +#define UB_EV_READ 0x02 +/** event fd writable */ +#define UB_EV_WRITE 0x04 +/** event signal */ +#define UB_EV_SIGNAL 0x08 +/** event must persist */ +#define UB_EV_PERSIST 0x10 + +/** magic number to identify this version of the pluggable event api */ +#define UB_EVENT_MAGIC 0x44d74d78 + +struct ub_event; +struct ub_event_base; +struct timeval; + +/** + * The Virtual Method Table for and ub_event_base "object" + */ +struct ub_event_base_vmt { + /** Destructor for the ub_event_base object, + * (not called by libunbound) */ + void (*free)(struct ub_event_base*); + /** Run the event loop + * (not called by libunbound when using ub_resolve_event) */ + int (*dispatch)(struct ub_event_base*); + /** Exit the given event loop */ + int (*loopexit)(struct ub_event_base*, struct timeval*); + /** Instantiate a new ub_event associated with this event base */ + struct ub_event* (*new_event)(struct ub_event_base*, + int fd, short bits, void (*cb)(int, short, void*), void* arg); + /** Instantiate a new signal associated with this event base, + * (not called by libunbound) */ + struct ub_event* (*new_signal)(struct ub_event_base*, int fd, + void (*cb)(int, short, void*), void* arg); + /** Create a new ub_event associated with the given wsaevent, + * (not called by libunbound) */ + struct ub_event* (*winsock_register_wsaevent)(struct ub_event_base*, + void* wsaevent, void (*cb)(int, short, void*), void* arg); +}; + +/** + * A user defined pluggable event base is registered by providing a + * ub_event_base "object" with the ub_ctx_create_ub_event() function. + * The magic number must be correct and the Virtual Method Table must be + * fully equipped providing the event base API to be used by libunbound. + */ +struct ub_event_base { + /** magic must be UB_EVENT_MAGIC (0x44d74d78) */ + unsigned long magic; + /** Virtual Method Table for ub_event_base */ + struct ub_event_base_vmt* vmt; +}; + +/** + * The Virtual Method Table for and ub_event "object" + */ +struct ub_event_vmt { + /** Add event bits for this event to fire on. + * The event will be deactivated before this function is called. */ + void (*add_bits)(struct ub_event*, short); + /** Configure the event so it will not longer fire on given bits + * The event will be deactivated before this function is called. */ + void (*del_bits)(struct ub_event*, short); + /** Change or set the file descriptor on the event + * The event will be deactivated before this function is called. */ + void (*set_fd)(struct ub_event*, int); + /** Destructor for the ub_event object */ + void (*free)(struct ub_event*); + /** Activate the event. The given timeval is an timeout value. */ + int (*add)(struct ub_event*, struct timeval*); + /** Deactivate the event */ + int (*del)(struct ub_event*); + /** Reconfigure and activate a timeout event */ + int (*add_timer)(struct ub_event*, struct ub_event_base*, + void (*cb)(int, short, void*), void* arg, struct timeval*); + /** Deactivate the timeout event */ + int (*del_timer)(struct ub_event*); + /** Activate a signal event (not called by libunbound). */ + int (*add_signal)(struct ub_event*, struct timeval*); + /** Deactivate a signal event (not called by libunbound). */ + int (*del_signal)(struct ub_event*); + /** Destructor for a ub_event associated with a wsaevent, + * (not called by libunbound) + */ + void (*winsock_unregister_wsaevent)(struct ub_event* ev); + /** Libunbound will signal the eventloop when a TCP windows socket + * will block on next read or write (given by the eventbits), to work + * around edge trigger event behaviour of select on windows with TCP. + */ + void (*winsock_tcp_wouldblock)(struct ub_event*, int eventbit); +}; + +/** + * An "object" comprising a user defined pluggable event. + * The magic number must be correct and the Virtual Method Table must be + * fully equipped providing the ub_event API to be used by libunbound. + */ +struct ub_event { + /** magic must be UB_EVENT_MAGIC (0x44d74d78) */ + unsigned long magic; + /** Virtual Method Table for ub_event */ + struct ub_event_vmt* vmt; +}; + +typedef void (*ub_event_callback_type)(void*, int, void*, int, int, char*, int); + +/** + * Create a resolving and validation context. + * The information from /etc/resolv.conf and /etc/hosts is not utilised by + * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. + * @param base: the pluggable event base that the caller has created. + * The unbound context uses this event base. + * @return a new context. default initialisation. + * returns NULL on error. + * You must use ub_resolve_event with this context. + * Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done + * with the event_base. Setup the options you like with the other functions. + */ +struct ub_ctx* ub_ctx_create_ub_event(struct ub_event_base* base); + +/** + * Create a resolving and validation context. + * The information from /etc/resolv.conf and /etc/hosts is not utilised by + * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. + * You have to use the same libevent that unbound was compiled with, + * otherwise it wouldn't work, the event and event_base structures would + * be different. + * @param base: the event base that the caller has created. The unbound + * context uses this event base. + * @return a new context. default initialisation. + * returns NULL on error. + * You must use ub_resolve_event with this context. + * Do not call ub_ctx_async, ub_poll, ub_wait, ub_process, this is all done + * with the event_base. Setup the options you like with the other functions. + */ +struct ub_ctx* ub_ctx_create_event(struct event_base* base); + +/** + * Set a new libevent event_base on a context created with ub_ctx_create_event. + * You have to use the same libevent that unbound was compiled with, + * otherwise it wouldn't work, the event and event_base structures would + * be different. + * Any outbound queries will be canceled. + * @param ctx the ub_ctx to update. Must have been created with ub_ctx_create_event + * @param base the new event_base to attach to the ctx + * @return 0 if OK, else error + */ +int ub_ctx_set_event(struct ub_ctx* ctx, struct event_base* base); + +/** + * Perform resolution and validation of the target name. + * Asynchronous, after a while, the callback will be called with your + * data and the result. Uses the event_base user installed by creating the + * context with ub_ctx_create_event(). + * @param ctx: context with event_base in it. + * The context is finalized, and can no longer accept all config changes. + * @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). + * @param mydata: this data is your own data (you can pass NULL), + * 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 rcode, void* packet, int packet_len, + * int sec, char* why_bogus, int was_ratelimited) + * with mydata: the same as passed here, you may pass NULL, + * with rcode: 0 on no error, nonzero for mostly SERVFAIL situations, + * this is a DNS rcode. + * with packet: a buffer with DNS wireformat packet with the answer. + * do not inspect if rcode != 0. + * do not write or free the packet buffer, it is used internally + * in unbound (for other callbacks that want the same data). + * with packet_len: length in bytes of the packet buffer. + * with sec: 0 if insecure, 1 if bogus, 2 if DNSSEC secure. + * with why_bogus: text string explaining why it is bogus (or NULL). + * with was_ratelimited: if the query was ratelimited. + * These point to buffers inside unbound; do not deallocate the packet or + * error string. + * + * If an error happens during processing, your callback will be called + * with error set to a nonzero value (and result==NULL). + * For localdata (etc/hosts) the callback is called immediately, before + * resolve_event returns, async_id=0 is returned. + * @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_resolve_event(struct ub_ctx* ctx, const char* name, int rrtype, + int rrclass, void* mydata, ub_event_callback_type callback, + int* async_id); + +#ifdef __cplusplus +} +#endif + +#endif /* UB_UNBOUND_EVENT_H */ |