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

   1 /*
   2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  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: lookup.h,v 1.12.128.2 2009/01/19 23:47:03 tbox Exp $ */
  19
  20 #ifndef DNS_LOOKUP_H
  21 #define DNS_LOOKUP_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/lookup.h
  28  * \brief
  29  * The lookup module performs simple DNS lookups.  It implements
  30  * the full resolver algorithm, both looking for local data and
  31  * resolving external names as necessary.
  32  *
  33  * MP:
  34  *\li   The module ensures appropriate synchronization of data structures it
  35  *      creates and manipulates.
  36  *
  37  * Reliability:
  38  *\li   No anticipated impact.
  39  *
  40  * Resources:
  41  *\li   TBS
  42  *
  43  * Security:
  44  *\li   No anticipated impact.
  45  *
  46  * Standards:
  47  *\li   RFCs:   1034, 1035, 2181, TBS
  48  *\li   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_lookupevent_t' is returned when a lookup completes.
  60  * The sender field will be set to the lookup 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_lookupevent {
  66         ISC_EVENT_COMMON(struct dns_lookupevent);
  67         isc_result_t                    result;
  68         dns_name_t                      *name;
  69         dns_rdataset_t                  *rdataset;
  70         dns_rdataset_t                  *sigrdataset;
  71         dns_db_t                        *db;
  72         dns_dbnode_t                    *node;
  73 } dns_lookupevent_t;
  74
  75 isc_result_t
  76 dns_lookup_create(isc_mem_t *mctx, dns_name_t *name, dns_rdatatype_t type,
  77                   dns_view_t *view, unsigned int options, isc_task_t *task,
  78                   isc_taskaction_t action, void *arg, dns_lookup_t **lookupp);
  79 /*%<
  80  * Finds the rrsets matching 'name' and 'type'.
  81  *
  82  * Requires:
  83  *
  84  *\li   'mctx' is a valid mctx.
  85  *
  86  *\li   'name' is a valid name.
  87  *
  88  *\li   'view' is a valid view which has a resolver.
  89  *
  90  *\li   'task' is a valid task.
  91  *
  92  *\li   lookupp != NULL && *lookupp == NULL
  93  *
  94  * Returns:
  95  *
  96  *\li   ISC_R_SUCCESS
  97  *\li   ISC_R_NOMEMORY
  98  *
  99  *\li   Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
 100  *      returned.
 101  */
 102
 103 void
 104 dns_lookup_cancel(dns_lookup_t *lookup);
 105 /*%<
 106  * Cancel 'lookup'.
 107  *
 108  * Notes:
 109  *
 110  *\li   If 'lookup' has not completed, post its LOOKUPDONE event with a
 111  *      result code of ISC_R_CANCELED.
 112  *
 113  * Requires:
 114  *
 115  *\li   'lookup' is a valid lookup.
 116  */
 117
 118 void
 119 dns_lookup_destroy(dns_lookup_t **lookupp);
 120 /*%<
 121  * Destroy 'lookup'.
 122  *
 123  * Requires:
 124  *
 125  *\li   '*lookupp' is a valid lookup.
 126  *
 127  *\li   The caller has received the LOOKUPDONE event (either because the
 128  *      lookup completed or because dns_lookup_cancel() was called).
 129  *
 130  * Ensures:
 131  *
 132  *\li   *lookupp == NULL.
 133  */
 134
 135 ISC_LANG_ENDDECLS
 136
 137 #endif /* DNS_LOOKUP_H */