unbound: libunbound/unbound-event.h File Reference

unbound 0.1

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 *, int)

## Functions
struct ub_ctx * | ub_ctx_create_ub_event (struct ub_event_base *base)
| Create a resolving and validation context.
struct ub_ctx * | ub_ctx_create_event (struct event_base *base)
| Create a resolving and validation context.
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.
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.

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

## 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

  base | the 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

  base | the 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::event_base_malloced, 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

  ctx | the ub_ctx to update. Must have been created with ub_ctx_create_event
  base | the 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

  ctx | context with event_base in it. The context is finalized, and can no longer accept all config changes.
  name | domain name in text format (a string).
  rrtype | type of RR in host order, 1 is A.
  rrclass | class of RR in host order, 1 is IN (for internet).
  mydata | this data is your own data (you can pass NULL), and is passed on to the callback function.
  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.

Parameters

  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.

Returns
  0 if OK, else error.

References libworker::base, ub_ctx::cfglock, context_finalize(), context_new(), ub_ctx::event_base, ub_ctx::event_worker, ub_ctx::finalized, libworker_attach_mesh(), libworker_create_event(), ub_comm_base_now(), UB_INITFAIL, UB_NOERROR, and UB_NOMEM.