contrib/bind-9.2.4rc7/lib/dns/include/dns/request.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  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.2.1 2004/03/09 06:11:21 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  * Create and send a request.
 204  *
 205  * Notes:
 206  *
 207  *      'message' will be rendered and sent to 'address'.  If the
 208  *      DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
 209  *      will timeout after 'timeout' seconds.
 210  *
 211  *      When the request completes, successfully, due to a timeout, or
 212  *      because it was canceled, a completion event will be sent to 'task'.
 213  *
 214  * Requires:
 215  *
 216  *      'message' is a valid DNS message.
 217  *
 218  *      'dstaddr' is a valid sockaddr.
 219  *
 220  *      'srcaddr' is a valid sockaddr or NULL.
 221  *
 222  *      'srcaddr' and 'dstaddr' are the same protocol family.
 223  *
 224  *      'timeout' > 0
 225  *
 226  *      'task' is a valid task.
 227  *
 228  *      requestp != NULL && *requestp == NULL
 229  */
 230
 231 isc_result_t
 232 dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
 233                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
 234                       unsigned int options, unsigned int timeout,
 235                       isc_task_t *task, isc_taskaction_t action, void *arg,
 236                       dns_request_t **requestp);
 237 /*
 238  * Create and send a request.
 239  *
 240  * Notes:
 241  *
 242  *      'msgbuf' will be sent to 'destaddr' after setting the id.  If the
 243  *      DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
 244  *      will timeout after 'timeout' seconds.
 245  *
 246  *      When the request completes, successfully, due to a timeout, or
 247  *      because it was canceled, a completion event will be sent to 'task'.
 248  *
 249  * Requires:
 250  *
 251  *      'msgbuf' is a valid DNS message in compressed wire format.
 252  *
 253  *      'destaddr' is a valid sockaddr.
 254  *
 255  *      'srcaddr' is a valid sockaddr or NULL.
 256  *
 257  *      'srcaddr' and 'dstaddr' are the same protocol family.
 258  *
 259  *      'timeout' > 0
 260  *
 261  *      'task' is a valid task.
 262  *
 263  *      requestp != NULL && *requestp == NULL
 264  */
 265
 266 isc_result_t
 267 dns_request_cancel(dns_request_t *request);
 268 /*
 269  * Cancel 'request'.
 270  *
 271  * Requires:
 272  *
 273  *      'request' is a valid request.
 274  *
 275  * Ensures:
 276  *
 277  *      If the completion event for 'request' has not yet been sent, it
 278  *      will be sent, and the result code will be ISC_R_CANCELED.
 279  */
 280
 281 isc_result_t
 282 dns_request_getresponse(dns_request_t *request, dns_message_t *message,
 283                         unsigned int options);
 284 /*
 285  * Get the response to 'request' by filling in 'message'.
 286  *
 287  * 'options' is passed to dns_message_parse().  See dns_message_parse()
 288  * for more details.
 289  *
 290  * Requires:
 291  *
 292  *      'request' is a valid request for which the caller has received the
 293  *      completion event.
 294  *
 295  *      The result code of the completion event was ISC_R_SUCCESS.
 296  *
 297  * Returns:
 298  *
 299  *      ISC_R_SUCCESS
 300  *
 301  *      Any result that dns_message_parse() can return.
 302  */
 303
 304 isc_boolean_t
 305 dns_request_usedtcp(dns_request_t *request);
 306 /*
 307  * Return whether this query used TCP or not.  Setting DNS_REQUESTOPT_TCP
 308  * in the call to dns_request_create() will cause the function to return
 309  * ISC_TRUE, othewise the result is based on the query message size.
 310  *
 311  * Requires:
 312  *      'request' is a valid request.
 313  *
 314  * Returns:
 315  *      ISC_TRUE        if TCP was used.
 316  *      ISC_FALSE       if UDP was used.
 317  */
 318
 319 void
 320 dns_request_destroy(dns_request_t **requestp);
 321 /*
 322  * Destroy 'request'.
 323  *
 324  * Requires:
 325  *
 326  *      'request' is a valid request for which the caller has received the
 327  *      completion event.
 328  *
 329  * Ensures:
 330  *
 331  *      *requestp == NULL
 332  */
 333
 334 ISC_LANG_ENDDECLS
 335
 336 #endif /* DNS_REQUEST_H */