contrib/bind-9.2.4rc7/lib/dns/include/dns/byaddr.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001, 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.3 2004/03/09 06:11:13 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 #define DNS_BYADDROPT_IPV6NIBBLE        0x0001
  72 #define DNS_BYADDROPT_IPV6INT           0x0002  /* Use IP6.INT nibble lookups */
  73
  74 isc_result_t
  75 dns_byaddr_create(isc_mem_t *mctx, isc_netaddr_t *address, dns_view_t *view,
  76                   unsigned int options, isc_task_t *task,
  77                   isc_taskaction_t action, void *arg, dns_byaddr_t **byaddrp);
  78 /*
  79  * Find the domain name of 'address'.
  80  *
  81  * Notes:
  82  *
  83  *      There is a reverse lookup format for IPv6 addresses, 'nibble'
  84  *
  85  *      The 'nibble' format for that address is
  86  *
  87  *   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.
  88  *
  89  *      DNS_BYADDROPT_IPV6INT can be used to get nibble lookups under ip6.int.
  90  *
  91  * Requires:
  92  *
  93  *      'mctx' is a valid mctx.
  94  *
  95  *      'address' is a valid IPv4 or IPv6 address.
  96  *
  97  *      'view' is a valid view which has a resolver.
  98  *
  99  *      'task' is a valid task.
 100  *
 101  *      byaddrp != NULL && *byaddrp == NULL
 102  *
 103  * Returns:
 104  *
 105  *      ISC_R_SUCCESS
 106  *      ISC_R_NOMEMORY
 107  *
 108  *      Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
 109  *      returned.
 110  */
 111
 112 void
 113 dns_byaddr_cancel(dns_byaddr_t *byaddr);
 114 /*
 115  * Cancel 'byaddr'.
 116  *
 117  * Notes:
 118  *
 119  *      If 'byaddr' has not completed, post its BYADDRDONE event with a
 120  *      result code of ISC_R_CANCELED.
 121  *
 122  * Requires:
 123  *
 124  *      'byaddr' is a valid byaddr.
 125  */
 126
 127 void
 128 dns_byaddr_destroy(dns_byaddr_t **byaddrp);
 129 /*
 130  * Destroy 'byaddr'.
 131  *
 132  * Requires:
 133  *
 134  *      '*byaddrp' is a valid byaddr.
 135  *
 136  *      The caller has received the BYADDRDONE event (either because the
 137  *      byaddr completed or because dns_byaddr_cancel() was called).
 138  *
 139  * Ensures:
 140  *
 141  *      *byaddrp == NULL.
 142  */
 143
 144 isc_result_t
 145 dns_byaddr_createptrname(isc_netaddr_t *address, isc_boolean_t nibble,
 146                          dns_name_t *name);
 147
 148 isc_result_t
 149 dns_byaddr_createptrname2(isc_netaddr_t *address, unsigned int options,
 150                           dns_name_t *name);
 151 /*
 152  * Creates a name that would be used in a PTR query for this address.  The
 153  * nibble flag indicates that the 'nibble' format is to be used if an IPv6
 154  * address is provided, instead of the 'bitstring' format.  'options' are
 155  * the same as for dns_byaddr_create().
 156  *
 157  * Requires:
 158  *
 159  *      'address' is a valid address.
 160  *      'name' is a valid name with a dedicated buffer.
 161  */
 162
 163 ISC_LANG_ENDDECLS
 164
 165 #endif /* DNS_BYADDR_H */