contrib/bind-9.5.2/lib/dns/include/dns/byaddr.h

   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
  55 ISC_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  */
  64 typedef 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
  77 isc_result_t
  78 dns_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
 117 void
 118 dns_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
 132 void
 133 dns_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
 149 isc_result_t
 150 dns_byaddr_createptrname(isc_netaddr_t *address, isc_boolean_t nibble,
 151                          dns_name_t *name);
 152
 153 isc_result_t
 154 dns_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
 169 ISC_LANG_ENDDECLS
 170
 171 #endif /* DNS_BYADDR_H */