/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
*
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
*/
#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 <stdbool.h>
#include <isc/event.h>
#include <isc/lang.h>
#include <dns/types.h>
#define DNS_REQUESTOPT_TCP 0x00000001U
#define DNS_REQUESTOPT_CASE 0x00000002U
#define DNS_REQUESTOPT_FIXEDID 0x00000004U
#define DNS_REQUESTOPT_SHARE 0x00000008U
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,
const 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,
* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
* (vs. connected) will be shared too. 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
*/
isc_result_t
dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,
const isc_sockaddr_t *srcaddr,
const isc_sockaddr_t *destaddr, isc_dscp_t dscp,
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,
* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
* (vs. connected) will be shared too. 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
*/
isc_result_t
dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
const isc_sockaddr_t *srcaddr,
const isc_sockaddr_t *destaddr, isc_dscp_t dscp,
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,
* #DNS_REQUESTOPT_SHARE option is set too, connecting TCP
* (vs. connected) will be shared too. 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_buffer_t *
dns_request_getanswer(dns_request_t *request);
/*
* Get the response to 'request' as a buffer.
*
* Requires:
*
*\li 'request' is a valid request for which the caller has received the
* completion event.
*
* Returns:
*
*\li a pointer to the answer buffer.
*/
bool
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
* #true, otherwise the result is based on the query message size.
*
* Requires:
*\li 'request' is a valid request.
*
* Returns:
*\li true if TCP was used.
*\li 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 */
