/contrib/bind9/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.14 2009/01/17 23:47:43 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
 56ISC_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 */
 65typedef 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
 75isc_result_t
 76dns_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
103void
104dns_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
118void
119dns_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
135ISC_LANG_ENDDECLS
136
137#endif /* DNS_LOOKUP_H */