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

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