/contrib/bind9/lib/dns/include/dns/request.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 381 lines · 88 code · 27 blank · 266 comment · 0 complexity · 9e88b017f2a5fe919de464441a27f33d MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009, 2010 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 2000-2002 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. /* $Id: request.h,v 1.31 2010/03/04 23:50:34 tbox Exp $ */
  18. #ifndef DNS_REQUEST_H
  19. #define DNS_REQUEST_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/request.h
  24. *
  25. * \brief
  26. * The request module provides simple request/response services useful for
  27. * sending SOA queries, DNS Notify messages, and dynamic update requests.
  28. *
  29. * MP:
  30. *\li The module ensures appropriate synchronization of data structures it
  31. * creates and manipulates.
  32. *
  33. * Resources:
  34. *\li TBS
  35. *
  36. * Security:
  37. *\li No anticipated impact.
  38. */
  39. #include <isc/lang.h>
  40. #include <isc/event.h>
  41. #include <dns/types.h>
  42. #define DNS_REQUESTOPT_TCP 0x00000001U
  43. #define DNS_REQUESTOPT_CASE 0x00000002U
  44. typedef struct dns_requestevent {
  45. ISC_EVENT_COMMON(struct dns_requestevent);
  46. isc_result_t result;
  47. dns_request_t *request;
  48. } dns_requestevent_t;
  49. ISC_LANG_BEGINDECLS
  50. isc_result_t
  51. dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
  52. isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr,
  53. dns_dispatchmgr_t *dispatchmgr,
  54. dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,
  55. dns_requestmgr_t **requestmgrp);
  56. /*%<
  57. * Create a request manager.
  58. *
  59. * Requires:
  60. *
  61. *\li 'mctx' is a valid memory context.
  62. *
  63. *\li 'timermgr' is a valid timer manager.
  64. *
  65. *\li 'socketmgr' is a valid socket manager.
  66. *
  67. *\li 'taskmgr' is a valid task manager.
  68. *
  69. *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
  70. *
  71. *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
  72. *
  73. *\li requestmgrp != NULL && *requestmgrp == NULL
  74. *
  75. * Ensures:
  76. *
  77. *\li On success, *requestmgrp is a valid request manager.
  78. *
  79. * Returns:
  80. *
  81. *\li ISC_R_SUCCESS
  82. *
  83. *\li Any other result indicates failure.
  84. */
  85. void
  86. dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,
  87. isc_event_t **eventp);
  88. /*%<
  89. * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.
  90. *
  91. * Notes:
  92. *
  93. *\li It is not safe to detach the last reference to 'requestmgr' until
  94. * shutdown is complete.
  95. *
  96. * Requires:
  97. *
  98. *\li 'requestmgr' is a valid request manager.
  99. *
  100. *\li 'task' is a valid task.
  101. *
  102. *\li *eventp is a valid event.
  103. *
  104. * Ensures:
  105. *
  106. *\li *eventp == NULL.
  107. */
  108. void
  109. dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);
  110. /*%<
  111. * Start the shutdown process for 'requestmgr'.
  112. *
  113. * Notes:
  114. *
  115. *\li This call has no effect if the request manager is already shutting
  116. * down.
  117. *
  118. * Requires:
  119. *
  120. *\li 'requestmgr' is a valid requestmgr.
  121. */
  122. void
  123. dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);
  124. /*%<
  125. * Attach to the request manager. dns_requestmgr_shutdown() must not
  126. * have been called on 'source' prior to calling dns_requestmgr_attach().
  127. *
  128. * Requires:
  129. *
  130. *\li 'source' is a valid requestmgr.
  131. *
  132. *\li 'targetp' to be non NULL and '*targetp' to be NULL.
  133. */
  134. void
  135. dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
  136. /*%<
  137. * Detach from the given requestmgr. If this is the final detach
  138. * requestmgr will be destroyed. dns_requestmgr_shutdown() must
  139. * be called before the final detach.
  140. *
  141. * Requires:
  142. *
  143. *\li '*requestmgrp' is a valid requestmgr.
  144. *
  145. * Ensures:
  146. *\li '*requestmgrp' is NULL.
  147. */
  148. isc_result_t
  149. dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
  150. isc_sockaddr_t *address, unsigned int options,
  151. dns_tsigkey_t *key,
  152. unsigned int timeout, isc_task_t *task,
  153. isc_taskaction_t action, void *arg,
  154. dns_request_t **requestp);
  155. /*%<
  156. * Create and send a request.
  157. *
  158. * Notes:
  159. *
  160. *\li 'message' will be rendered and sent to 'address'. If the
  161. * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
  162. * will timeout after 'timeout' seconds.
  163. *
  164. *\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
  165. * compression.
  166. *
  167. *\li When the request completes, successfully, due to a timeout, or
  168. * because it was canceled, a completion event will be sent to 'task'.
  169. *
  170. * Requires:
  171. *
  172. *\li 'message' is a valid DNS message.
  173. *
  174. *\li 'address' is a valid sockaddr.
  175. *
  176. *\li 'timeout' > 0
  177. *
  178. *\li 'task' is a valid task.
  179. *
  180. *\li requestp != NULL && *requestp == NULL
  181. */
  182. /*% See dns_request_createvia3() */
  183. isc_result_t
  184. dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,
  185. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  186. unsigned int options, dns_tsigkey_t *key,
  187. unsigned int timeout, isc_task_t *task,
  188. isc_taskaction_t action, void *arg,
  189. dns_request_t **requestp);
  190. /*% See dns_request_createvia3() */
  191. isc_result_t
  192. dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
  193. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  194. unsigned int options, dns_tsigkey_t *key,
  195. unsigned int timeout, unsigned int udptimeout,
  196. isc_task_t *task, isc_taskaction_t action, void *arg,
  197. dns_request_t **requestp);
  198. isc_result_t
  199. dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
  200. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  201. unsigned int options, dns_tsigkey_t *key,
  202. unsigned int timeout, unsigned int udptimeout,
  203. unsigned int udpretries, isc_task_t *task,
  204. isc_taskaction_t action, void *arg,
  205. dns_request_t **requestp);
  206. /*%<
  207. * Create and send a request.
  208. *
  209. * Notes:
  210. *
  211. *\li 'message' will be rendered and sent to 'address'. If the
  212. * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
  213. * will timeout after 'timeout' seconds. UDP requests will be resent
  214. * at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
  215. *
  216. *\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
  217. * compression.
  218. *
  219. *\li When the request completes, successfully, due to a timeout, or
  220. * because it was canceled, a completion event will be sent to 'task'.
  221. *
  222. * Requires:
  223. *
  224. *\li 'message' is a valid DNS message.
  225. *
  226. *\li 'dstaddr' is a valid sockaddr.
  227. *
  228. *\li 'srcaddr' is a valid sockaddr or NULL.
  229. *
  230. *\li 'srcaddr' and 'dstaddr' are the same protocol family.
  231. *
  232. *\li 'timeout' > 0
  233. *
  234. *\li 'task' is a valid task.
  235. *
  236. *\li requestp != NULL && *requestp == NULL
  237. */
  238. /*% See dns_request_createraw3() */
  239. isc_result_t
  240. dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
  241. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  242. unsigned int options, unsigned int timeout,
  243. isc_task_t *task, isc_taskaction_t action, void *arg,
  244. dns_request_t **requestp);
  245. /*% See dns_request_createraw3() */
  246. isc_result_t
  247. dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
  248. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  249. unsigned int options, unsigned int timeout,
  250. unsigned int udptimeout, isc_task_t *task,
  251. isc_taskaction_t action, void *arg,
  252. dns_request_t **requestp);
  253. isc_result_t
  254. dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
  255. isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
  256. unsigned int options, unsigned int timeout,
  257. unsigned int udptimeout, unsigned int udpretries,
  258. isc_task_t *task, isc_taskaction_t action, void *arg,
  259. dns_request_t **requestp);
  260. /*!<
  261. * \brief Create and send a request.
  262. *
  263. * Notes:
  264. *
  265. *\li 'msgbuf' will be sent to 'destaddr' after setting the id. If the
  266. * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
  267. * will timeout after 'timeout' seconds. UDP requests will be resent
  268. * at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
  269. *
  270. *\li When the request completes, successfully, due to a timeout, or
  271. * because it was canceled, a completion event will be sent to 'task'.
  272. *
  273. * Requires:
  274. *
  275. *\li 'msgbuf' is a valid DNS message in compressed wire format.
  276. *
  277. *\li 'destaddr' is a valid sockaddr.
  278. *
  279. *\li 'srcaddr' is a valid sockaddr or NULL.
  280. *
  281. *\li 'srcaddr' and 'dstaddr' are the same protocol family.
  282. *
  283. *\li 'timeout' > 0
  284. *
  285. *\li 'task' is a valid task.
  286. *
  287. *\li requestp != NULL && *requestp == NULL
  288. */
  289. void
  290. dns_request_cancel(dns_request_t *request);
  291. /*%<
  292. * Cancel 'request'.
  293. *
  294. * Requires:
  295. *
  296. *\li 'request' is a valid request.
  297. *
  298. * Ensures:
  299. *
  300. *\li If the completion event for 'request' has not yet been sent, it
  301. * will be sent, and the result code will be ISC_R_CANCELED.
  302. */
  303. isc_result_t
  304. dns_request_getresponse(dns_request_t *request, dns_message_t *message,
  305. unsigned int options);
  306. /*%<
  307. * Get the response to 'request' by filling in 'message'.
  308. *
  309. * 'options' is passed to dns_message_parse(). See dns_message_parse()
  310. * for more details.
  311. *
  312. * Requires:
  313. *
  314. *\li 'request' is a valid request for which the caller has received the
  315. * completion event.
  316. *
  317. *\li The result code of the completion event was #ISC_R_SUCCESS.
  318. *
  319. * Returns:
  320. *
  321. *\li ISC_R_SUCCESS
  322. *
  323. *\li Any result that dns_message_parse() can return.
  324. */
  325. isc_boolean_t
  326. dns_request_usedtcp(dns_request_t *request);
  327. /*%<
  328. * Return whether this query used TCP or not. Setting #DNS_REQUESTOPT_TCP
  329. * in the call to dns_request_create() will cause the function to return
  330. * #ISC_TRUE, otherwise the result is based on the query message size.
  331. *
  332. * Requires:
  333. *\li 'request' is a valid request.
  334. *
  335. * Returns:
  336. *\li ISC_TRUE if TCP was used.
  337. *\li ISC_FALSE if UDP was used.
  338. */
  339. void
  340. dns_request_destroy(dns_request_t **requestp);
  341. /*%<
  342. * Destroy 'request'.
  343. *
  344. * Requires:
  345. *
  346. *\li 'request' is a valid request for which the caller has received the
  347. * completion event.
  348. *
  349. * Ensures:
  350. *
  351. *\li *requestp == NULL
  352. */
  353. ISC_LANG_ENDDECLS
  354. #endif /* DNS_REQUEST_H */