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

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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.17.12.5 2004/03/08 09:04:39 marka Exp $ */
  19
  20 #ifndef DNS_REQUEST_H
  21 #define DNS_REQUEST_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * DNS Request
  29  *
  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  *      The module ensures appropriate synchronization of data structures it
  35  *      creates and manipulates.
  36  *
  37  * Resources:
  38  *      <TBS>
  39  *
  40  * Security:
  41  *      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  *      'mctx' is a valid memory context.
  71  *
  72  *      'timermgr' is a valid timer manager.
  73  *
  74  *      'socketmgr' is a valid socket manager.
  75  *
  76  *      'taskmgr' is a valid task manager.
  77  *
  78  *      'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
  79  *
  80  *      'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
  81  *
  82  *      requestmgrp != NULL && *requestmgrp == NULL
  83  *
  84  * Ensures:
  85  *
  86  *      On success, *requestmgrp is a valid request manager.
  87  *
  88  * Returns:
  89  *
  90  *      ISC_R_SUCCESS
  91  *
  92  *      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  *      It is not safe to detach the last reference to 'requestmgr' until
 104  *      shutdown is complete.
 105  *
 106  * Requires:
 107  *
 108  *      'requestmgr' is a valid request manager.
 109  *
 110  *      'task' is a valid task.
 111  *
 112  *      *eventp is a valid event.
 113  *
 114  * Ensures:
 115  *
 116  *      *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  *      This call has no effect if the request manager is already shutting
 127  *      down.
 128  *
 129  * Requires:
 130  *
 131  *      '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  *      'source' is a valid requestmgr.
 143  *
 144  *      'targetp' to be non NULL and '*targetp' to be NULL.
 145  */
 146
 147 void
 148 dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
 149 /*
 150  *
 151  *      Detach from the given requestmgr.  If this is the final detach
 152  *      requestmgr will be destroyed.  dns_requestmgr_shutdown() must
 153  *      be called before the final detach.
 154  *
 155  * Requires:
 156  *
 157  *      '*requestmgrp' is a valid requestmgr.
 158  *
 159  * Ensures:
 160  *      '*requestmgrp' is NULL.
 161  */
 162
 163 isc_result_t
 164 dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
 165                    isc_sockaddr_t *address, unsigned int options,
 166                    dns_tsigkey_t *key,
 167                    unsigned int timeout, isc_task_t *task,
 168                    isc_taskaction_t action, void *arg,
 169                    dns_request_t **requestp);
 170 /*
 171  * Create and send a request.
 172  *
 173  * Notes:
 174  *
 175  *      'message' will be rendered and sent to 'address'.  If the
 176  *      DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
 177  *      will timeout after 'timeout' seconds.
 178  *
 179  *      When the request completes, successfully, due to a timeout, or
 180  *      because it was canceled, a completion event will be sent to 'task'.
 181  *
 182  * Requires:
 183  *
 184  *      'message' is a valid DNS message.
 185  *
 186  *      'address' is a valid sockaddr.
 187  *
 188  *      'timeout' > 0
 189  *
 190  *      'task' is a valid task.
 191  *
 192  *      requestp != NULL && *requestp == NULL
 193  */
 194
 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 isc_result_t
 204 dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
 205                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 206                        unsigned int options, dns_tsigkey_t *key,
 207                        unsigned int timeout, unsigned int udptimeout,
 208                        isc_task_t *task, isc_taskaction_t action, void *arg,
 209                        dns_request_t **requestp);
 210
 211 isc_result_t
 212 dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
 213                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 214                        unsigned int options, dns_tsigkey_t *key,
 215                        unsigned int timeout, unsigned int udptimeout,
 216                        unsigned int udpretries, isc_task_t *task,
 217                        isc_taskaction_t action, void *arg,
 218                        dns_request_t **requestp);
 219 /*
 220  * Create and send a request.
 221  *
 222  * Notes:
 223  *
 224  *      'message' will be rendered and sent to 'address'.  If the
 225  *      DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
 226  *      will timeout after 'timeout' seconds.  UDP requests will be resent
 227  *      at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
 228  *
 229  *      When the request completes, successfully, due to a timeout, or
 230  *      because it was canceled, a completion event will be sent to 'task'.
 231  *
 232  * Requires:
 233  *
 234  *      'message' is a valid DNS message.
 235  *
 236  *      'dstaddr' is a valid sockaddr.
 237  *
 238  *      'srcaddr' is a valid sockaddr or NULL.
 239  *
 240  *      'srcaddr' and 'dstaddr' are the same protocol family.
 241  *
 242  *      'timeout' > 0
 243  *
 244  *      'task' is a valid task.
 245  *
 246  *      requestp != NULL && *requestp == NULL
 247  */
 248
 249 isc_result_t
 250 dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
 251                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 252                       unsigned int options, unsigned int timeout,
 253                       isc_task_t *task, isc_taskaction_t action, void *arg,
 254                       dns_request_t **requestp);
 255
 256 isc_result_t
 257 dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
 258                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 259                        unsigned int options, unsigned int timeout,
 260                        unsigned int udptimeout, isc_task_t *task,
 261                        isc_taskaction_t action, void *arg,
 262                        dns_request_t **requestp);
 263
 264 isc_result_t
 265 dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
 266                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 267                        unsigned int options, unsigned int timeout,
 268                        unsigned int udptimeout, unsigned int udpretries,
 269                        isc_task_t *task, isc_taskaction_t action, void *arg,
 270                        dns_request_t **requestp);
 271 /*
 272  * Create and send a request.
 273  *
 274  * Notes:
 275  *
 276  *      'msgbuf' will be sent to 'destaddr' after setting the id.  If the
 277  *      DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
 278  *      will timeout after 'timeout' seconds.   UDP requests will be resent
 279  *      at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
 280  *
 281  *      When the request completes, successfully, due to a timeout, or
 282  *      because it was canceled, a completion event will be sent to 'task'.
 283  *
 284  * Requires:
 285  *
 286  *      'msgbuf' is a valid DNS message in compressed wire format.
 287  *
 288  *      'destaddr' is a valid sockaddr.
 289  *
 290  *      'srcaddr' is a valid sockaddr or NULL.
 291  *
 292  *      'srcaddr' and 'dstaddr' are the same protocol family.
 293  *
 294  *      'timeout' > 0
 295  *
 296  *      'task' is a valid task.
 297  *
 298  *      requestp != NULL && *requestp == NULL
 299  */
 300
 301 void
 302 dns_request_cancel(dns_request_t *request);
 303 /*
 304  * Cancel 'request'.
 305  *
 306  * Requires:
 307  *
 308  *      'request' is a valid request.
 309  *
 310  * Ensures:
 311  *
 312  *      If the completion event for 'request' has not yet been sent, it
 313  *      will be sent, and the result code will be ISC_R_CANCELED.
 314  */
 315
 316 isc_result_t
 317 dns_request_getresponse(dns_request_t *request, dns_message_t *message,
 318                         unsigned int options);
 319 /*
 320  * Get the response to 'request' by filling in 'message'.
 321  *
 322  * 'options' is passed to dns_message_parse().  See dns_message_parse()
 323  * for more details.
 324  *
 325  * Requires:
 326  *
 327  *      'request' is a valid request for which the caller has received the
 328  *      completion event.
 329  *
 330  *      The result code of the completion event was ISC_R_SUCCESS.
 331  *
 332  * Returns:
 333  *
 334  *      ISC_R_SUCCESS
 335  *
 336  *      Any result that dns_message_parse() can return.
 337  */
 338
 339 isc_boolean_t
 340 dns_request_usedtcp(dns_request_t *request);
 341 /*
 342  * Return whether this query used TCP or not.  Setting DNS_REQUESTOPT_TCP
 343  * in the call to dns_request_create() will cause the function to return
 344  * ISC_TRUE, othewise the result is based on the query message size.
 345  *
 346  * Requires:
 347  *      'request' is a valid request.
 348  *
 349  * Returns:
 350  *      ISC_TRUE        if TCP was used.
 351  *      ISC_FALSE       if UDP was used.
 352  */
 353
 354 void
 355 dns_request_destroy(dns_request_t **requestp);
 356 /*
 357  * Destroy 'request'.
 358  *
 359  * Requires:
 360  *
 361  *      'request' is a valid request for which the caller has received the
 362  *      completion event.
 363  *
 364  * Ensures:
 365  *
 366  *      *requestp == NULL
 367  */
 368
 369 ISC_LANG_ENDDECLS
 370
 371 #endif /* DNS_REQUEST_H */