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

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