1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #ifndef DNS_BYADDR_H 13 #define DNS_BYADDR_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file dns/byaddr.h 20 * \brief 21 * The byaddr module provides reverse lookup services for IPv4 and IPv6 22 * addresses. 23 * 24 * MP: 25 *\li The module ensures appropriate synchronization of data structures it 26 * creates and manipulates. 27 * 28 * Reliability: 29 *\li No anticipated impact. 30 * 31 * Resources: 32 *\li TBS 33 * 34 * Security: 35 *\li No anticipated impact. 36 * 37 * Standards: 38 *\li RFCs: 1034, 1035, 2181, TBS 39 *\li Drafts: TBS 40 */ 41 42 #include <isc/event.h> 43 #include <isc/lang.h> 44 45 #include <dns/types.h> 46 47 ISC_LANG_BEGINDECLS 48 49 /*% 50 * A 'dns_byaddrevent_t' is returned when a byaddr completes. 51 * The sender field will be set to the byaddr that completed. If 'result' 52 * is ISC_R_SUCCESS, then 'names' will contain a list of names associated 53 * with the address. The recipient of the event must not change the list 54 * and must not refer to any of the name data after the event is freed. 55 */ 56 typedef struct dns_byaddrevent { 57 ISC_EVENT_COMMON(struct dns_byaddrevent); 58 isc_result_t result; 59 dns_namelist_t names; 60 } dns_byaddrevent_t; 61 62 isc_result_t 63 dns_byaddr_create(isc_mem_t *mctx, const isc_netaddr_t *address, 64 dns_view_t *view, unsigned int options, isc_task_t *task, 65 isc_taskaction_t action, void *arg, dns_byaddr_t **byaddrp); 66 /*%< 67 * Find the domain name of 'address'. 68 * 69 * Notes: 70 * 71 *\li There is a reverse lookup format for IPv6 addresses, 'nibble' 72 * 73 *\li The 'nibble' format for that address is 74 * 75 * \code 76 * 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. 77 * \endcode 78 * 79 * Requires: 80 * 81 *\li 'mctx' is a valid mctx. 82 * 83 *\li 'address' is a valid IPv4 or IPv6 address. 84 * 85 *\li 'view' is a valid view which has a resolver. 86 * 87 *\li 'task' is a valid task. 88 * 89 *\li byaddrp != NULL && *byaddrp == NULL 90 * 91 * Returns: 92 * 93 *\li #ISC_R_SUCCESS 94 *\li #ISC_R_NOMEMORY 95 * 96 *\li Any resolver-related error (e.g. #ISC_R_SHUTTINGDOWN) may also be 97 * returned. 98 */ 99 100 void 101 dns_byaddr_cancel(dns_byaddr_t *byaddr); 102 /*%< 103 * Cancel 'byaddr'. 104 * 105 * Notes: 106 * 107 *\li If 'byaddr' has not completed, post its #DNS_EVENT_BYADDRDONE 108 * event with a result code of #ISC_R_CANCELED. 109 * 110 * Requires: 111 * 112 *\li 'byaddr' is a valid byaddr. 113 */ 114 115 void 116 dns_byaddr_destroy(dns_byaddr_t **byaddrp); 117 /*%< 118 * Destroy 'byaddr'. 119 * 120 * Requires: 121 * 122 *\li '*byaddrp' is a valid byaddr. 123 * 124 *\li The caller has received the #DNS_EVENT_BYADDRDONE event (either because 125 * the byaddr completed or because dns_byaddr_cancel() was called). 126 * 127 * Ensures: 128 * 129 *\li *byaddrp == NULL. 130 */ 131 132 isc_result_t 133 dns_byaddr_createptrname(const isc_netaddr_t *address, unsigned int options, 134 dns_name_t *name); 135 /*%< 136 * Creates a name that would be used in a PTR query for this address. The 137 * nibble flag indicates that the 'nibble' format is to be used if an IPv6 138 * address is provided, instead of the 'bitstring' format. Since we dropped 139 * the support of the bitstring labels, it is expected that the flag is always 140 * set. 'options' are the same as for dns_byaddr_create(). 141 * 142 * Requires: 143 * 144 * \li 'address' is a valid address. 145 * \li 'name' is a valid name with a dedicated buffer. 146 */ 147 148 ISC_LANG_ENDDECLS 149 150 #endif /* DNS_BYADDR_H */ 151