/*

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

[12] Fix | Delete

#define DNS_REQUEST_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file dns/request.h

[19] Fix | Delete

*

[20] Fix | Delete

* \brief

[21] Fix | Delete

* The request module provides simple request/response services useful for

[22] Fix | Delete

* sending SOA queries, DNS Notify messages, and dynamic update requests.

[23] Fix | Delete

*

[24] Fix | Delete

* MP:

[25] Fix | Delete

*\li The module ensures appropriate synchronization of data structures it

[26] Fix | Delete

* creates and manipulates.

[27] Fix | Delete

*

[28] Fix | Delete

* Resources:

[29] Fix | Delete

*\li TBS

[30] Fix | Delete

*

[31] Fix | Delete

* Security:

[32] Fix | Delete

*\li No anticipated impact.

[33] Fix | Delete

*/

[34] Fix | Delete

[35] Fix | Delete

#include <stdbool.h>

[36] Fix | Delete

#include <isc/lang.h>

[37] Fix | Delete

#include <isc/event.h>

[38] Fix | Delete

[39] Fix | Delete

#include <dns/types.h>

[40] Fix | Delete

[41] Fix | Delete

#define DNS_REQUESTOPT_TCP 0x00000001U

[42] Fix | Delete

#define DNS_REQUESTOPT_CASE 0x00000002U

[43] Fix | Delete

#define DNS_REQUESTOPT_FIXEDID 0x00000004U

[44] Fix | Delete

#define DNS_REQUESTOPT_SHARE 0x00000008U

[45] Fix | Delete

[46] Fix | Delete

typedef struct dns_requestevent {

[47] Fix | Delete

ISC_EVENT_COMMON(struct dns_requestevent);

[48] Fix | Delete

isc_result_t result;

[49] Fix | Delete

dns_request_t *request;

[50] Fix | Delete

} dns_requestevent_t;

[51] Fix | Delete

[52] Fix | Delete

ISC_LANG_BEGINDECLS

[53] Fix | Delete

[54] Fix | Delete

isc_result_t

[55] Fix | Delete

dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,

[56] Fix | Delete

isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr,

[57] Fix | Delete

dns_dispatchmgr_t *dispatchmgr,

[58] Fix | Delete

dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,

[59] Fix | Delete

dns_requestmgr_t **requestmgrp);

[60] Fix | Delete

/*%<

[61] Fix | Delete

* Create a request manager.

[62] Fix | Delete

*

[63] Fix | Delete

* Requires:

[64] Fix | Delete

*

[65] Fix | Delete

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

[66] Fix | Delete

*

[67] Fix | Delete

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

[68] Fix | Delete

*

[69] Fix | Delete

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

[70] Fix | Delete

*

[71] Fix | Delete

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

[72] Fix | Delete

*

[73] Fix | Delete

*\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.

[74] Fix | Delete

*

[75] Fix | Delete

*\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.

[76] Fix | Delete

*

[77] Fix | Delete

*\li requestmgrp != NULL && *requestmgrp == NULL

[78] Fix | Delete

*

[79] Fix | Delete

* Ensures:

[80] Fix | Delete

*

[81] Fix | Delete

*\li On success, *requestmgrp is a valid request manager.

[82] Fix | Delete

*

[83] Fix | Delete

* Returns:

[84] Fix | Delete

*

[85] Fix | Delete

*\li ISC_R_SUCCESS

[86] Fix | Delete

*

[87] Fix | Delete

*\li Any other result indicates failure.

[88] Fix | Delete

*/

[89] Fix | Delete

[90] Fix | Delete

void

[91] Fix | Delete

dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,

[92] Fix | Delete

isc_event_t **eventp);

[93] Fix | Delete

/*%<

[94] Fix | Delete

* Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.

[95] Fix | Delete

*

[96] Fix | Delete

* Notes:

[97] Fix | Delete

*

[98] Fix | Delete

*\li It is not safe to detach the last reference to 'requestmgr' until

[99] Fix | Delete

* shutdown is complete.

[100] Fix | Delete

*

[101] Fix | Delete

* Requires:

[102] Fix | Delete

*

[103] Fix | Delete

*\li 'requestmgr' is a valid request manager.

[104] Fix | Delete

*

[105] Fix | Delete

*\li 'task' is a valid task.

[106] Fix | Delete

*

[107] Fix | Delete

*\li *eventp is a valid event.

[108] Fix | Delete

*

[109] Fix | Delete

* Ensures:

[110] Fix | Delete

*

[111] Fix | Delete

*\li *eventp == NULL.

[112] Fix | Delete

*/

[113] Fix | Delete

[114] Fix | Delete

void

[115] Fix | Delete

dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);

[116] Fix | Delete

/*%<

[117] Fix | Delete

* Start the shutdown process for 'requestmgr'.

[118] Fix | Delete

*

[119] Fix | Delete

* Notes:

[120] Fix | Delete

*

[121] Fix | Delete

*\li This call has no effect if the request manager is already shutting

[122] Fix | Delete

* down.

[123] Fix | Delete

*

[124] Fix | Delete

* Requires:

[125] Fix | Delete

*

[126] Fix | Delete

*\li 'requestmgr' is a valid requestmgr.

[127] Fix | Delete

*/

[128] Fix | Delete

[129] Fix | Delete

void

[130] Fix | Delete

dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);

[131] Fix | Delete

/*%<

[132] Fix | Delete

* Attach to the request manager. dns_requestmgr_shutdown() must not

[133] Fix | Delete

* have been called on 'source' prior to calling dns_requestmgr_attach().

[134] Fix | Delete

*

[135] Fix | Delete

* Requires:

[136] Fix | Delete

*

[137] Fix | Delete

*\li 'source' is a valid requestmgr.

[138] Fix | Delete

*

[139] Fix | Delete

*\li 'targetp' to be non NULL and '*targetp' to be NULL.

[140] Fix | Delete

*/

[141] Fix | Delete

[142] Fix | Delete

void

[143] Fix | Delete

dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);

[144] Fix | Delete

/*%<

[145] Fix | Delete

* Detach from the given requestmgr. If this is the final detach

[146] Fix | Delete

* requestmgr will be destroyed. dns_requestmgr_shutdown() must

[147] Fix | Delete

* be called before the final detach.

[148] Fix | Delete

*

[149] Fix | Delete

* Requires:

[150] Fix | Delete

*

[151] Fix | Delete

*\li '*requestmgrp' is a valid requestmgr.

[152] Fix | Delete

*

[153] Fix | Delete

* Ensures:

[154] Fix | Delete

*\li '*requestmgrp' is NULL.

[155] Fix | Delete

*/

[156] Fix | Delete

[157] Fix | Delete

isc_result_t

[158] Fix | Delete

dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,

[159] Fix | Delete

isc_sockaddr_t *address, unsigned int options,

[160] Fix | Delete

dns_tsigkey_t *key,

[161] Fix | Delete

unsigned int timeout, isc_task_t *task,

[162] Fix | Delete

isc_taskaction_t action, void *arg,

[163] Fix | Delete

dns_request_t **requestp);

[164] Fix | Delete

/*%<

[165] Fix | Delete

* Create and send a request.

[166] Fix | Delete

*

[167] Fix | Delete

* Notes:

[168] Fix | Delete

*

[169] Fix | Delete

*\li 'message' will be rendered and sent to 'address'. If the

[170] Fix | Delete

* #DNS_REQUESTOPT_TCP option is set, TCP will be used,

[171] Fix | Delete

* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP

[172] Fix | Delete

* (vs. connected) will be shared too. The request

[173] Fix | Delete

* will timeout after 'timeout' seconds.

[174] Fix | Delete

*

[175] Fix | Delete

*\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive

[176] Fix | Delete

* compression.

[177] Fix | Delete

*

[178] Fix | Delete

*\li When the request completes, successfully, due to a timeout, or

[179] Fix | Delete

* because it was canceled, a completion event will be sent to 'task'.

[180] Fix | Delete

*

[181] Fix | Delete

* Requires:

[182] Fix | Delete

*

[183] Fix | Delete

*\li 'message' is a valid DNS message.

[184] Fix | Delete

*

[185] Fix | Delete

*\li 'address' is a valid sockaddr.

[186] Fix | Delete

*

[187] Fix | Delete

*\li 'timeout' > 0

[188] Fix | Delete

*

[189] Fix | Delete

*\li 'task' is a valid task.

[190] Fix | Delete

*

[191] Fix | Delete

*\li requestp != NULL && *requestp == NULL

[192] Fix | Delete

*/

[193] Fix | Delete

[194] Fix | Delete

/*% See dns_request_createvia4() */

[195] Fix | Delete

isc_result_t

[196] Fix | Delete

dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,

[197] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[198] Fix | Delete

unsigned int options, dns_tsigkey_t *key,

[199] Fix | Delete

unsigned int timeout, isc_task_t *task,

[200] Fix | Delete

isc_taskaction_t action, void *arg,

[201] Fix | Delete

dns_request_t **requestp);

[202] Fix | Delete

[203] Fix | Delete

/*% See dns_request_createvia4() */

[204] Fix | Delete

isc_result_t

[205] Fix | Delete

dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,

[206] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[207] Fix | Delete

unsigned int options, dns_tsigkey_t *key,

[208] Fix | Delete

unsigned int timeout, unsigned int udptimeout,

[209] Fix | Delete

isc_task_t *task, isc_taskaction_t action, void *arg,

[210] Fix | Delete

dns_request_t **requestp);

[211] Fix | Delete

[212] Fix | Delete

/*% See dns_request_createvia4() */

[213] Fix | Delete

isc_result_t

[214] Fix | Delete

dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,

[215] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[216] Fix | Delete

unsigned int options, dns_tsigkey_t *key,

[217] Fix | Delete

unsigned int timeout, unsigned int udptimeout,

[218] Fix | Delete

unsigned int udpretries, isc_task_t *task,

[219] Fix | Delete

isc_taskaction_t action, void *arg,

[220] Fix | Delete

dns_request_t **requestp);

[221] Fix | Delete

[222] Fix | Delete

isc_result_t

[223] Fix | Delete

dns_request_createvia4(dns_requestmgr_t *requestmgr, dns_message_t *message,

[224] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[225] Fix | Delete

isc_dscp_t dscp, unsigned int options,

[226] Fix | Delete

dns_tsigkey_t *key, unsigned int timeout,

[227] Fix | Delete

unsigned int udptimeout, unsigned int udpretries,

[228] Fix | Delete

isc_task_t *task, isc_taskaction_t action, void *arg,

[229] Fix | Delete

dns_request_t **requestp);

[230] Fix | Delete

/*%<

[231] Fix | Delete

* Create and send a request.

[232] Fix | Delete

*

[233] Fix | Delete

* Notes:

[234] Fix | Delete

*

[235] Fix | Delete

*\li 'message' will be rendered and sent to 'address'. If the

[236] Fix | Delete

* #DNS_REQUESTOPT_TCP option is set, TCP will be used,

[237] Fix | Delete

* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP

[238] Fix | Delete

* (vs. connected) will be shared too. The request

[239] Fix | Delete

* will timeout after 'timeout' seconds. UDP requests will be resent

[240] Fix | Delete

* at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.

[241] Fix | Delete

*

[242] Fix | Delete

*\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive

[243] Fix | Delete

* compression.

[244] Fix | Delete

*

[245] Fix | Delete

*\li When the request completes, successfully, due to a timeout, or

[246] Fix | Delete

* because it was canceled, a completion event will be sent to 'task'.

[247] Fix | Delete

*

[248] Fix | Delete

* Requires:

[249] Fix | Delete

*

[250] Fix | Delete

*\li 'message' is a valid DNS message.

[251] Fix | Delete

*

[252] Fix | Delete

*\li 'dstaddr' is a valid sockaddr.

[253] Fix | Delete

*

[254] Fix | Delete

*\li 'srcaddr' is a valid sockaddr or NULL.

[255] Fix | Delete

*

[256] Fix | Delete

*\li 'srcaddr' and 'dstaddr' are the same protocol family.

[257] Fix | Delete

*

[258] Fix | Delete

*\li 'timeout' > 0

[259] Fix | Delete

*

[260] Fix | Delete

*\li 'task' is a valid task.

[261] Fix | Delete

*

[262] Fix | Delete

*\li requestp != NULL && *requestp == NULL

[263] Fix | Delete

*/

[264] Fix | Delete

[265] Fix | Delete

/*% See dns_request_createraw4() */

[266] Fix | Delete

isc_result_t

[267] Fix | Delete

dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,

[268] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[269] Fix | Delete

unsigned int options, unsigned int timeout,

[270] Fix | Delete

isc_task_t *task, isc_taskaction_t action, void *arg,

[271] Fix | Delete

dns_request_t **requestp);

[272] Fix | Delete

[273] Fix | Delete

/*% See dns_request_createraw4() */

[274] Fix | Delete

isc_result_t

[275] Fix | Delete

dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,

[276] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[277] Fix | Delete

unsigned int options, unsigned int timeout,

[278] Fix | Delete

unsigned int udptimeout, isc_task_t *task,

[279] Fix | Delete

isc_taskaction_t action, void *arg,

[280] Fix | Delete

dns_request_t **requestp);

[281] Fix | Delete

[282] Fix | Delete

/*% See dns_request_createraw4() */

[283] Fix | Delete

isc_result_t

[284] Fix | Delete

dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,

[285] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[286] Fix | Delete

unsigned int options, unsigned int timeout,

[287] Fix | Delete

unsigned int udptimeout, unsigned int udpretries,

[288] Fix | Delete

isc_task_t *task, isc_taskaction_t action, void *arg,

[289] Fix | Delete

dns_request_t **requestp);

[290] Fix | Delete

[291] Fix | Delete

isc_result_t

[292] Fix | Delete

dns_request_createraw4(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,

[293] Fix | Delete

isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,

[294] Fix | Delete

isc_dscp_t dscp, unsigned int options,

[295] Fix | Delete

unsigned int timeout, unsigned int udptimeout,

[296] Fix | Delete

unsigned int udpretries, isc_task_t *task,

[297] Fix | Delete

isc_taskaction_t action, void *arg,

[298] Fix | Delete

dns_request_t **requestp);

[299] Fix | Delete

/*!<

[300] Fix | Delete

* \brief Create and send a request.

[301] Fix | Delete

*

[302] Fix | Delete

* Notes:

[303] Fix | Delete

*

[304] Fix | Delete

*\li 'msgbuf' will be sent to 'destaddr' after setting the id. If the

[305] Fix | Delete

* #DNS_REQUESTOPT_TCP option is set, TCP will be used,

[306] Fix | Delete

* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP

[307] Fix | Delete

* (vs. connected) will be shared too. The request

[308] Fix | Delete

* will timeout after 'timeout' seconds. UDP requests will be resent

[309] Fix | Delete

* at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.

[310] Fix | Delete

*

[311] Fix | Delete

*\li When the request completes, successfully, due to a timeout, or

[312] Fix | Delete

* because it was canceled, a completion event will be sent to 'task'.

[313] Fix | Delete

*

[314] Fix | Delete

* Requires:

[315] Fix | Delete

*

[316] Fix | Delete

*\li 'msgbuf' is a valid DNS message in compressed wire format.

[317] Fix | Delete

*

[318] Fix | Delete

*\li 'destaddr' is a valid sockaddr.

[319] Fix | Delete

*

[320] Fix | Delete

*\li 'srcaddr' is a valid sockaddr or NULL.

[321] Fix | Delete

*

[322] Fix | Delete

*\li 'srcaddr' and 'dstaddr' are the same protocol family.

[323] Fix | Delete

*

[324] Fix | Delete

*\li 'timeout' > 0

[325] Fix | Delete

*

[326] Fix | Delete

*\li 'task' is a valid task.

[327] Fix | Delete

*

[328] Fix | Delete

*\li requestp != NULL && *requestp == NULL

[329] Fix | Delete

*/

[330] Fix | Delete

[331] Fix | Delete

void

[332] Fix | Delete

dns_request_cancel(dns_request_t *request);

[333] Fix | Delete

/*%<

[334] Fix | Delete

* Cancel 'request'.

[335] Fix | Delete

*

[336] Fix | Delete

* Requires:

[337] Fix | Delete

*

[338] Fix | Delete

*\li 'request' is a valid request.

[339] Fix | Delete

*

[340] Fix | Delete

* Ensures:

[341] Fix | Delete

*

[342] Fix | Delete

*\li If the completion event for 'request' has not yet been sent, it

[343] Fix | Delete

* will be sent, and the result code will be ISC_R_CANCELED.

[344] Fix | Delete

*/

[345] Fix | Delete

[346] Fix | Delete

isc_result_t

[347] Fix | Delete

dns_request_getresponse(dns_request_t *request, dns_message_t *message,

[348] Fix | Delete

unsigned int options);

[349] Fix | Delete

/*%<

[350] Fix | Delete

* Get the response to 'request' by filling in 'message'.

[351] Fix | Delete

*

[352] Fix | Delete

* 'options' is passed to dns_message_parse(). See dns_message_parse()

[353] Fix | Delete

* for more details.

[354] Fix | Delete

*

[355] Fix | Delete

* Requires:

[356] Fix | Delete

*

[357] Fix | Delete

*\li 'request' is a valid request for which the caller has received the

[358] Fix | Delete

* completion event.

[359] Fix | Delete

*

[360] Fix | Delete

*\li The result code of the completion event was #ISC_R_SUCCESS.

[361] Fix | Delete

*

[362] Fix | Delete

* Returns:

[363] Fix | Delete

*

[364] Fix | Delete

*\li ISC_R_SUCCESS

[365] Fix | Delete

*

[366] Fix | Delete

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

[367] Fix | Delete

*/

[368] Fix | Delete

[369] Fix | Delete

bool

[370] Fix | Delete

dns_request_usedtcp(dns_request_t *request);

[371] Fix | Delete

/*%<

[372] Fix | Delete

* Return whether this query used TCP or not. Setting #DNS_REQUESTOPT_TCP

[373] Fix | Delete

* in the call to dns_request_create() will cause the function to return

[374] Fix | Delete

* #true, otherwise the result is based on the query message size.

[375] Fix | Delete

*

[376] Fix | Delete

* Requires:

[377] Fix | Delete

*\li 'request' is a valid request.

[378] Fix | Delete

*

[379] Fix | Delete

* Returns:

[380] Fix | Delete

*\li true if TCP was used.

[381] Fix | Delete

*\li false if UDP was used.

[382] Fix | Delete

*/

[383] Fix | Delete

[384] Fix | Delete

void

[385] Fix | Delete

dns_request_destroy(dns_request_t **requestp);

[386] Fix | Delete

/*%<

[387] Fix | Delete

* Destroy 'request'.

[388] Fix | Delete

*

[389] Fix | Delete

* Requires:

[390] Fix | Delete

*

[391] Fix | Delete

*\li 'request' is a valid request for which the caller has received the

[392] Fix | Delete

* completion event.

[393] Fix | Delete

*

[394] Fix | Delete

* Ensures:

[395] Fix | Delete

*

[396] Fix | Delete

*\li *requestp == NULL

[397] Fix | Delete

*/

[398] Fix | Delete

[399] Fix | Delete

ISC_LANG_ENDDECLS

[400] Fix | Delete

[401] Fix | Delete

#endif /* DNS_REQUEST_H */

[402] Fix | Delete

[403] Fix | Delete