1/*	$NetBSD$	*/
2
3/*
4 * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
5 * Copyright (C) 2000, 2001  Internet Software Consortium.
6 *
7 * Permission to use, copy, modify, and/or distribute this software for any
8 * purpose with or without fee is hereby granted, provided that the above
9 * copyright notice and this permission notice appear in all copies.
10 *
11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 * PERFORMANCE OF THIS SOFTWARE.
18 */
19
20/* Id: lookup.h,v 1.14 2009/01/17 23:47:43 tbox Exp  */
21
22#ifndef DNS_LOOKUP_H
23#define DNS_LOOKUP_H 1
24
25/*****
26 ***** Module Info
27 *****/
28
29/*! \file dns/lookup.h
30 * \brief
31 * The lookup module performs simple DNS lookups.  It implements
32 * the full resolver algorithm, both looking for local data and
33 * resolving external names as necessary.
34 *
35 * MP:
36 *\li	The module ensures appropriate synchronization of data structures it
37 *	creates and manipulates.
38 *
39 * Reliability:
40 *\li	No anticipated impact.
41 *
42 * Resources:
43 *\li	TBS
44 *
45 * Security:
46 *\li	No anticipated impact.
47 *
48 * Standards:
49 *\li	RFCs:	1034, 1035, 2181, TBS
50 *\li	Drafts:	TBS
51 */
52
53#include <isc/lang.h>
54#include <isc/event.h>
55
56#include <dns/types.h>
57
58ISC_LANG_BEGINDECLS
59
60/*%
61 * A 'dns_lookupevent_t' is returned when a lookup completes.
62 * The sender field will be set to the lookup that completed.  If 'result'
63 * is ISC_R_SUCCESS, then 'names' will contain a list of names associated
64 * with the address.  The recipient of the event must not change the list
65 * and must not refer to any of the name data after the event is freed.
66 */
67typedef struct dns_lookupevent {
68	ISC_EVENT_COMMON(struct dns_lookupevent);
69	isc_result_t			result;
70	dns_name_t			*name;
71	dns_rdataset_t			*rdataset;
72	dns_rdataset_t			*sigrdataset;
73	dns_db_t			*db;
74	dns_dbnode_t			*node;
75} dns_lookupevent_t;
76
77isc_result_t
78dns_lookup_create(isc_mem_t *mctx, dns_name_t *name, dns_rdatatype_t type,
79		  dns_view_t *view, unsigned int options, isc_task_t *task,
80		  isc_taskaction_t action, void *arg, dns_lookup_t **lookupp);
81/*%<
82 * Finds the rrsets matching 'name' and 'type'.
83 *
84 * Requires:
85 *
86 *\li	'mctx' is a valid mctx.
87 *
88 *\li	'name' is a valid name.
89 *
90 *\li	'view' is a valid view which has a resolver.
91 *
92 *\li	'task' is a valid task.
93 *
94 *\li	lookupp != NULL && *lookupp == NULL
95 *
96 * Returns:
97 *
98 *\li	ISC_R_SUCCESS
99 *\li	ISC_R_NOMEMORY
100 *
101 *\li	Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
102 *	returned.
103 */
104
105void
106dns_lookup_cancel(dns_lookup_t *lookup);
107/*%<
108 * Cancel 'lookup'.
109 *
110 * Notes:
111 *
112 *\li	If 'lookup' has not completed, post its LOOKUPDONE event with a
113 *	result code of ISC_R_CANCELED.
114 *
115 * Requires:
116 *
117 *\li	'lookup' is a valid lookup.
118 */
119
120void
121dns_lookup_destroy(dns_lookup_t **lookupp);
122/*%<
123 * Destroy 'lookup'.
124 *
125 * Requires:
126 *
127 *\li	'*lookupp' is a valid lookup.
128 *
129 *\li	The caller has received the LOOKUPDONE event (either because the
130 *	lookup completed or because dns_lookup_cancel() was called).
131 *
132 * Ensures:
133 *
134 *\li	*lookupp == NULL.
135 */
136
137ISC_LANG_ENDDECLS
138
139#endif /* DNS_LOOKUP_H */
140