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. More... | |
| struct ub_ctx * | ub_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... | |
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.
| 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.
| base | the pluggable event base that the caller has created. The unbound context uses this event base. |
References ub_ctx::created_bg, ub_ctx::dothread, ub_ctx::event_base, and ub_ctx_create_nopipe().
| 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.
| base | the event base that the caller has created. The unbound context uses this event base. |
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().
| 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.
| 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 |
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.
| 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().
| 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.
| 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. |