home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / request.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  10.0 KB  |  375 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  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.21.18.2 2005/04/29 00:16:20 marka Exp $ */
  19.  
  20. #ifndef DNS_REQUEST_H
  21. #define DNS_REQUEST_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  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, othewise 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 */
  375.