request.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2007, 2009, 2010, 2013-2015  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 2000-2002  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id: request.h,v 1.31 2010/03/04 23:50:34 tbox Exp $ */
00019 
00020 #ifndef DNS_REQUEST_H
00021 #define DNS_REQUEST_H 1
00022 
00023 /*****
00024  ***** Module Info
00025  *****/
00026 
00027 /*! \file dns/request.h
00028  *
00029  * \brief
00030  * The request module provides simple request/response services useful for
00031  * sending SOA queries, DNS Notify messages, and dynamic update requests.
00032  *
00033  * MP:
00034  *\li   The module ensures appropriate synchronization of data structures it
00035  *      creates and manipulates.
00036  *
00037  * Resources:
00038  *\li   TBS
00039  *
00040  * Security:
00041  *\li   No anticipated impact.
00042  */
00043 
00044 #include <isc/lang.h>
00045 #include <isc/event.h>
00046 
00047 #include <dns/types.h>
00048 
00049 #define DNS_REQUESTOPT_TCP 0x00000001U
00050 #define DNS_REQUESTOPT_CASE 0x00000002U
00051 #define DNS_REQUESTOPT_FIXEDID 0x00000004U
00052 #define DNS_REQUESTOPT_SHARE 0x00000008U
00053 
00054 typedef struct dns_requestevent {
00055         ISC_EVENT_COMMON(struct dns_requestevent);
00056         isc_result_t result;
00057         dns_request_t *request;
00058 } dns_requestevent_t;
00059 
00060 ISC_LANG_BEGINDECLS
00061 
00062 isc_result_t
00063 dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
00064                       isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr,
00065                       dns_dispatchmgr_t *dispatchmgr,
00066                       dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,
00067                       dns_requestmgr_t **requestmgrp);
00068 /*%<
00069  * Create a request manager.
00070  *
00071  * Requires:
00072  *
00073  *\li   'mctx' is a valid memory context.
00074  *
00075  *\li   'timermgr' is a valid timer manager.
00076  *
00077  *\li   'socketmgr' is a valid socket manager.
00078  *
00079  *\li   'taskmgr' is a valid task manager.
00080  *
00081  *\li   'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
00082  *
00083  *\li   'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
00084  *
00085  *\li   requestmgrp != NULL && *requestmgrp == NULL
00086  *
00087  * Ensures:
00088  *
00089  *\li   On success, *requestmgrp is a valid request manager.
00090  *
00091  * Returns:
00092  *
00093  *\li   ISC_R_SUCCESS
00094  *
00095  *\li   Any other result indicates failure.
00096  */
00097 
00098 void
00099 dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,
00100                             isc_event_t **eventp);
00101 /*%<
00102  * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.
00103  *
00104  * Notes:
00105  *
00106  *\li   It is not safe to detach the last reference to 'requestmgr' until
00107  *      shutdown is complete.
00108  *
00109  * Requires:
00110  *
00111  *\li   'requestmgr' is a valid request manager.
00112  *
00113  *\li   'task' is a valid task.
00114  *
00115  *\li   *eventp is a valid event.
00116  *
00117  * Ensures:
00118  *
00119  *\li   *eventp == NULL.
00120  */
00121 
00122 void
00123 dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);
00124 /*%<
00125  * Start the shutdown process for 'requestmgr'.
00126  *
00127  * Notes:
00128  *
00129  *\li   This call has no effect if the request manager is already shutting
00130  *      down.
00131  *
00132  * Requires:
00133  *
00134  *\li   'requestmgr' is a valid requestmgr.
00135  */
00136 
00137 void
00138 dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);
00139 /*%<
00140  *      Attach to the request manager.  dns_requestmgr_shutdown() must not
00141  *      have been called on 'source' prior to calling dns_requestmgr_attach().
00142  *
00143  * Requires:
00144  *
00145  *\li   'source' is a valid requestmgr.
00146  *
00147  *\li   'targetp' to be non NULL and '*targetp' to be NULL.
00148  */
00149 
00150 void
00151 dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
00152 /*%<
00153  *      Detach from the given requestmgr.  If this is the final detach
00154  *      requestmgr will be destroyed.  dns_requestmgr_shutdown() must
00155  *      be called before the final detach.
00156  *
00157  * Requires:
00158  *
00159  *\li   '*requestmgrp' is a valid requestmgr.
00160  *
00161  * Ensures:
00162  *\li   '*requestmgrp' is NULL.
00163  */
00164 
00165 isc_result_t
00166 dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
00167                    isc_sockaddr_t *address, unsigned int options,
00168                    dns_tsigkey_t *key,
00169                    unsigned int timeout, isc_task_t *task,
00170                    isc_taskaction_t action, void *arg,
00171                    dns_request_t **requestp);
00172 /*%<
00173  * Create and send a request.
00174  *
00175  * Notes:
00176  *
00177  *\li   'message' will be rendered and sent to 'address'.  If the
00178  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used,
00179  *      #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
00180  *      (vs. connected) will be shared too.  The request
00181  *      will timeout after 'timeout' seconds.
00182  *
00183  *\li   If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
00184  *      compression.
00185  *
00186  *\li   When the request completes, successfully, due to a timeout, or
00187  *      because it was canceled, a completion event will be sent to 'task'.
00188  *
00189  * Requires:
00190  *
00191  *\li   'message' is a valid DNS message.
00192  *
00193  *\li   'address' is a valid sockaddr.
00194  *
00195  *\li   'timeout' > 0
00196  *
00197  *\li   'task' is a valid task.
00198  *
00199  *\li   requestp != NULL && *requestp == NULL
00200  */
00201 
00202 /*% See dns_request_createvia4() */
00203 isc_result_t
00204 dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,
00205                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00206                       unsigned int options, dns_tsigkey_t *key,
00207                       unsigned int timeout, isc_task_t *task,
00208                       isc_taskaction_t action, void *arg,
00209                       dns_request_t **requestp);
00210 
00211 /*% See dns_request_createvia4() */
00212 isc_result_t
00213 dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
00214                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00215                        unsigned int options, dns_tsigkey_t *key,
00216                        unsigned int timeout, unsigned int udptimeout,
00217                        isc_task_t *task, isc_taskaction_t action, void *arg,
00218                        dns_request_t **requestp);
00219 
00220 /*% See dns_request_createvia4() */
00221 isc_result_t
00222 dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
00223                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00224                        unsigned int options, dns_tsigkey_t *key,
00225                        unsigned int timeout, unsigned int udptimeout,
00226                        unsigned int udpretries, isc_task_t *task,
00227                        isc_taskaction_t action, void *arg,
00228                        dns_request_t **requestp);
00229 
00230 isc_result_t
00231 dns_request_createvia4(dns_requestmgr_t *requestmgr, dns_message_t *message,
00232                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00233                        isc_dscp_t dscp, unsigned int options,
00234                        dns_tsigkey_t *key, unsigned int timeout,
00235                        unsigned int udptimeout, unsigned int udpretries,
00236                        isc_task_t *task, isc_taskaction_t action, void *arg,
00237                        dns_request_t **requestp);
00238 /*%<
00239  * Create and send a request.
00240  *
00241  * Notes:
00242  *
00243  *\li   'message' will be rendered and sent to 'address'.  If the
00244  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used,
00245  *      #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
00246  *      (vs. connected) will be shared too.  The request
00247  *      will timeout after 'timeout' seconds.  UDP requests will be resent
00248  *      at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
00249  *
00250  *\li   If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
00251  *      compression.
00252  *
00253  *\li   When the request completes, successfully, due to a timeout, or
00254  *      because it was canceled, a completion event will be sent to 'task'.
00255  *
00256  * Requires:
00257  *
00258  *\li   'message' is a valid DNS message.
00259  *
00260  *\li   'dstaddr' is a valid sockaddr.
00261  *
00262  *\li   'srcaddr' is a valid sockaddr or NULL.
00263  *
00264  *\li   'srcaddr' and 'dstaddr' are the same protocol family.
00265  *
00266  *\li   'timeout' > 0
00267  *
00268  *\li   'task' is a valid task.
00269  *
00270  *\li   requestp != NULL && *requestp == NULL
00271  */
00272 
00273 /*% See dns_request_createraw4() */
00274 isc_result_t
00275 dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
00276                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00277                       unsigned int options, unsigned int timeout,
00278                       isc_task_t *task, isc_taskaction_t action, void *arg,
00279                       dns_request_t **requestp);
00280 
00281 /*% See dns_request_createraw4() */
00282 isc_result_t
00283 dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
00284                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00285                        unsigned int options, unsigned int timeout,
00286                        unsigned int udptimeout, isc_task_t *task,
00287                        isc_taskaction_t action, void *arg,
00288                        dns_request_t **requestp);
00289 
00290 /*% See dns_request_createraw4() */
00291 isc_result_t
00292 dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
00293                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00294                        unsigned int options, unsigned int timeout,
00295                        unsigned int udptimeout, unsigned int udpretries,
00296                        isc_task_t *task, isc_taskaction_t action, void *arg,
00297                        dns_request_t **requestp);
00298 
00299 isc_result_t
00300 dns_request_createraw4(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
00301                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
00302                        isc_dscp_t dscp, unsigned int options,
00303                        unsigned int timeout, unsigned int udptimeout,
00304                        unsigned int udpretries, isc_task_t *task,
00305                        isc_taskaction_t action, void *arg,
00306                        dns_request_t **requestp);
00307 /*!<
00308  * \brief Create and send a request.
00309  *
00310  * Notes:
00311  *
00312  *\li   'msgbuf' will be sent to 'destaddr' after setting the id.  If the
00313  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used,
00314  *      #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
00315  *      (vs. connected) will be shared too.  The request
00316  *      will timeout after 'timeout' seconds.   UDP requests will be resent
00317  *      at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
00318  *
00319  *\li   When the request completes, successfully, due to a timeout, or
00320  *      because it was canceled, a completion event will be sent to 'task'.
00321  *
00322  * Requires:
00323  *
00324  *\li   'msgbuf' is a valid DNS message in compressed wire format.
00325  *
00326  *\li   'destaddr' is a valid sockaddr.
00327  *
00328  *\li   'srcaddr' is a valid sockaddr or NULL.
00329  *
00330  *\li   'srcaddr' and 'dstaddr' are the same protocol family.
00331  *
00332  *\li   'timeout' > 0
00333  *
00334  *\li   'task' is a valid task.
00335  *
00336  *\li   requestp != NULL && *requestp == NULL
00337  */
00338 
00339 void
00340 dns_request_cancel(dns_request_t *request);
00341 /*%<
00342  * Cancel 'request'.
00343  *
00344  * Requires:
00345  *
00346  *\li   'request' is a valid request.
00347  *
00348  * Ensures:
00349  *
00350  *\li   If the completion event for 'request' has not yet been sent, it
00351  *      will be sent, and the result code will be ISC_R_CANCELED.
00352  */
00353 
00354 isc_result_t
00355 dns_request_getresponse(dns_request_t *request, dns_message_t *message,
00356                         unsigned int options);
00357 /*%<
00358  * Get the response to 'request' by filling in 'message'.
00359  *
00360  * 'options' is passed to dns_message_parse().  See dns_message_parse()
00361  * for more details.
00362  *
00363  * Requires:
00364  *
00365  *\li   'request' is a valid request for which the caller has received the
00366  *      completion event.
00367  *
00368  *\li   The result code of the completion event was #ISC_R_SUCCESS.
00369  *
00370  * Returns:
00371  *
00372  *\li   ISC_R_SUCCESS
00373  *
00374  *\li   Any result that dns_message_parse() can return.
00375  */
00376 
00377 isc_boolean_t
00378 dns_request_usedtcp(dns_request_t *request);
00379 /*%<
00380  * Return whether this query used TCP or not.  Setting #DNS_REQUESTOPT_TCP
00381  * in the call to dns_request_create() will cause the function to return
00382  * #ISC_TRUE, otherwise the result is based on the query message size.
00383  *
00384  * Requires:
00385  *\li   'request' is a valid request.
00386  *
00387  * Returns:
00388  *\li   ISC_TRUE        if TCP was used.
00389  *\li   ISC_FALSE       if UDP was used.
00390  */
00391 
00392 void
00393 dns_request_destroy(dns_request_t **requestp);
00394 /*%<
00395  * Destroy 'request'.
00396  *
00397  * Requires:
00398  *
00399  *\li   'request' is a valid request for which the caller has received the
00400  *      completion event.
00401  *
00402  * Ensures:
00403  *
00404  *\li   *requestp == NULL
00405  */
00406 
00407 ISC_LANG_ENDDECLS
00408 
00409 #endif /* DNS_REQUEST_H */

Generated on Tue Apr 28 17:40:57 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha