/*

[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_CLIENT_H

[12] Fix | Delete

#define DNS_CLIENT_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file

[19] Fix | Delete

*

[20] Fix | Delete

* \brief

[21] Fix | Delete

* The DNS client module provides convenient programming interfaces to various

[22] Fix | Delete

* DNS services, such as name resolution with or without DNSSEC validation or

[23] Fix | Delete

* dynamic DNS update. This module is primarily expected to be used by other

[24] Fix | Delete

* applications than BIND9-related ones that need such advanced DNS features.

[25] Fix | Delete

*

[26] Fix | Delete

* MP:

[27] Fix | Delete

*\li In the typical usage of this module, application threads will not share

[28] Fix | Delete

* the same data structures created and manipulated in this module.

[29] Fix | Delete

* However, the module still ensures appropriate synchronization of such

[30] Fix | Delete

* data structures.

[31] Fix | Delete

*

[32] Fix | Delete

* Resources:

[33] Fix | Delete

*\li TBS

[34] Fix | Delete

*

[35] Fix | Delete

* Security:

[36] Fix | Delete

*\li This module does not handle any low-level data directly, and so no

[37] Fix | Delete

* security issue specific to this module is anticipated.

[38] Fix | Delete

*/

[39] Fix | Delete

[40] Fix | Delete

#include <isc/event.h>

[41] Fix | Delete

#include <isc/sockaddr.h>

[42] Fix | Delete

[43] Fix | Delete

#include <dns/tsig.h>

[44] Fix | Delete

#include <dns/types.h>

[45] Fix | Delete

[46] Fix | Delete

#include <dst/dst.h>

[47] Fix | Delete

[48] Fix | Delete

typedef enum {

[49] Fix | Delete

updateop_none = 0,

[50] Fix | Delete

updateop_add = 1,

[51] Fix | Delete

updateop_delete = 2,

[52] Fix | Delete

updateop_exist = 3,

[53] Fix | Delete

updateop_notexist = 4,

[54] Fix | Delete

updateop_max = 5

[55] Fix | Delete

} dns_client_updateop_t;

[56] Fix | Delete

[57] Fix | Delete

ISC_LANG_BEGINDECLS

[58] Fix | Delete

[59] Fix | Delete

/***

[60] Fix | Delete

*** Types

[61] Fix | Delete

***/

[62] Fix | Delete

[63] Fix | Delete

/*%

[64] Fix | Delete

* Optional flags for dns_client_create(x).

[65] Fix | Delete

*/

[66] Fix | Delete

/*%< Enable caching resolution results (experimental). */

[67] Fix | Delete

#define DNS_CLIENTCREATEOPT_USECACHE 0x8000

[68] Fix | Delete

[69] Fix | Delete

/*%

[70] Fix | Delete

* Optional flags for dns_client_(start)resolve.

[71] Fix | Delete

*/

[72] Fix | Delete

/*%< Do not return DNSSEC data (e.g. RRSIGS) with response. */

[73] Fix | Delete

#define DNS_CLIENTRESOPT_NODNSSEC 0x01

[74] Fix | Delete

/*%< Allow running external context. */

[75] Fix | Delete

#define DNS_CLIENTRESOPT_ALLOWRUN 0x02

[76] Fix | Delete

/*%< Don't validate responses. */

[77] Fix | Delete

#define DNS_CLIENTRESOPT_NOVALIDATE 0x04

[78] Fix | Delete

/*%< Don't set the CD flag on upstream queries. */

[79] Fix | Delete

#define DNS_CLIENTRESOPT_NOCDFLAG 0x08

[80] Fix | Delete

/*%< Use TCP transport. */

[81] Fix | Delete

#define DNS_CLIENTRESOPT_TCP 0x10

[82] Fix | Delete

[83] Fix | Delete

/*%

[84] Fix | Delete

* Optional flags for dns_client_(start)request.

[85] Fix | Delete

*/

[86] Fix | Delete

/*%< Allow running external context. */

[87] Fix | Delete

#define DNS_CLIENTREQOPT_ALLOWRUN 0x01

[88] Fix | Delete

/*%< Use TCP transport. */

[89] Fix | Delete

#define DNS_CLIENTREQOPT_TCP 0x02

[90] Fix | Delete

[91] Fix | Delete

/*%

[92] Fix | Delete

* Optional flags for dns_client_(start)update.

[93] Fix | Delete

*/

[94] Fix | Delete

/*%< Allow running external context. */

[95] Fix | Delete

#define DNS_CLIENTUPDOPT_ALLOWRUN 0x01

[96] Fix | Delete

/*%< Use TCP transport. */

[97] Fix | Delete

#define DNS_CLIENTUPDOPT_TCP 0x02

[98] Fix | Delete

[99] Fix | Delete

/*%

[100] Fix | Delete

* A dns_clientresevent_t is sent when name resolution performed by a client

[101] Fix | Delete

* completes. 'result' stores the result code of the entire resolution

[102] Fix | Delete

* procedure. 'vresult' specifically stores the result code of DNSSEC

[103] Fix | Delete

* validation if it is performed. When name resolution successfully completes,

[104] Fix | Delete

* 'answerlist' is typically non empty, containing answer names along with

[105] Fix | Delete

* RRsets. It is the receiver's responsibility to free this list by calling

[106] Fix | Delete

* dns_client_freeresanswer() before freeing the event structure.

[107] Fix | Delete

*/

[108] Fix | Delete

typedef struct dns_clientresevent {

[109] Fix | Delete

ISC_EVENT_COMMON(struct dns_clientresevent);

[110] Fix | Delete

isc_result_t result;

[111] Fix | Delete

isc_result_t vresult;

[112] Fix | Delete

dns_namelist_t answerlist;

[113] Fix | Delete

} dns_clientresevent_t; /* too long? */

[114] Fix | Delete

[115] Fix | Delete

/*%

[116] Fix | Delete

* Status of a dynamic update procedure.

[117] Fix | Delete

*/

[118] Fix | Delete

typedef enum {

[119] Fix | Delete

dns_clientupdatestate_prepare, /*%< no updates have been sent */

[120] Fix | Delete

dns_clientupdatestate_sent, /*%< updates were sent, no response */

[121] Fix | Delete

dns_clientupdatestate_done /*%< update was sent and succeeded */

[122] Fix | Delete

} dns_clientupdatestate_t;

[123] Fix | Delete

[124] Fix | Delete

/*%

[125] Fix | Delete

* A dns_clientreqevent_t is sent when a DNS request is completed by a client.

[126] Fix | Delete

* 'result' stores the result code of the entire transaction.

[127] Fix | Delete

* If the transaction is successfully completed but the response packet cannot

[128] Fix | Delete

* be parsed, 'result' will store the result code of dns_message_parse().

[129] Fix | Delete

* If the response packet is received, 'rmessage' will contain the response

[130] Fix | Delete

* message, whether it is successfully parsed or not.

[131] Fix | Delete

*/

[132] Fix | Delete

typedef struct dns_clientreqevent {

[133] Fix | Delete

ISC_EVENT_COMMON(struct dns_clientreqevent);

[134] Fix | Delete

isc_result_t result;

[135] Fix | Delete

dns_message_t *rmessage;

[136] Fix | Delete

} dns_clientreqevent_t; /* too long? */

[137] Fix | Delete

[138] Fix | Delete

/*%

[139] Fix | Delete

* A dns_clientupdateevent_t is sent when dynamic update performed by a client

[140] Fix | Delete

* completes. 'result' stores the result code of the entire update procedure.

[141] Fix | Delete

* 'state' specifies the status of the update procedure when this event is

[142] Fix | Delete

* sent. This can be used as a hint by the receiver to determine whether

[143] Fix | Delete

* the update attempt was ever made. In particular, if the state is

[144] Fix | Delete

* dns_clientupdatestate_prepare, the receiver can be sure that the requested

[145] Fix | Delete

* update was not applied.

[146] Fix | Delete

*/

[147] Fix | Delete

typedef struct dns_clientupdateevent {

[148] Fix | Delete

ISC_EVENT_COMMON(struct dns_clientupdateevent);

[149] Fix | Delete

isc_result_t result;

[150] Fix | Delete

dns_clientupdatestate_t state;

[151] Fix | Delete

} dns_clientupdateevent_t; /* too long? */

[152] Fix | Delete

[153] Fix | Delete

isc_result_t

[154] Fix | Delete

dns_client_create(dns_client_t **clientp, unsigned int options);

[155] Fix | Delete

[156] Fix | Delete

isc_result_t

[157] Fix | Delete

dns_client_createx(isc_mem_t *mctx, isc_appctx_t *actx, isc_taskmgr_t *taskmgr,

[158] Fix | Delete

isc_socketmgr_t *socketmgr, isc_timermgr_t *timermgr,

[159] Fix | Delete

unsigned int options, dns_client_t **clientp);

[160] Fix | Delete

[161] Fix | Delete

isc_result_t

[162] Fix | Delete

dns_client_createx2(isc_mem_t *mctx, isc_appctx_t *actx,

[163] Fix | Delete

isc_taskmgr_t *taskmgr, isc_socketmgr_t *socketmgr,

[164] Fix | Delete

isc_timermgr_t *timermgr, unsigned int options,

[165] Fix | Delete

dns_client_t **clientp,

[166] Fix | Delete

isc_sockaddr_t *localaddr4, isc_sockaddr_t *localaddr6);

[167] Fix | Delete

/*%<

[168] Fix | Delete

* Create a DNS client. These functions create a new client object with

[169] Fix | Delete

* minimal internal resources such as the default 'view' for the IN class and

[170] Fix | Delete

* IPv4/IPv6 dispatches for the view.

[171] Fix | Delete

*

[172] Fix | Delete

* dns_client_createx() takes 'manager' arguments so that the caller can

[173] Fix | Delete

* control the behavior of the client through the underlying event framework.

[174] Fix | Delete

* On the other hand, dns_client_create() simplifies the interface and creates

[175] Fix | Delete

* the managers internally. A DNS client object created via

[176] Fix | Delete

* dns_client_create() is expected to be used by an application that only needs

[177] Fix | Delete

* simple synchronous services or by a thread-based application.

[178] Fix | Delete

*

[179] Fix | Delete

* dns_client_createx2 takes two additional parameters, 'localaddr4' and

[180] Fix | Delete

* 'localaddr6', to specify the local address to use for each family. If

[181] Fix | Delete

* both are set to NULL, then wildcard addresses will be used for both

[182] Fix | Delete

* families. If only one is NULL, then the other address will be used

[183] Fix | Delete

* as the local address, and the other protocol family will not be used.

[184] Fix | Delete

*

[185] Fix | Delete

* If the DNS_CLIENTCREATEOPT_USECACHE flag is set in 'options',

[186] Fix | Delete

* dns_client_create(x) will create a cache database with the view.

[187] Fix | Delete

*

[188] Fix | Delete

* Requires:

[189] Fix | Delete

*

[190] Fix | Delete

*\li 'mctx' is a valid memory context.

[191] Fix | Delete

*

[192] Fix | Delete

*\li 'actx' is a valid application context.

[193] Fix | Delete

*

[194] Fix | Delete

*\li 'taskmgr' is a valid task manager.

[195] Fix | Delete

*

[196] Fix | Delete

*\li 'socketmgr' is a valid socket manager.

[197] Fix | Delete

*

[198] Fix | Delete

*\li 'timermgr' is a valid timer manager.

[199] Fix | Delete

*

[200] Fix | Delete

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

[201] Fix | Delete

*

[202] Fix | Delete

* Returns:

[203] Fix | Delete

*

[204] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[205] Fix | Delete

*

[206] Fix | Delete

*\li Anything else Failure.

[207] Fix | Delete

*/

[208] Fix | Delete

[209] Fix | Delete

void

[210] Fix | Delete

dns_client_destroy(dns_client_t **clientp);

[211] Fix | Delete

/*%<

[212] Fix | Delete

* Destroy 'client'.

[213] Fix | Delete

*

[214] Fix | Delete

* Requires:

[215] Fix | Delete

*

[216] Fix | Delete

*\li '*clientp' is a valid client.

[217] Fix | Delete

*

[218] Fix | Delete

* Ensures:

[219] Fix | Delete

*

[220] Fix | Delete

*\li *clientp == NULL.

[221] Fix | Delete

*/

[222] Fix | Delete

[223] Fix | Delete

isc_result_t

[224] Fix | Delete

dns_client_setservers(dns_client_t *client, dns_rdataclass_t rdclass,

[225] Fix | Delete

dns_name_t *name_space, isc_sockaddrlist_t *addrs);

[226] Fix | Delete

/*%<

[227] Fix | Delete

* Specify a list of addresses of recursive name servers that the client will

[228] Fix | Delete

* use for name resolution. A view for the 'rdclass' class must be created

[229] Fix | Delete

* beforehand. If 'name_space' is non NULL, the specified server will be used

[230] Fix | Delete

* if and only if the query name is a subdomain of 'name_space'. When servers

[231] Fix | Delete

* for multiple 'name_space's are provided, and a query name is covered by

[232] Fix | Delete

* more than one 'name_space', the servers for the best (longest) matching

[233] Fix | Delete

* name_space will be used. If 'name_space' is NULL, it works as if

[234] Fix | Delete

* dns_rootname (.) were specified.

[235] Fix | Delete

*

[236] Fix | Delete

* Requires:

[237] Fix | Delete

*

[238] Fix | Delete

*\li 'client' is a valid client.

[239] Fix | Delete

*

[240] Fix | Delete

*\li 'name_space' is NULL or a valid name.

[241] Fix | Delete

*

[242] Fix | Delete

*\li 'addrs' != NULL.

[243] Fix | Delete

*

[244] Fix | Delete

* Returns:

[245] Fix | Delete

*

[246] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[247] Fix | Delete

*

[248] Fix | Delete

*\li Anything else Failure.

[249] Fix | Delete

*/

[250] Fix | Delete

[251] Fix | Delete

isc_result_t

[252] Fix | Delete

dns_client_clearservers(dns_client_t *client, dns_rdataclass_t rdclass,

[253] Fix | Delete

dns_name_t *name_space);

[254] Fix | Delete

/*%<

[255] Fix | Delete

* Remove configured recursive name servers for the 'rdclass' and 'name_space'

[256] Fix | Delete

* from the client. See the description of dns_client_setservers() for

[257] Fix | Delete

* the requirements about 'rdclass' and 'name_space'.

[258] Fix | Delete

*

[259] Fix | Delete

* Requires:

[260] Fix | Delete

*

[261] Fix | Delete

*\li 'client' is a valid client.

[262] Fix | Delete

*

[263] Fix | Delete

*\li 'name_space' is NULL or a valid name.

[264] Fix | Delete

*

[265] Fix | Delete

* Returns:

[266] Fix | Delete

*

[267] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[268] Fix | Delete

*

[269] Fix | Delete

*\li Anything else Failure.

[270] Fix | Delete

*/

[271] Fix | Delete

[272] Fix | Delete

isc_result_t

[273] Fix | Delete

dns_client_setdlv(dns_client_t *client, dns_rdataclass_t rdclass,

[274] Fix | Delete

const char *dlvname);

[275] Fix | Delete

/*%<

[276] Fix | Delete

* Specify a name to use for DNSSEC lookaside validation.

[277] Fix | Delete

* If a trusted key has been added for that name, then DLV will be

[278] Fix | Delete

* used during validation. If 'dlvname' is NULL, then DLV will no

[279] Fix | Delete

* longer be used for this client.

[280] Fix | Delete

*

[281] Fix | Delete

* Requires:

[282] Fix | Delete

*

[283] Fix | Delete

*\li 'client' is a valid client.

[284] Fix | Delete

*

[285] Fix | Delete

* Returns:

[286] Fix | Delete

*

[287] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[288] Fix | Delete

*

[289] Fix | Delete

*\li Anything else Failure.

[290] Fix | Delete

*/

[291] Fix | Delete

[292] Fix | Delete

isc_result_t

[293] Fix | Delete

dns_client_resolve(dns_client_t *client, dns_name_t *name,

[294] Fix | Delete

dns_rdataclass_t rdclass, dns_rdatatype_t type,

[295] Fix | Delete

unsigned int options, dns_namelist_t *namelist);

[296] Fix | Delete

[297] Fix | Delete

isc_result_t

[298] Fix | Delete

dns_client_startresolve(dns_client_t *client, dns_name_t *name,

[299] Fix | Delete

dns_rdataclass_t rdclass, dns_rdatatype_t type,

[300] Fix | Delete

unsigned int options, isc_task_t *task,

[301] Fix | Delete

isc_taskaction_t action, void *arg,

[302] Fix | Delete

dns_clientrestrans_t **transp);

[303] Fix | Delete

/*%<

[304] Fix | Delete

* Perform name resolution for 'name', 'rdclass', and 'type'.

[305] Fix | Delete

*

[306] Fix | Delete

* If any trusted keys are configured and the query name is considered to

[307] Fix | Delete

* belong to a secure zone, these functions also validate the responses

[308] Fix | Delete

* using DNSSEC by default. If the DNS_CLIENTRESOPT_NOVALIDATE flag is set

[309] Fix | Delete

* in 'options', DNSSEC validation is disabled regardless of the configured

[310] Fix | Delete

* trusted keys or the query name. With DNS_CLIENTRESOPT_NODNSSEC

[311] Fix | Delete

* DNSSEC data is not returned with response. DNS_CLIENTRESOPT_NOCDFLAG

[312] Fix | Delete

* disables the CD flag on queries, DNS_CLIENTRESOPT_TCP switches to

[313] Fix | Delete

* the TCP (vs. UDP) transport.

[314] Fix | Delete

*

[315] Fix | Delete

* dns_client_resolve() provides a synchronous service. This function starts

[316] Fix | Delete

* name resolution internally and blocks until it completes. On success,

[317] Fix | Delete

* 'namelist' will contain a list of answer names, each of which has

[318] Fix | Delete

* corresponding RRsets. The caller must provide a valid empty list, and

[319] Fix | Delete

* is responsible for freeing the list content via dns_client_freeresanswer().

[320] Fix | Delete

* If the name resolution fails due to an error in DNSSEC validation,

[321] Fix | Delete

* dns_client_resolve() returns the result code indicating the validation

[322] Fix | Delete

* error. Otherwise, it returns the result code of the entire resolution

[323] Fix | Delete

* process, either success or failure.

[324] Fix | Delete

*

[325] Fix | Delete

* It is typically expected that the client object passed to

[326] Fix | Delete

* dns_client_resolve() was created via dns_client_create() and has its own

[327] Fix | Delete

* managers and contexts. However, if the DNS_CLIENTRESOPT_ALLOWRUN flag is

[328] Fix | Delete

* set in 'options', this function performs the synchronous service even if

[329] Fix | Delete

* it does not have its own manager and context structures.

[330] Fix | Delete

*

[331] Fix | Delete

* dns_client_startresolve() is an asynchronous version of dns_client_resolve()

[332] Fix | Delete

* and does not block. When name resolution is completed, 'action' will be

[333] Fix | Delete

* called with the argument of a 'dns_clientresevent_t' object, which contains

[334] Fix | Delete

* the resulting list of answer names (on success). On return, '*transp' is

[335] Fix | Delete

* set to an opaque transaction ID so that the caller can cancel this

[336] Fix | Delete

* resolution process.

[337] Fix | Delete

*

[338] Fix | Delete

* Requires:

[339] Fix | Delete

*

[340] Fix | Delete

*\li 'client' is a valid client.

[341] Fix | Delete

*

[342] Fix | Delete

*\li 'addrs' != NULL.

[343] Fix | Delete

*

[344] Fix | Delete

*\li 'name' is a valid name.

[345] Fix | Delete

*

[346] Fix | Delete

*\li 'namelist' != NULL and is not empty.

[347] Fix | Delete

*

[348] Fix | Delete

*\li 'task' is a valid task.

[349] Fix | Delete

*

[350] Fix | Delete

*\li 'transp' != NULL && *transp == NULL;

[351] Fix | Delete

*

[352] Fix | Delete

* Returns:

[353] Fix | Delete

*

[354] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[355] Fix | Delete

*

[356] Fix | Delete

*\li Anything else Failure.

[357] Fix | Delete

*/

[358] Fix | Delete

[359] Fix | Delete

void

[360] Fix | Delete

dns_client_cancelresolve(dns_clientrestrans_t *trans);

[361] Fix | Delete

/*%<

[362] Fix | Delete

* Cancel an ongoing resolution procedure started via

[363] Fix | Delete

* dns_client_startresolve().

[364] Fix | Delete

*

[365] Fix | Delete

* Notes:

[366] Fix | Delete

*

[367] Fix | Delete

*\li If the resolution procedure has not completed, post its CLIENTRESDONE

[368] Fix | Delete

* event with a result code of #ISC_R_CANCELED.

[369] Fix | Delete

*

[370] Fix | Delete

* Requires:

[371] Fix | Delete

*

[372] Fix | Delete

*\li 'trans' is a valid transaction ID.

[373] Fix | Delete

*/

[374] Fix | Delete

[375] Fix | Delete

void

[376] Fix | Delete

dns_client_destroyrestrans(dns_clientrestrans_t **transp);

[377] Fix | Delete

/*%<

[378] Fix | Delete

* Destroy name resolution transaction state identified by '*transp'.

[379] Fix | Delete

*

[380] Fix | Delete

* Requires:

[381] Fix | Delete

*

[382] Fix | Delete

*\li '*transp' is a valid transaction ID.

[383] Fix | Delete

*

[384] Fix | Delete

*\li The caller has received the CLIENTRESDONE event (either because the

[385] Fix | Delete

* resolution completed or because dns_client_cancelresolve() was called).

[386] Fix | Delete

*

[387] Fix | Delete

* Ensures:

[388] Fix | Delete

*

[389] Fix | Delete

*\li *transp == NULL.

[390] Fix | Delete

*/

[391] Fix | Delete

[392] Fix | Delete

void

[393] Fix | Delete

dns_client_freeresanswer(dns_client_t *client, dns_namelist_t *namelist);

[394] Fix | Delete

/*%<

[395] Fix | Delete

* Free resources allocated for the content of 'namelist'.

[396] Fix | Delete

*

[397] Fix | Delete

* Requires:

[398] Fix | Delete

*

[399] Fix | Delete

*\li 'client' is a valid client.

[400] Fix | Delete

*

[401] Fix | Delete

*\li 'namelist' != NULL.

[402] Fix | Delete

*/

[403] Fix | Delete

[404] Fix | Delete

isc_result_t

[405] Fix | Delete

dns_client_addtrustedkey(dns_client_t *client, dns_rdataclass_t rdclass,

[406] Fix | Delete

dns_name_t *keyname, isc_buffer_t *keydatabuf);

[407] Fix | Delete

/*%<

[408] Fix | Delete

* Add a DNSSEC trusted key for the 'rdclass' class. A view for the 'rdclass'

[409] Fix | Delete

* class must be created beforehand. 'keyname' is the DNS name of the key,

[410] Fix | Delete

* and 'keydatabuf' stores the resource data of the key.

[411] Fix | Delete

*

[412] Fix | Delete

* Requires:

[413] Fix | Delete

*

[414] Fix | Delete

*\li 'client' is a valid client.

[415] Fix | Delete

*

[416] Fix | Delete

*\li 'keyname' is a valid name.

[417] Fix | Delete

*

[418] Fix | Delete

*\li 'keydatabuf' is a valid buffer.

[419] Fix | Delete

*

[420] Fix | Delete

* Returns:

[421] Fix | Delete

*

[422] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[423] Fix | Delete

*

[424] Fix | Delete

*\li Anything else Failure.

[425] Fix | Delete

*/

[426] Fix | Delete

[427] Fix | Delete

isc_result_t

[428] Fix | Delete

dns_client_request(dns_client_t *client, dns_message_t *qmessage,

[429] Fix | Delete

dns_message_t *rmessage, isc_sockaddr_t *server,

[430] Fix | Delete

unsigned int options, unsigned int parseoptions,

[431] Fix | Delete

dns_tsec_t *tsec, unsigned int timeout,

[432] Fix | Delete

unsigned int udptimeout, unsigned int udpretries);

[433] Fix | Delete

[434] Fix | Delete

isc_result_t

[435] Fix | Delete

dns_client_startrequest(dns_client_t *client, dns_message_t *qmessage,

[436] Fix | Delete

dns_message_t *rmessage, isc_sockaddr_t *server,

[437] Fix | Delete

unsigned int options, unsigned int parseoptions,

[438] Fix | Delete

dns_tsec_t *tsec, unsigned int timeout,

[439] Fix | Delete

unsigned int udptimeout, unsigned int udpretries,

[440] Fix | Delete

isc_task_t *task, isc_taskaction_t action, void *arg,

[441] Fix | Delete

dns_clientreqtrans_t **transp);

[442] Fix | Delete

[443] Fix | Delete

/*%<

[444] Fix | Delete

* Send a DNS request containing a query message 'query' to 'server'.

[445] Fix | Delete

*

[446] Fix | Delete

* 'parseoptions' will be used when the response packet is parsed, and will be

[447] Fix | Delete

* passed to dns_message_parse() via dns_request_getresponse(). See

[448] Fix | Delete

* dns_message_parse() for more details.

[449] Fix | Delete

*

[450] Fix | Delete

* 'tsec' is a transaction security object containing, e.g. a TSIG key for

[451] Fix | Delete

* authenticating the request/response transaction. This is optional and can

[452] Fix | Delete

* be NULL, in which case this library performs the transaction without any

[453] Fix | Delete

* transaction authentication.

[454] Fix | Delete

*

[455] Fix | Delete

* 'timeout', 'udptimeout', and 'udpretries' are passed to

[456] Fix | Delete

* dns_request_createvia3(). See dns_request_createvia3() for more details.

[457] Fix | Delete

*

[458] Fix | Delete

* dns_client_request() provides a synchronous service. This function sends

[459] Fix | Delete

* the request and blocks until a response is received. On success,

[460] Fix | Delete

* 'rmessage' will contain the response message. The caller must provide a

[461] Fix | Delete

* valid initialized message.

[462] Fix | Delete

*

[463] Fix | Delete

* It is usually expected that the client object passed to

[464] Fix | Delete

* dns_client_request() was created via dns_client_create() and has its own

[465] Fix | Delete

* managers and contexts. However, if the DNS_CLIENTREQOPT_ALLOWRUN flag is

[466] Fix | Delete

* set in 'options', this function performs the synchronous service even if

[467] Fix | Delete

* it does not have its own manager and context structures.

[468] Fix | Delete

*

[469] Fix | Delete

* dns_client_startrequest() is an asynchronous version of dns_client_request()

[470] Fix | Delete

* and does not block. When the transaction is completed, 'action' will be

[471] Fix | Delete

* called with the argument of a 'dns_clientreqevent_t' object, which contains

[472] Fix | Delete

* the response message (on success). On return, '*transp' is set to an opaque

[473] Fix | Delete

* transaction ID so that the caller can cancel this request.

[474] Fix | Delete

*

[475] Fix | Delete

* DNS_CLIENTREQOPT_TCP switches to the TCP (vs. UDP) transport.

[476] Fix | Delete

*

[477] Fix | Delete

* Requires:

[478] Fix | Delete

*

[479] Fix | Delete

*\li 'client' is a valid client.

[480] Fix | Delete

*

[481] Fix | Delete

*\li 'qmessage' and 'rmessage' are valid initialized message.

[482] Fix | Delete

*

[483] Fix | Delete

*\li 'server' is a valid socket address structure.

[484] Fix | Delete

*

[485] Fix | Delete

*\li 'task' is a valid task.

[486] Fix | Delete

*

[487] Fix | Delete

*\li 'transp' != NULL && *transp == NULL;

[488] Fix | Delete

*

[489] Fix | Delete

* Returns:

[490] Fix | Delete

*

[491] Fix | Delete

*\li #ISC_R_SUCCESS On success.

[492] Fix | Delete

*

[493] Fix | Delete

*\li Anything else Failure.

[494] Fix | Delete

*

[495] Fix | Delete

*\li Any result that dns_message_parse() can return.

[496] Fix | Delete

*/

[497] Fix | Delete

[498] Fix | Delete

void

[499] Fix | Delete