Electroneum
unbound-event.h File Reference
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  ub_event_base_vmt
 
struct  ub_event_base
 
struct  ub_event_vmt
 
struct  ub_event
 

Macros

#define UB_EV_TIMEOUT   0x01
 
#define UB_EV_READ   0x02
 
#define UB_EV_WRITE   0x04
 
#define UB_EV_SIGNAL   0x08
 
#define UB_EV_PERSIST   0x10
 
#define UB_EVENT_MAGIC   0x44d74d78
 

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)
 
struct ub_ctxub_ctx_create_event (struct event_base *base)
 
int ub_ctx_set_event (struct ub_ctx *ctx, struct event_base *base)
 
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)
 

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.

Definition in file unbound-event.h.

Macro Definition Documentation

◆ UB_EV_PERSIST

#define UB_EV_PERSIST   0x10

event must persist

Definition at line 75 of file unbound-event.h.

◆ UB_EV_READ

#define UB_EV_READ   0x02

event fd readable

Definition at line 69 of file unbound-event.h.

◆ UB_EV_SIGNAL

#define UB_EV_SIGNAL   0x08

event signal

Definition at line 73 of file unbound-event.h.

◆ UB_EV_TIMEOUT

#define UB_EV_TIMEOUT   0x01

event timeout

Definition at line 67 of file unbound-event.h.

◆ UB_EV_WRITE

#define UB_EV_WRITE   0x04

event fd writable

Definition at line 71 of file unbound-event.h.

◆ UB_EVENT_MAGIC

#define UB_EVENT_MAGIC   0x44d74d78

magic number to identify this version of the pluggable event api

Definition at line 78 of file unbound-event.h.

Typedef Documentation

◆ ub_event_callback_type

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

Definition at line 173 of file unbound-event.h.

Function Documentation

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

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

◆ 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

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