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

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