1/*
2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000-2003  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: byaddr.h,v 1.22 2007/06/19 23:47:16 tbox Exp $ */
19
20#ifndef DNS_BYADDR_H
21#define DNS_BYADDR_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file dns/byaddr.h
28 * \brief
29 * The byaddr module provides reverse lookup services for IPv4 and IPv6
30 * addresses.
31 *
32 * MP:
33 *\li	The module ensures appropriate synchronization of data structures it
34 *	creates and manipulates.
35 *
36 * Reliability:
37 *\li	No anticipated impact.
38 *
39 * Resources:
40 *\li	TBS
41 *
42 * Security:
43 *\li	No anticipated impact.
44 *
45 * Standards:
46 *\li	RFCs:	1034, 1035, 2181, TBS
47 *\li	Drafts:	TBS
48 */
49
50#include <isc/lang.h>
51#include <isc/event.h>
52
53#include <dns/types.h>
54
55ISC_LANG_BEGINDECLS
56
57/*%
58 * A 'dns_byaddrevent_t' is returned when a byaddr completes.
59 * The sender field will be set to the byaddr that completed.  If 'result'
60 * is ISC_R_SUCCESS, then 'names' will contain a list of names associated
61 * with the address.  The recipient of the event must not change the list
62 * and must not refer to any of the name data after the event is freed.
63 */
64typedef struct dns_byaddrevent {
65	ISC_EVENT_COMMON(struct dns_byaddrevent);
66	isc_result_t			result;
67	dns_namelist_t			names;
68} dns_byaddrevent_t;
69
70/*
71 * This option is deprecated since we now only consider nibbles.
72#define DNS_BYADDROPT_IPV6NIBBLE	0x0001
73 */
74/*% Note DNS_BYADDROPT_IPV6NIBBLE is now deprecated. */
75#define DNS_BYADDROPT_IPV6INT		0x0002
76
77isc_result_t
78dns_byaddr_create(isc_mem_t *mctx, isc_netaddr_t *address, dns_view_t *view,
79		  unsigned int options, isc_task_t *task,
80		  isc_taskaction_t action, void *arg, dns_byaddr_t **byaddrp);
81/*%<
82 * Find the domain name of 'address'.
83 *
84 * Notes:
85 *
86 *\li	There is a reverse lookup format for IPv6 addresses, 'nibble'
87 *
88 *\li	The 'nibble' format for that address is
89 *
90 * \code
91 *   1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f.ip6.arpa.
92 * \endcode
93 *
94 *\li	#DNS_BYADDROPT_IPV6INT can be used to get nibble lookups under ip6.int.
95 *
96 * Requires:
97 *
98 *\li	'mctx' is a valid mctx.
99 *
100 *\li	'address' is a valid IPv4 or IPv6 address.
101 *
102 *\li	'view' is a valid view which has a resolver.
103 *
104 *\li	'task' is a valid task.
105 *
106 *\li	byaddrp != NULL && *byaddrp == NULL
107 *
108 * Returns:
109 *
110 *\li	#ISC_R_SUCCESS
111 *\li	#ISC_R_NOMEMORY
112 *
113 *\li	Any resolver-related error (e.g. #ISC_R_SHUTTINGDOWN) may also be
114 *	returned.
115 */
116
117void
118dns_byaddr_cancel(dns_byaddr_t *byaddr);
119/*%<
120 * Cancel 'byaddr'.
121 *
122 * Notes:
123 *
124 *\li	If 'byaddr' has not completed, post its #DNS_EVENT_BYADDRDONE
125 *	event with a result code of #ISC_R_CANCELED.
126 *
127 * Requires:
128 *
129 *\li	'byaddr' is a valid byaddr.
130 */
131
132void
133dns_byaddr_destroy(dns_byaddr_t **byaddrp);
134/*%<
135 * Destroy 'byaddr'.
136 *
137 * Requires:
138 *
139 *\li	'*byaddrp' is a valid byaddr.
140 *
141 *\li	The caller has received the #DNS_EVENT_BYADDRDONE event (either because
142 *	the byaddr completed or because dns_byaddr_cancel() was called).
143 *
144 * Ensures:
145 *
146 *\li	*byaddrp == NULL.
147 */
148
149isc_result_t
150dns_byaddr_createptrname(isc_netaddr_t *address, isc_boolean_t nibble,
151			 dns_name_t *name);
152
153isc_result_t
154dns_byaddr_createptrname2(isc_netaddr_t *address, unsigned int options,
155			  dns_name_t *name);
156/*%<
157 * Creates a name that would be used in a PTR query for this address.  The
158 * nibble flag indicates that the 'nibble' format is to be used if an IPv6
159 * address is provided, instead of the 'bitstring' format.  Since we dropped
160 * the support of the bitstring labels, it is expected that the flag is always
161 * set.  'options' are the same as for dns_byaddr_create().
162 *
163 * Requires:
164 *
165 * \li	'address' is a valid address.
166 * \li	'name' is a valid name with a dedicated buffer.
167 */
168
169ISC_LANG_ENDDECLS
170
171#endif /* DNS_BYADDR_H */
172