/* * Copyright (C) 2004-2007, 2009, 2010 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000-2002 Internet Software Consortium. * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ /* $Id: request.h,v 1.31 2010/03/04 23:50:34 tbox Exp $ */ #ifndef DNS_REQUEST_H #define DNS_REQUEST_H 1 /***** ***** Module Info *****/ /*! \file dns/request.h * * \brief * The request module provides simple request/response services useful for * sending SOA queries, DNS Notify messages, and dynamic update requests. * * MP: *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Resources: *\li TBS * * Security: *\li No anticipated impact. */ #include <isc/lang.h> #include <isc/event.h> #include <dns/types.h> #define DNS_REQUESTOPT_TCP 0x00000001U #define DNS_REQUESTOPT_CASE 0x00000002U typedef struct dns_requestevent { ISC_EVENT_COMMON(struct dns_requestevent); isc_result_t result; dns_request_t *request; } dns_requestevent_t; ISC_LANG_BEGINDECLS isc_result_t dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr, dns_dispatchmgr_t *dispatchmgr, dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6, dns_requestmgr_t **requestmgrp); /*%< * Create a request manager. * * Requires: * *\li 'mctx' is a valid memory context. * *\li 'timermgr' is a valid timer manager. * *\li 'socketmgr' is a valid socket manager. * *\li 'taskmgr' is a valid task manager. * *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. * *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. * *\li requestmgrp != NULL && *requestmgrp == NULL * * Ensures: * *\li On success, *requestmgrp is a valid request manager. * * Returns: * *\li ISC_R_SUCCESS * *\li Any other result indicates failure. */ void dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task, isc_event_t **eventp); /*%< * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown. * * Notes: * *\li It is not safe to detach the last reference to 'requestmgr' until * shutdown is complete. * * Requires: * *\li 'requestmgr' is a valid request manager. * *\li 'task' is a valid task. * *\li *eventp is a valid event. * * Ensures: * *\li *eventp == NULL. */ void dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr); /*%< * Start the shutdown process for 'requestmgr'. * * Notes: * *\li This call has no effect if the request manager is already shutting * down. * * Requires: * *\li 'requestmgr' is a valid requestmgr. */ void dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp); /*%< * Attach to the request manager. dns_requestmgr_shutdown() must not * have been called on 'source' prior to calling dns_requestmgr_attach(). * * Requires: * *\li 'source' is a valid requestmgr. * *\li 'targetp' to be non NULL and '*targetp' to be NULL. */ void dns_requestmgr_detach(dns_requestmgr_t **requestmgrp); /*%< * Detach from the given requestmgr. If this is the final detach * requestmgr will be destroyed. dns_requestmgr_shutdown() must * be called before the final detach. * * Requires: * *\li '*requestmgrp' is a valid requestmgr. * * Ensures: *\li '*requestmgrp' is NULL. */ isc_result_t dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *address, unsigned int options, dns_tsigkey_t *key, unsigned int timeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); /*%< * Create and send a request. * * Notes: * *\li 'message' will be rendered and sent to 'address'. If the * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. * *\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive * compression. * *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * *\li 'message' is a valid DNS message. * *\li 'address' is a valid sockaddr. * *\li 'timeout' > 0 * *\li 'task' is a valid task. * *\li requestp != NULL && *requestp == NULL */ /*% See dns_request_createvia3() */ isc_result_t dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, dns_tsigkey_t *key, unsigned int timeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); /*% See dns_request_createvia3() */ isc_result_t dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, dns_tsigkey_t *key, unsigned int timeout, unsigned int udptimeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); isc_result_t dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, dns_tsigkey_t *key, unsigned int timeout, unsigned int udptimeout, unsigned int udpretries, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); /*%< * Create and send a request. * * Notes: * *\li 'message' will be rendered and sent to 'address'. If the * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. UDP requests will be resent * at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero. * *\li If the #DNS_REQUESTOPT_CASE option is set, use case sensitive * compression. * *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * *\li 'message' is a valid DNS message. * *\li 'dstaddr' is a valid sockaddr. * *\li 'srcaddr' is a valid sockaddr or NULL. * *\li 'srcaddr' and 'dstaddr' are the same protocol family. * *\li 'timeout' > 0 * *\li 'task' is a valid task. * *\li requestp != NULL && *requestp == NULL */ /*% See dns_request_createraw3() */ isc_result_t dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, unsigned int timeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); /*% See dns_request_createraw3() */ isc_result_t dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, unsigned int timeout, unsigned int udptimeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); isc_result_t dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, unsigned int options, unsigned int timeout, unsigned int udptimeout, unsigned int udpretries, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); /*!< * \brief Create and send a request. * * Notes: * *\li 'msgbuf' will be sent to 'destaddr' after setting the id. If the * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. UDP requests will be resent * at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero. * *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * *\li 'msgbuf' is a valid DNS message in compressed wire format. * *\li 'destaddr' is a valid sockaddr. * *\li 'srcaddr' is a valid sockaddr or NULL. * *\li 'srcaddr' and 'dstaddr' are the same protocol family. * *\li 'timeout' > 0 * *\li 'task' is a valid task. * *\li requestp != NULL && *requestp == NULL */ void dns_request_cancel(dns_request_t *request); /*%< * Cancel 'request'. * * Requires: * *\li 'request' is a valid request. * * Ensures: * *\li If the completion event for 'request' has not yet been sent, it * will be sent, and the result code will be ISC_R_CANCELED. */ isc_result_t dns_request_getresponse(dns_request_t *request, dns_message_t *message, unsigned int options); /*%< * Get the response to 'request' by filling in 'message'. * * 'options' is passed to dns_message_parse(). See dns_message_parse() * for more details. * * Requires: * *\li 'request' is a valid request for which the caller has received the * completion event. * *\li The result code of the completion event was #ISC_R_SUCCESS. * * Returns: * *\li ISC_R_SUCCESS * *\li Any result that dns_message_parse() can return. */ isc_boolean_t dns_request_usedtcp(dns_request_t *request); /*%< * Return whether this query used TCP or not. Setting #DNS_REQUESTOPT_TCP * in the call to dns_request_create() will cause the function to return * #ISC_TRUE, otherwise the result is based on the query message size. * * Requires: *\li 'request' is a valid request. * * Returns: *\li ISC_TRUE if TCP was used. *\li ISC_FALSE if UDP was used. */ void dns_request_destroy(dns_request_t **requestp); /*%< * Destroy 'request'. * * Requires: * *\li 'request' is a valid request for which the caller has received the * completion event. * * Ensures: * *\li *requestp == NULL */ ISC_LANG_ENDDECLS #endif /* DNS_REQUEST_H */