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