/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef DNS_ADB_H

[12] Fix | Delete

#define DNS_ADB_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file dns/adb.h

[19] Fix | Delete

*\brief

[20] Fix | Delete

* DNS Address Database

[21] Fix | Delete

*

[22] Fix | Delete

* This module implements an address database (ADB) for mapping a name

[23] Fix | Delete

* to an isc_sockaddr_t. It also provides statistical information on

[24] Fix | Delete

* how good that address might be.

[25] Fix | Delete

*

[26] Fix | Delete

* A client will pass in a dns_name_t, and the ADB will walk through

[27] Fix | Delete

* the rdataset looking up addresses associated with the name. If it

[28] Fix | Delete

* is found on the internal lists, a structure is filled in with the

[29] Fix | Delete

* address information and stats for found addresses.

[30] Fix | Delete

*

[31] Fix | Delete

* If the name cannot be found on the internal lists, a new entry will

[32] Fix | Delete

* be created for a name if all the information needed can be found

[33] Fix | Delete

* in the zone table or cache. This new address will then be returned.

[34] Fix | Delete

*

[35] Fix | Delete

* If a request must be made to remote servers to satisfy a name lookup,

[36] Fix | Delete

* this module will start fetches to try to complete these addresses. When

[37] Fix | Delete

* at least one more completes, an event is sent to the caller. If none of

[38] Fix | Delete

* them resolve before the fetch times out, an event indicating this is

[39] Fix | Delete

* sent instead.

[40] Fix | Delete

*

[41] Fix | Delete

* Records are stored internally until a timer expires. The timer is the

[42] Fix | Delete

* smaller of the TTL or signature validity period.

[43] Fix | Delete

*

[44] Fix | Delete

* Lameness is stored per <qname,qtype> tuple, and this data hangs off each

[45] Fix | Delete

* address field. When an address is marked lame for a given tuple the address

[46] Fix | Delete

* will not be returned to a caller.

[47] Fix | Delete

*

[48] Fix | Delete

*

[49] Fix | Delete

* MP:

[50] Fix | Delete

*

[51] Fix | Delete

*\li The ADB takes care of all necessary locking.

[52] Fix | Delete

*

[53] Fix | Delete

*\li Only the task which initiated the name lookup can cancel the lookup.

[54] Fix | Delete

*

[55] Fix | Delete

*

[56] Fix | Delete

* Security:

[57] Fix | Delete

*

[58] Fix | Delete

*\li None, since all data stored is required to be pre-filtered.

[59] Fix | Delete

* (Cache needs to be sane, fetches return bounds-checked and sanity-

[60] Fix | Delete

* checked data, caller passes a good dns_name_t for the zone, etc)

[61] Fix | Delete

*/

[62] Fix | Delete

[63] Fix | Delete

/***

[64] Fix | Delete

*** Imports

[65] Fix | Delete

***/

[66] Fix | Delete

[67] Fix | Delete

#include <inttypes.h>

[68] Fix | Delete

#include <stdbool.h>

[69] Fix | Delete

[70] Fix | Delete

#include <isc/lang.h>

[71] Fix | Delete

#include <isc/magic.h>

[72] Fix | Delete

#include <isc/mem.h>

[73] Fix | Delete

#include <isc/sockaddr.h>

[74] Fix | Delete

[75] Fix | Delete

#include <dns/types.h>

[76] Fix | Delete

#include <dns/view.h>

[77] Fix | Delete

[78] Fix | Delete

ISC_LANG_BEGINDECLS

[79] Fix | Delete

[80] Fix | Delete

/***

[81] Fix | Delete

*** Magic number checks

[82] Fix | Delete

***/

[83] Fix | Delete

[84] Fix | Delete

#define DNS_ADBFIND_MAGIC ISC_MAGIC('a','d','b','H')

[85] Fix | Delete

#define DNS_ADBFIND_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBFIND_MAGIC)

[86] Fix | Delete

#define DNS_ADBADDRINFO_MAGIC ISC_MAGIC('a','d','A','I')

[87] Fix | Delete

#define DNS_ADBADDRINFO_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBADDRINFO_MAGIC)

[88] Fix | Delete

[89] Fix | Delete

[90] Fix | Delete

/***

[91] Fix | Delete

*** TYPES

[92] Fix | Delete

***/

[93] Fix | Delete

[94] Fix | Delete

typedef struct dns_adbname dns_adbname_t;

[95] Fix | Delete

[96] Fix | Delete

/*!

[97] Fix | Delete

*\brief

[98] Fix | Delete

* Represents a lookup for a single name.

[99] Fix | Delete

*

[100] Fix | Delete

* On return, the client can safely use "list", and can reorder the list.

[101] Fix | Delete

* Items may not be _deleted_ from this list, however, or added to it

[102] Fix | Delete

* other than by using the dns_adb_*() API.

[103] Fix | Delete

*/

[104] Fix | Delete

struct dns_adbfind {

[105] Fix | Delete

/* Public */

[106] Fix | Delete

unsigned int magic; /*%< RO: magic */

[107] Fix | Delete

dns_adbaddrinfolist_t list; /*%< RO: list of addrs */

[108] Fix | Delete

unsigned int query_pending; /*%< RO: partial list */

[109] Fix | Delete

unsigned int partial_result; /*%< RO: addrs missing */

[110] Fix | Delete

unsigned int options; /*%< RO: options */

[111] Fix | Delete

isc_result_t result_v4; /*%< RO: v4 result */

[112] Fix | Delete

isc_result_t result_v6; /*%< RO: v6 result */

[113] Fix | Delete

ISC_LINK(dns_adbfind_t) publink; /*%< RW: client use */

[114] Fix | Delete

[115] Fix | Delete

/* Private */

[116] Fix | Delete

isc_mutex_t lock; /* locks all below */

[117] Fix | Delete

in_port_t port;

[118] Fix | Delete

int name_bucket;

[119] Fix | Delete

unsigned int flags;

[120] Fix | Delete

dns_adbname_t *adbname;

[121] Fix | Delete

dns_adb_t *adb;

[122] Fix | Delete

isc_event_t event;

[123] Fix | Delete

ISC_LINK(dns_adbfind_t) plink;

[124] Fix | Delete

};

[125] Fix | Delete

[126] Fix | Delete

/*

[127] Fix | Delete

* _INET:

[128] Fix | Delete

* _INET6:

[129] Fix | Delete

* return addresses of that type.

[130] Fix | Delete

*

[131] Fix | Delete

* _EMPTYEVENT:

[132] Fix | Delete

* Only schedule an event if no addresses are known.

[133] Fix | Delete

* Must set _WANTEVENT for this to be meaningful.

[134] Fix | Delete

*

[135] Fix | Delete

* _WANTEVENT:

[136] Fix | Delete

* An event is desired. Check this bit in the returned find to see

[137] Fix | Delete

* if one will actually be generated.

[138] Fix | Delete

*

[139] Fix | Delete

* _AVOIDFETCHES:

[140] Fix | Delete

* If set, fetches will not be generated unless no addresses are

[141] Fix | Delete

* available in any of the address families requested.

[142] Fix | Delete

*

[143] Fix | Delete

* _STARTATZONE:

[144] Fix | Delete

* Fetches will start using the closest zone data or use the root servers.

[145] Fix | Delete

* This is useful for reestablishing glue that has expired.

[146] Fix | Delete

*

[147] Fix | Delete

* _GLUEOK:

[148] Fix | Delete

* _HINTOK:

[149] Fix | Delete

* Glue or hints are ok. These are used when matching names already

[150] Fix | Delete

* in the adb, and when dns databases are searched.

[151] Fix | Delete

*

[152] Fix | Delete

* _RETURNLAME:

[153] Fix | Delete

* Return lame servers in a find, so that all addresses are returned.

[154] Fix | Delete

*

[155] Fix | Delete

* _LAMEPRUNED:

[156] Fix | Delete

* At least one address was omitted from the list because it was lame.

[157] Fix | Delete

* This bit will NEVER be set if _RETURNLAME is set in the createfind().

[158] Fix | Delete

*/

[159] Fix | Delete

/*% Return addresses of type INET. */

[160] Fix | Delete

#define DNS_ADBFIND_INET 0x00000001

[161] Fix | Delete

/*% Return addresses of type INET6. */

[162] Fix | Delete

#define DNS_ADBFIND_INET6 0x00000002

[163] Fix | Delete

#define DNS_ADBFIND_ADDRESSMASK 0x00000003

[164] Fix | Delete

/*%

[165] Fix | Delete

* Only schedule an event if no addresses are known.

[166] Fix | Delete

* Must set _WANTEVENT for this to be meaningful.

[167] Fix | Delete

*/

[168] Fix | Delete

#define DNS_ADBFIND_EMPTYEVENT 0x00000004

[169] Fix | Delete

/*%

[170] Fix | Delete

* An event is desired. Check this bit in the returned find to see

[171] Fix | Delete

* if one will actually be generated.

[172] Fix | Delete

*/

[173] Fix | Delete

#define DNS_ADBFIND_WANTEVENT 0x00000008

[174] Fix | Delete

/*%

[175] Fix | Delete

* If set, fetches will not be generated unless no addresses are

[176] Fix | Delete

* available in any of the address families requested.

[177] Fix | Delete

*/

[178] Fix | Delete

#define DNS_ADBFIND_AVOIDFETCHES 0x00000010

[179] Fix | Delete

/*%

[180] Fix | Delete

* Fetches will start using the closest zone data or use the root servers.

[181] Fix | Delete

* This is useful for reestablishing glue that has expired.

[182] Fix | Delete

*/

[183] Fix | Delete

#define DNS_ADBFIND_STARTATZONE 0x00000020

[184] Fix | Delete

/*%

[185] Fix | Delete

* Glue or hints are ok. These are used when matching names already

[186] Fix | Delete

* in the adb, and when dns databases are searched.

[187] Fix | Delete

*/

[188] Fix | Delete

#define DNS_ADBFIND_GLUEOK 0x00000040

[189] Fix | Delete

/*%

[190] Fix | Delete

* Glue or hints are ok. These are used when matching names already

[191] Fix | Delete

* in the adb, and when dns databases are searched.

[192] Fix | Delete

*/

[193] Fix | Delete

#define DNS_ADBFIND_HINTOK 0x00000080

[194] Fix | Delete

/*%

[195] Fix | Delete

* Return lame servers in a find, so that all addresses are returned.

[196] Fix | Delete

*/

[197] Fix | Delete

#define DNS_ADBFIND_RETURNLAME 0x00000100

[198] Fix | Delete

/*%

[199] Fix | Delete

* Only schedule an event if no addresses are known.

[200] Fix | Delete

* Must set _WANTEVENT for this to be meaningful.

[201] Fix | Delete

*/

[202] Fix | Delete

#define DNS_ADBFIND_LAMEPRUNED 0x00000200

[203] Fix | Delete

/*%

[204] Fix | Delete

* The server's fetch quota is exceeded; it will be treated as

[205] Fix | Delete

* lame for this query.

[206] Fix | Delete

*/

[207] Fix | Delete

#define DNS_ADBFIND_OVERQUOTA 0x00000400

[208] Fix | Delete

/*%

[209] Fix | Delete

* Don't perform a fetch even if there are no address records available.

[210] Fix | Delete

*/

[211] Fix | Delete

#define DNS_ADBFIND_NOFETCH 0x00000800

[212] Fix | Delete

[213] Fix | Delete

/*%

[214] Fix | Delete

* The answers to queries come back as a list of these.

[215] Fix | Delete

*/

[216] Fix | Delete

struct dns_adbaddrinfo {

[217] Fix | Delete

unsigned int magic; /*%< private */

[218] Fix | Delete

[219] Fix | Delete

isc_sockaddr_t sockaddr; /*%< [rw] */

[220] Fix | Delete

unsigned int srtt; /*%< [rw] microsecs */

[221] Fix | Delete

isc_dscp_t dscp;

[222] Fix | Delete

[223] Fix | Delete

unsigned int flags; /*%< [rw] */

[224] Fix | Delete

dns_adbentry_t *entry; /*%< private */

[225] Fix | Delete

ISC_LINK(dns_adbaddrinfo_t) publink;

[226] Fix | Delete

};

[227] Fix | Delete

[228] Fix | Delete

/*!<

[229] Fix | Delete

* The event sent to the caller task is just a plain old isc_event_t. It

[230] Fix | Delete

* contains no data other than a simple status, passed in the "type" field

[231] Fix | Delete

* to indicate that another address resolved, or all partially resolved

[232] Fix | Delete

* addresses have failed to resolve.

[233] Fix | Delete

*

[234] Fix | Delete

* "sender" is the dns_adbfind_t used to issue this query.

[235] Fix | Delete

*

[236] Fix | Delete

* This is simply a standard event, with the "type" set to:

[237] Fix | Delete

*

[238] Fix | Delete

*\li #DNS_EVENT_ADBMOREADDRESSES -- another address resolved.

[239] Fix | Delete

*\li #DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed,

[240] Fix | Delete

* were canceled, or otherwise will

[241] Fix | Delete

* not be usable.

[242] Fix | Delete

*\li #DNS_EVENT_ADBCANCELED -- The request was canceled by a

[243] Fix | Delete

* 3rd party.

[244] Fix | Delete

*\li #DNS_EVENT_ADBNAMEDELETED -- The name was deleted, so this request

[245] Fix | Delete

* was canceled.

[246] Fix | Delete

*

[247] Fix | Delete

* In each of these cases, the addresses returned by the initial call

[248] Fix | Delete

* to dns_adb_createfind() can still be used until they are no longer needed.

[249] Fix | Delete

*/

[250] Fix | Delete

[251] Fix | Delete

/****

[252] Fix | Delete

**** FUNCTIONS

[253] Fix | Delete

****/

[254] Fix | Delete

[255] Fix | Delete

[256] Fix | Delete

isc_result_t

[257] Fix | Delete

dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,

[258] Fix | Delete

isc_taskmgr_t *taskmgr, dns_adb_t **newadb);

[259] Fix | Delete

/*%<

[260] Fix | Delete

* Create a new ADB.

[261] Fix | Delete

*

[262] Fix | Delete

* Notes:

[263] Fix | Delete

*

[264] Fix | Delete

*\li Generally, applications should not create an ADB directly, but

[265] Fix | Delete

* should instead call dns_view_createresolver().

[266] Fix | Delete

*

[267] Fix | Delete

* Requires:

[268] Fix | Delete

*

[269] Fix | Delete

*\li 'mem' must be a valid memory context.

[270] Fix | Delete

*

[271] Fix | Delete

*\li 'view' be a pointer to a valid view.

[272] Fix | Delete

*

[273] Fix | Delete

*\li 'tmgr' be a pointer to a valid timer manager.

[274] Fix | Delete

*

[275] Fix | Delete

*\li 'taskmgr' be a pointer to a valid task manager.

[276] Fix | Delete

*

[277] Fix | Delete

*\li 'newadb' != NULL && '*newadb' == NULL.

[278] Fix | Delete

*

[279] Fix | Delete

* Returns:

[280] Fix | Delete

*

[281] Fix | Delete

*\li #ISC_R_SUCCESS after happiness.

[282] Fix | Delete

*\li #ISC_R_NOMEMORY after resource allocation failure.

[283] Fix | Delete

*/

[284] Fix | Delete

[285] Fix | Delete

void

[286] Fix | Delete

dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp);

[287] Fix | Delete

/*%

[288] Fix | Delete

* Attach to an 'adb' to 'adbp'.

[289] Fix | Delete

*

[290] Fix | Delete

* Requires:

[291] Fix | Delete

*\li 'adb' to be a valid dns_adb_t, created via dns_adb_create().

[292] Fix | Delete

*\li 'adbp' to be a valid pointer to a *dns_adb_t which is initialized

[293] Fix | Delete

* to NULL.

[294] Fix | Delete

*/

[295] Fix | Delete

[296] Fix | Delete

void

[297] Fix | Delete

dns_adb_detach(dns_adb_t **adb);

[298] Fix | Delete

/*%

[299] Fix | Delete

* Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests.

[300] Fix | Delete

*

[301] Fix | Delete

* Requires:

[302] Fix | Delete

*

[303] Fix | Delete

*\li 'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via

[304] Fix | Delete

* dns_adb_create().

[305] Fix | Delete

*/

[306] Fix | Delete

[307] Fix | Delete

void

[308] Fix | Delete

dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp);

[309] Fix | Delete

/*%

[310] Fix | Delete

* Send '*eventp' to 'task' when 'adb' has shutdown.

[311] Fix | Delete

*

[312] Fix | Delete

* Requires:

[313] Fix | Delete

*

[314] Fix | Delete

*\li '*adb' is a valid dns_adb_t.

[315] Fix | Delete

*

[316] Fix | Delete

*\li eventp != NULL && *eventp is a valid event.

[317] Fix | Delete

*

[318] Fix | Delete

* Ensures:

[319] Fix | Delete

*

[320] Fix | Delete

*\li *eventp == NULL

[321] Fix | Delete

*

[322] Fix | Delete

*\li The event's sender field is set to the value of adb when the event

[323] Fix | Delete

* is sent.

[324] Fix | Delete

*/

[325] Fix | Delete

[326] Fix | Delete

void

[327] Fix | Delete

dns_adb_shutdown(dns_adb_t *adb);

[328] Fix | Delete

/*%<

[329] Fix | Delete

* Shutdown 'adb'.

[330] Fix | Delete

*

[331] Fix | Delete

* Requires:

[332] Fix | Delete

*

[333] Fix | Delete

* \li '*adb' is a valid dns_adb_t.

[334] Fix | Delete

*/

[335] Fix | Delete

[336] Fix | Delete

isc_result_t

[337] Fix | Delete

dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,

[338] Fix | Delete

void *arg, dns_name_t *name, dns_name_t *qname,

[339] Fix | Delete

dns_rdatatype_t qtype, unsigned int options,

[340] Fix | Delete

isc_stdtime_t now, dns_name_t *target,

[341] Fix | Delete

in_port_t port, dns_adbfind_t **find);

[342] Fix | Delete

isc_result_t

[343] Fix | Delete

dns_adb_createfind2(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,

[344] Fix | Delete

void *arg, dns_name_t *name, dns_name_t *qname,

[345] Fix | Delete

dns_rdatatype_t qtype, unsigned int options,

[346] Fix | Delete

isc_stdtime_t now, dns_name_t *target, in_port_t port,

[347] Fix | Delete

unsigned int depth, isc_counter_t *qc,

[348] Fix | Delete

dns_adbfind_t **find);

[349] Fix | Delete

/*%<

[350] Fix | Delete

* Main interface for clients. The adb will look up the name given in

[351] Fix | Delete

* "name" and will build up a list of found addresses, and perhaps start

[352] Fix | Delete

* internal fetches to resolve names that are unknown currently.

[353] Fix | Delete

*

[354] Fix | Delete

* If other addresses resolve after this call completes, an event will

[355] Fix | Delete

* be sent to the <task, taskaction, arg> with the sender of that event

[356] Fix | Delete

* set to a pointer to the dns_adbfind_t returned by this function.

[357] Fix | Delete

*

[358] Fix | Delete

* If no events will be generated, the *find->result_v4 and/or result_v6

[359] Fix | Delete

* members may be examined for address lookup status. The usual #ISC_R_SUCCESS,

[360] Fix | Delete

* #ISC_R_FAILURE, #DNS_R_NXDOMAIN, and #DNS_R_NXRRSET are returned, along with

[361] Fix | Delete

* #ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values. In this

[362] Fix | Delete

* latter case, retrying may produce more addresses.

[363] Fix | Delete

*

[364] Fix | Delete

* If events will be returned, the result_v[46] members are only valid

[365] Fix | Delete

* when that event is actually returned.

[366] Fix | Delete

*

[367] Fix | Delete

* The list of addresses returned is unordered. The caller must impose

[368] Fix | Delete

* any ordering required. The list will not contain "known bad" addresses,

[369] Fix | Delete

* however. For instance, it will not return hosts that are known to be

[370] Fix | Delete

* lame for the zone in question.

[371] Fix | Delete

*

[372] Fix | Delete

* The caller cannot (directly) modify the contents of the address list's

[373] Fix | Delete

* fields other than the "link" field. All values can be read at any

[374] Fix | Delete

* time, however.

[375] Fix | Delete

*

[376] Fix | Delete

* The "now" parameter is used only for determining which entries that

[377] Fix | Delete

* have a specific time to live or expire time should be removed from

[378] Fix | Delete

* the running database. If specified as zero, the current time will

[379] Fix | Delete

* be retrieved and used.

[380] Fix | Delete

*

[381] Fix | Delete

* If 'target' is not NULL and 'name' is an alias (i.e. the name is

[382] Fix | Delete

* CNAME'd or DNAME'd to another name), then 'target' will be updated with

[383] Fix | Delete

* the domain name that 'name' is aliased to.

[384] Fix | Delete

*

[385] Fix | Delete

* All addresses returned will have the sockaddr's port set to 'port.'

[386] Fix | Delete

* The caller may change them directly in the dns_adbaddrinfo_t since

[387] Fix | Delete

* they are copies of the internal address only.

[388] Fix | Delete

*

[389] Fix | Delete

* XXXMLG Document options, especially the flags which control how

[390] Fix | Delete

* events are sent.

[391] Fix | Delete

*

[392] Fix | Delete

* Requires:

[393] Fix | Delete

*

[394] Fix | Delete

*\li *adb be a valid isc_adb_t object.

[395] Fix | Delete

*

[396] Fix | Delete

*\li If events are to be sent, *task be a valid task,

[397] Fix | Delete

* and isc_taskaction_t != NULL.

[398] Fix | Delete

*

[399] Fix | Delete

*\li *name is a valid dns_name_t.

[400] Fix | Delete

*

[401] Fix | Delete

*\li qname != NULL and *qname be a valid dns_name_t.

[402] Fix | Delete

*

[403] Fix | Delete

*\li target == NULL or target is a valid name with a buffer.

[404] Fix | Delete

*

[405] Fix | Delete

*\li find != NULL && *find == NULL.

[406] Fix | Delete

*

[407] Fix | Delete

* Returns:

[408] Fix | Delete

*

[409] Fix | Delete

*\li #ISC_R_SUCCESS Addresses might have been returned, and events will be

[410] Fix | Delete

* delivered for unresolved addresses.

[411] Fix | Delete

*\li #ISC_R_NOMORE Addresses might have been returned, but no events

[412] Fix | Delete

* will ever be posted for this context. This is only

[413] Fix | Delete

* returned if task != NULL.

[414] Fix | Delete

*\li #ISC_R_NOMEMORY insufficient resources

[415] Fix | Delete

*\li #DNS_R_ALIAS 'name' is an alias for another name.

[416] Fix | Delete

*

[417] Fix | Delete

* Calls, and returns error codes from:

[418] Fix | Delete

*

[419] Fix | Delete

*\li isc_stdtime_get()

[420] Fix | Delete

*

[421] Fix | Delete

* Notes:

[422] Fix | Delete

*

[423] Fix | Delete

*\li No internal reference to "name" exists after this function

[424] Fix | Delete

* returns.

[425] Fix | Delete

*/

[426] Fix | Delete

[427] Fix | Delete

void

[428] Fix | Delete

dns_adb_cancelfind(dns_adbfind_t *find);

[429] Fix | Delete

/*%<

[430] Fix | Delete

* Cancels the find, and sends the event off to the caller.

[431] Fix | Delete

*

[432] Fix | Delete

* It is an error to call dns_adb_cancelfind() on a find where

[433] Fix | Delete

* no event is wanted, or will ever be sent.

[434] Fix | Delete

*

[435] Fix | Delete

* Note:

[436] Fix | Delete

*

[437] Fix | Delete

*\li It is possible that the real completion event was posted just

[438] Fix | Delete

* before the dns_adb_cancelfind() call was made. In this case,

[439] Fix | Delete

* dns_adb_cancelfind() will do nothing. The event callback needs

[440] Fix | Delete

* to be prepared to find this situation (i.e. result is valid but

[441] Fix | Delete

* the caller expects it to be canceled).

[442] Fix | Delete

*

[443] Fix | Delete

* Requires:

[444] Fix | Delete

*

[445] Fix | Delete

*\li 'find' be a valid dns_adbfind_t pointer.

[446] Fix | Delete

*

[447] Fix | Delete

*\li events would have been posted to the task. This can be checked

[448] Fix | Delete

* with (find->options & DNS_ADBFIND_WANTEVENT).

[449] Fix | Delete

*

[450] Fix | Delete

* Ensures:

[451] Fix | Delete

*

[452] Fix | Delete

*\li The event was posted to the task.

[453] Fix | Delete

*/

[454] Fix | Delete

[455] Fix | Delete

void

[456] Fix | Delete

dns_adb_destroyfind(dns_adbfind_t **find);

[457] Fix | Delete

/*%<

[458] Fix | Delete

* Destroys the find reference.

[459] Fix | Delete

*

[460] Fix | Delete

* Note:

[461] Fix | Delete

*

[462] Fix | Delete

*\li This can only be called after the event was delivered for a

[463] Fix | Delete

* find. Additionally, the event MUST have been freed via

[464] Fix | Delete

* isc_event_free() BEFORE this function is called.

[465] Fix | Delete

*

[466] Fix | Delete

* Requires:

[467] Fix | Delete

*

[468] Fix | Delete

*\li 'find' != NULL and *find be valid dns_adbfind_t pointer.

[469] Fix | Delete

*

[470] Fix | Delete

* Ensures:

[471] Fix | Delete

*

[472] Fix | Delete

*\li No "address found" events will be posted to the originating task

[473] Fix | Delete

* after this function returns.

[474] Fix | Delete

*/

[475] Fix | Delete

[476] Fix | Delete

void

[477] Fix | Delete

dns_adb_dump(dns_adb_t *adb, FILE *f);

[478] Fix | Delete

/*%<

[479] Fix | Delete

* This function is only used for debugging. It will dump as much of the

[480] Fix | Delete

* state of the running system as possible.

[481] Fix | Delete

*

[482] Fix | Delete

* Requires:

[483] Fix | Delete

*

[484] Fix | Delete

*\li adb be valid.

[485] Fix | Delete

*

[486] Fix | Delete

*\li f != NULL, and is a file open for writing.

[487] Fix | Delete

*/

[488] Fix | Delete

[489] Fix | Delete

void

[490] Fix | Delete

dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);

[491] Fix | Delete

/*%<

[492] Fix | Delete

* This function is only used for debugging. Dump the data associated

[493] Fix | Delete

* with a find.

[494] Fix | Delete

*

[495] Fix | Delete

* Requires:

[496] Fix | Delete

*

[497] Fix | Delete

*\li find is valid.

[498] Fix | Delete

*

[499] Fix | Delete