lookup.h revision 135446 
1/*
2 * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and 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.5.206.1 2004/03/06 08:13:57 marka Exp $ */
19
20#ifndef DNS_LOOKUP_H
21#define DNS_LOOKUP_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*
28 * DNS Lookup
29 *
30 * The lookup module performs simple DNS lookups.  It implements
31 * the full resolver algorithm, both looking for local data and
32 * resoving external names as necessary.
33 *
34 * MP:
35 *	The module ensures appropriate synchronization of data structures it
36 *	creates and manipulates.
37 *
38 * Reliability:
39 *	No anticipated impact.
40 *
41 * Resources:
42 *	<TBS>
43 *
44 * Security:
45 *	No anticipated impact.
46 *
47 * Standards:
48 *	RFCs:	1034, 1035, 2181, <TBS>
49 *	Drafts:	<TBS>
50 */
51
52#include <isc/lang.h>
53#include <isc/event.h>
54
55#include <dns/types.h>
56
57ISC_LANG_BEGINDECLS
58
59/*
60 * A 'dns_lookupevent_t' is returned when a lookup completes.
61 * The sender field will be set to the lookup that completed.  If 'result'
62 * is ISC_R_SUCCESS, then 'names' will contain a list of names associated
63 * with the address.  The recipient of the event must not change the list
64 * and must not refer to any of the name data after the event is freed.
65 */
66typedef struct dns_lookupevent {
67	ISC_EVENT_COMMON(struct dns_lookupevent);
68	isc_result_t			result;
69	dns_name_t			*name;
70	dns_rdataset_t			*rdataset;
71	dns_rdataset_t			*sigrdataset;
72	dns_db_t			*db;
73	dns_dbnode_t			*node;
74} dns_lookupevent_t;
75
76isc_result_t
77dns_lookup_create(isc_mem_t *mctx, dns_name_t *name, dns_rdatatype_t type,
78		  dns_view_t *view, unsigned int options, isc_task_t *task,
79		  isc_taskaction_t action, void *arg, dns_lookup_t **lookupp);
80/*
81 * Finds the rrsets matching 'name' and 'type'.
82 *
83 * Requires:
84 *
85 *	'mctx' is a valid mctx.
86 *
87 *	'name' is a valid name.
88 *
89 *	'view' is a valid view which has a resolver.
90 *
91 *	'task' is a valid task.
92 *
93 *	lookupp != NULL && *lookupp == NULL
94 *
95 * Returns:
96 *
97 *	ISC_R_SUCCESS
98 *	ISC_R_NOMEMORY
99 *
100 *	Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
101 *	returned.
102 */
103
104void
105dns_lookup_cancel(dns_lookup_t *lookup);
106/*
107 * Cancel 'lookup'.
108 *
109 * Notes:
110 *
111 *	If 'lookup' has not completed, post its LOOKUPDONE event with a
112 *	result code of ISC_R_CANCELED.
113 *
114 * Requires:
115 *
116 *	'lookup' is a valid lookup.
117 */
118
119void
120dns_lookup_destroy(dns_lookup_t **lookupp);
121/*
122 * Destroy 'lookup'.
123 *
124 * Requires:
125 *
126 *	'*lookupp' is a valid lookup.
127 *
128 *	The caller has received the LOOKUPDONE event (either because the
129 *	lookup completed or because dns_lookup_cancel() was called).
130 *
131 * Ensures:
132 *
133 *	*lookupp == NULL.
134 */
135
136ISC_LANG_ENDDECLS
137
138#endif /* DNS_LOOKUP_H */
139