Home | History | Annotate | Line # | Download | only in dns 
      1 /*	$NetBSD: lookup.h,v 1.1 2024/02/18 20:57:37 christos Exp $	*/
      2 
      3 /*
      4  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
      5  *
      6  * SPDX-License-Identifier: MPL-2.0
      7  *
      8  * This Source Code Form is subject to the terms of the Mozilla Public
      9  * License, v. 2.0. If a copy of the MPL was not distributed with this
     10  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
     11  *
     12  * See the COPYRIGHT file distributed with this work for additional
     13  * information regarding copyright ownership.
     14  */
     15 
     16 #ifndef DNS_LOOKUP_H
     17 #define DNS_LOOKUP_H 1
     18 
     19 /*****
     20 ***** Module Info
     21 *****/
     22 
     23 /*! \file dns/lookup.h
     24  * \brief
     25  * The lookup module performs simple DNS lookups.  It implements
     26  * the full resolver algorithm, both looking for local data and
     27  * resolving external names as necessary.
     28  *
     29  * MP:
     30  *\li	The module ensures appropriate synchronization of data structures it
     31  *	creates and manipulates.
     32  *
     33  * Reliability:
     34  *\li	No anticipated impact.
     35  *
     36  * Resources:
     37  *\li	TBS
     38  *
     39  * Security:
     40  *\li	No anticipated impact.
     41  *
     42  * Standards:
     43  *\li	RFCs:	1034, 1035, 2181, TBS
     44  *\li	Drafts:	TBS
     45  */
     46 
     47 #include <isc/event.h>
     48 #include <isc/lang.h>
     49 
     50 #include <dns/types.h>
     51 
     52 ISC_LANG_BEGINDECLS
     53 
     54 /*%
     55  * A 'dns_lookupevent_t' is returned when a lookup completes.
     56  * The sender field will be set to the lookup that completed.  If 'result'
     57  * is ISC_R_SUCCESS, then 'names' will contain a list of names associated
     58  * with the address.  The recipient of the event must not change the list
     59  * and must not refer to any of the name data after the event is freed.
     60  */
     61 typedef struct dns_lookupevent {
     62 	ISC_EVENT_COMMON(struct dns_lookupevent);
     63 	isc_result_t	result;
     64 	dns_name_t     *name;
     65 	dns_rdataset_t *rdataset;
     66 	dns_rdataset_t *sigrdataset;
     67 	dns_db_t       *db;
     68 	dns_dbnode_t   *node;
     69 } dns_lookupevent_t;
     70 
     71 isc_result_t
     72 dns_lookup_create(isc_mem_t *mctx, const dns_name_t *name, dns_rdatatype_t type,
     73 		  dns_view_t *view, unsigned int options, isc_task_t *task,
     74 		  isc_taskaction_t action, void *arg, dns_lookup_t **lookupp);
     75 /*%<
     76  * Finds the rrsets matching 'name' and 'type'.
     77  *
     78  * Requires:
     79  *
     80  *\li	'mctx' is a valid mctx.
     81  *
     82  *\li	'name' is a valid name.
     83  *
     84  *\li	'view' is a valid view which has a resolver.
     85  *
     86  *\li	'task' is a valid task.
     87  *
     88  *\li	lookupp != NULL && *lookupp == NULL
     89  *
     90  * Returns:
     91  *
     92  *\li	ISC_R_SUCCESS
     93  *\li	ISC_R_NOMEMORY
     94  *
     95  *\li	Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be
     96  *	returned.
     97  */
     98 
     99 void
    100 dns_lookup_cancel(dns_lookup_t *lookup);
    101 /*%<
    102  * Cancel 'lookup'.
    103  *
    104  * Notes:
    105  *
    106  *\li	If 'lookup' has not completed, post its LOOKUPDONE event with a
    107  *	result code of ISC_R_CANCELED.
    108  *
    109  * Requires:
    110  *
    111  *\li	'lookup' is a valid lookup.
    112  */
    113 
    114 void
    115 dns_lookup_destroy(dns_lookup_t **lookupp);
    116 /*%<
    117  * Destroy 'lookup'.
    118  *
    119  * Requires:
    120  *
    121  *\li	'*lookupp' is a valid lookup.
    122  *
    123  *\li	The caller has received the LOOKUPDONE event (either because the
    124  *	lookup completed or because dns_lookup_cancel() was called).
    125  *
    126  * Ensures:
    127  *
    128  *\li	*lookupp == NULL.
    129  */
    130 
    131 ISC_LANG_ENDDECLS
    132 
    133 #endif /* DNS_LOOKUP_H */
    134