1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
/*
* 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 libevent.
* 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. If unbound is compiled without libevent support then
* this header file is not supposed to be installed on the system.
*
* Use ub_ctx_create_event_base() to create an unbound context that uses
* the event base that you have made. Then, use the ub_resolve_event call
* to add DNS resolve queries to the context. Those then run when you
* call event_dispatch() on your 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.
*/
#ifndef _UB_UNBOUND_EVENT_H
#define _UB_UNBOUND_EVENT_H
#ifdef __cplusplus
extern "C" {
#endif
struct ub_ctx;
struct ub_result;
struct event_base;
typedef void (*ub_event_callback_t)(void*, int, void*, int, int, char*);
/**
* 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 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 event_base on a context created with ub_ctx_create_event.
* 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)
* 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.
* @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_t callback, int* async_id);
#ifdef __cplusplus
}
#endif
#endif /* _UB_UNBOUND_H */
|
