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

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  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: resolver.h,v 1.34.2.1 2004/03/09 06:11:21 marka Exp $ */
  19
  20 #ifndef DNS_RESOLVER_H
  21 #define DNS_RESOLVER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * DNS Resolver
  29  *
  30  * This is the BIND 9 resolver, the module responsible for resolving DNS
  31  * requests by iteratively querying authoritative servers and following
  32  * referrals.  This is a "full resolver", not to be confused with
  33  * the stub resolvers most people associate with the word "resolver".
  34  * The full resolver is part of the caching name server or resolver
  35  * daemon the stub resolver talks to.
  36  *
  37  * MP:
  38  *      The module ensures appropriate synchronization of data structures it
  39  *      creates and manipulates.
  40  *
  41  * Reliability:
  42  *      No anticipated impact.
  43  *
  44  * Resources:
  45  *      <TBS>
  46  *
  47  * Security:
  48  *      No anticipated impact.
  49  *
  50  * Standards:
  51  *      RFCs:   1034, 1035, 2181, <TBS>
  52  *      Drafts: <TBS>
  53  */
  54
  55 #include <isc/lang.h>
  56 #include <isc/socket.h>
  57
  58 #include <dns/types.h>
  59 #include <dns/fixedname.h>
  60
  61 ISC_LANG_BEGINDECLS
  62
  63 /*
  64  * A dns_fetchevent_t is sent when a 'fetch' completes.  Any of 'db',
  65  * 'node', 'rdataset', and 'sigrdataset' may be bound.  It is the
  66  * receiver's responsibility to detach before freeing the event.
  67  *
  68  * 'rdataset' and 'sigrdataset' are the values that were supplied when
  69  * dns_resolver_createfetch() was called.  They are returned to the
  70  * caller so that they may be freed.
  71  */
  72 typedef struct dns_fetchevent {
  73         ISC_EVENT_COMMON(struct dns_fetchevent);
  74         dns_fetch_t *                   fetch;
  75         isc_result_t                    result;
  76         dns_rdatatype_t                 qtype;
  77         dns_db_t *                      db;
  78         dns_dbnode_t *                  node;
  79         dns_rdataset_t *                rdataset;
  80         dns_rdataset_t *                sigrdataset;
  81         dns_fixedname_t                 foundname;
  82 } dns_fetchevent_t;
  83
  84 /*
  85  * Options that modify how a 'fetch' is done.
  86  */
  87 #define DNS_FETCHOPT_TCP                0x01         /* Use TCP. */
  88 #define DNS_FETCHOPT_UNSHARED           0x02         /* See below. */
  89 #define DNS_FETCHOPT_RECURSIVE          0x04         /* Set RD? */
  90 #define DNS_FETCHOPT_NOEDNS0            0x08         /* Do not use EDNS. */
  91 #define DNS_FETCHOPT_FORWARDONLY        0x10         /* Only use forwarders. */
  92 #define DNS_FETCHOPT_NOVALIDATE         0x20         /* Disable validation. */
  93
  94 /*
  95  * XXXRTH  Should this API be made semi-private?  (I.e.
  96  * _dns_resolver_create()).
  97  */
  98
  99 isc_result_t
 100 dns_resolver_create(dns_view_t *view,
 101                     isc_taskmgr_t *taskmgr, unsigned int ntasks,
 102                     isc_socketmgr_t *socketmgr,
 103                     isc_timermgr_t *timermgr,
 104                     unsigned int options,
 105                     dns_dispatchmgr_t *dispatchmgr,
 106                     dns_dispatch_t *dispatchv4,
 107                     dns_dispatch_t *dispatchv6,
 108                     dns_resolver_t **resp);
 109 /*
 110  * Create a resolver.
 111  *
 112  * Notes:
 113  *
 114  *      Generally, applications should not create a resolver directly, but
 115  *      should instead call dns_view_createresolver().
 116  *
 117  *      No options are currently defined.
 118  *
 119  * Requires:
 120  *
 121  *      'view' is a valid view.
 122  *
 123  *      'taskmgr' is a valid task manager.
 124  *
 125  *      'ntasks' > 0.
 126  *
 127  *      'socketmgr' is a valid socket manager.
 128  *
 129  *      'timermgr' is a valid timer manager.
 130  *
 131  *      'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
 132  *
 133  *      'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
 134  *
 135  *      *resp != NULL && *resp == NULL.
 136  *
 137  * Returns:
 138  *
 139  *      ISC_R_SUCCESS                           On success.
 140  *
 141  *      Anything else                           Failure.
 142  */
 143
 144 void
 145 dns_resolver_freeze(dns_resolver_t *res);
 146 /*
 147  * Freeze resolver.
 148  *
 149  * Notes:
 150  *
 151  *      Certain configuration changes cannot be made after the resolver
 152  *      is frozen.  Fetches cannot be created until the resolver is frozen.
 153  *
 154  * Requires:
 155  *
 156  *      'res' is a valid, unfrozen resolver.
 157  *
 158  * Ensures:
 159  *
 160  *      'res' is frozen.
 161  */
 162
 163 void
 164 dns_resolver_prime(dns_resolver_t *res);
 165 /*
 166  * Prime resolver.
 167  *
 168  * Notes:
 169  *
 170  *      Resolvers which have a forwarding policy other than dns_fwdpolicy_only
 171  *      need to be primed with the root nameservers, otherwise the root
 172  *      nameserver hints data may be used indefinitely.  This function requests
 173  *      that the resolver start a priming fetch, if it isn't already priming.
 174  *
 175  * Requires:
 176  *
 177  *      'res' is a valid, frozen resolver.
 178  */
 179
 180
 181 void
 182 dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
 183                           isc_event_t **eventp);
 184 /*
 185  * Send '*eventp' to 'task' when 'res' has completed shutdown.
 186  *
 187  * Notes:
 188  *
 189  *      It is not safe to detach the last reference to 'res' until
 190  *      shutdown is complete.
 191  *
 192  * Requires:
 193  *
 194  *      'res' is a valid resolver.
 195  *
 196  *      'task' is a valid task.
 197  *
 198  *      *eventp is a valid event.
 199  *
 200  * Ensures:
 201  *
 202  *      *eventp == NULL.
 203  */
 204
 205 void
 206 dns_resolver_shutdown(dns_resolver_t *res);
 207 /*
 208  * Start the shutdown process for 'res'.
 209  *
 210  * Notes:
 211  *
 212  *      This call has no effect if the resolver is already shutting down.
 213  *
 214  * Requires:
 215  *
 216  *      'res' is a valid resolver.
 217  */
 218
 219 void
 220 dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
 221
 222 void
 223 dns_resolver_detach(dns_resolver_t **resp);
 224
 225 isc_result_t
 226 dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
 227                          dns_rdatatype_t type,
 228                          dns_name_t *domain, dns_rdataset_t *nameservers,
 229                          dns_forwarders_t *forwarders,
 230                          unsigned int options, isc_task_t *task,
 231                          isc_taskaction_t action, void *arg,
 232                          dns_rdataset_t *rdataset,
 233                          dns_rdataset_t *sigrdataset,
 234                          dns_fetch_t **fetchp);
 235 /*
 236  * Recurse to answer a question.
 237  *
 238  * Notes:
 239  *
 240  *      This call starts a query for 'name', type 'type'.
 241  *
 242  *      The 'domain' is a parent domain of 'name' for which
 243  *      a set of name servers 'nameservers' is known.  If no
 244  *      such name server information is available, set
 245  *      'domain' and 'nameservers' to NULL.
 246  *
 247  *      'forwarders' is unimplemented, and subject to change when
 248  *      we figure out how selective forwarding will work.
 249  *
 250  *      When the fetch completes (successfully or otherwise), a
 251  *      DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
 252  *      posted to 'task'.
 253  *
 254  *      The values of 'rdataset' and 'sigrdataset' will be returned in
 255  *      the FETCHDONE event.
 256  *
 257  * Requires:
 258  *
 259  *      'res' is a valid resolver that has been frozen.
 260  *
 261  *      'name' is a valid name.
 262  *
 263  *      'type' is not a meta type other than ANY.
 264  *
 265  *      'domain' is a valid name or NULL.
 266  *
 267  *      'nameservers' is a valid NS rdataset (whose owner name is 'domain')
 268  *      iff. 'domain' is not NULL.
 269  *
 270  *      'forwarders' is NULL.
 271  *
 272  *      'options' contains valid options.
 273  *
 274  *      'rdataset' is a valid, disassociated rdataset.
 275  *
 276  *      'sigrdataset' is NULL, or is a valid, disassociated rdataset.
 277  *
 278  *      fetchp != NULL && *fetchp == NULL.
 279  *
 280  * Returns:
 281  *
 282  *      ISC_R_SUCCESS                                   Success
 283  *
 284  *      Many other values are possible, all of which indicate failure.
 285  */
 286
 287 void
 288 dns_resolver_cancelfetch(dns_fetch_t *fetch);
 289 /*
 290  * Cancel 'fetch'.
 291  *
 292  * Notes:
 293  *
 294  *      If 'fetch' has not completed, post its FETCHDONE event with a
 295  *      result code of ISC_R_CANCELED.
 296  *
 297  * Requires:
 298  *
 299  *      'fetch' is a valid fetch.
 300  */
 301
 302 void
 303 dns_resolver_destroyfetch(dns_fetch_t **fetchp);
 304 /*
 305  * Destroy 'fetch'.
 306  *
 307  * Requires:
 308  *
 309  *      '*fetchp' is a valid fetch.
 310  *
 311  *      The caller has received the FETCHDONE event (either because the
 312  *      fetch completed or because dns_resolver_cancelfetch() was called).
 313  *
 314  * Ensures:
 315  *
 316  *      *fetchp == NULL.
 317  */
 318
 319 dns_dispatchmgr_t *
 320 dns_resolver_dispatchmgr(dns_resolver_t *resolver);
 321
 322 dns_dispatch_t *
 323 dns_resolver_dispatchv4(dns_resolver_t *resolver);
 324
 325 dns_dispatch_t *
 326 dns_resolver_dispatchv6(dns_resolver_t *resolver);
 327
 328 isc_socketmgr_t *
 329 dns_resolver_socketmgr(dns_resolver_t *resolver);
 330
 331 isc_taskmgr_t *
 332 dns_resolver_taskmgr(dns_resolver_t *resolver);
 333
 334 isc_uint32_t
 335 dns_resolver_getlamettl(dns_resolver_t *resolver);
 336 /*
 337  * Get the resolver's lame-ttl.  zero => no lame processing.
 338  *
 339  * Requires:
 340  *      'resolver' to be valid.
 341  */
 342
 343 void
 344 dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
 345 /*
 346  * Set the resolver's lame-ttl.  zero => no lame processing.
 347  *
 348  * Requires:
 349  *      'resolver' to be valid.
 350  */
 351
 352 ISC_LANG_ENDDECLS
 353
 354 #endif /* DNS_RESOLVER_H */