Maintained by: NLnet Labs
Data Structures | Macros | Typedefs | Functions
unbound-event.h File Reference

This file contains the unbound interface for use with user defined pluggable event bases. More...

Data Structures

struct  ub_event_base_vmt
 The Virtual Method Table for and ub_event_base "object". More...
 
struct  ub_event_base
 A user defined pluggable event base is registered by providing a ub_event_base "object" with the ub_ctx_create_ub_event() function. More...
 
struct  ub_event_vmt
 The Virtual Method Table for and ub_event "object". More...
 
struct  ub_event
 An "object" comprising a user defined pluggable event. More...
 

Macros

#define UB_EV_TIMEOUT   0x01
 event timeout
 
#define UB_EV_READ   0x02
 event fd readable
 
#define UB_EV_WRITE   0x04
 event fd writable
 
#define UB_EV_SIGNAL   0x08
 event signal
 
#define UB_EV_PERSIST   0x10
 event must persist
 
#define UB_EVENT_MAGIC   0x44d74d78
 magic number to identify this version of the pluggable event api
 

Typedefs

typedef void(* ub_event_callback_type) (void *, int, void *, int, int, char *)
 

Functions

struct ub_ctxub_ctx_create_ub_event (struct ub_event_base *base)
 Create a resolving and validation context. More...
 
struct ub_ctxub_ctx_create_event (struct event_base *base)
 Create a resolving and validation context. More...
 
int ub_ctx_set_event (struct ub_ctx *ctx, struct event_base *base)
 Set a new libevent event_base on a context created with ub_ctx_create_event. More...
 
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)
 Perform resolution and validation of the target name. More...
 

Detailed Description

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 whith 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.

Function Documentation

◆ ub_ctx_create_ub_event()

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.

Parameters
basethe pluggable event base that the caller has created. The unbound context uses this event base.
Returns
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.

References ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, and ub_ctx_create_nopipe().

◆ ub_ctx_create_event()

struct ub_ctx* ub_ctx_create_event ( struct 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.

Parameters
basethe event base that the caller has created. The unbound context uses this event base.
Returns
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.

References ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, ub_ctx_create_nopipe(), ub_ctx_delete(), and ub_libevent_event_base().

◆ ub_ctx_set_event()

int ub_ctx_set_event ( struct ub_ctx ctx,
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.

Parameters
ctxthe ub_ctx to update. Must have been created with ub_ctx_create_event
basethe new event_base to attach to the ctx
Returns
0 if OK, else error

References ub_ctx::cfglock, ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, ub_ctx::event_worker, libworker_delete_event(), UB_INITFAIL, ub_libevent_event_base(), ub_libevent_get_event_base(), and UB_NOERROR.

◆ ub_resolve_event()

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 
)

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().

Parameters
ctxcontext with event_base in it. The context is finalized, and can no longer accept all config changes.
namedomain name in text format (a string).
rrtypetype of RR in host order, 1 is A.
rrclassclass of RR in host order, 1 is IN (for internet).
mydatathis data is your own data (you can pass NULL), and is passed on to the callback function.
callbackthis 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) 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). 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.

Parameters
async_idif 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.
Returns
0 if OK, else error.