1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * SPDX-License-Identifier: MPL-2.0 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 #ifndef DNS_TCPMSG_H 15 #define DNS_TCPMSG_H 1 16 17 /*! \file dns/tcpmsg.h */ 18 19 #include <inttypes.h> 20 21 #include <isc/buffer.h> 22 #include <isc/lang.h> 23 #include <isc/socket.h> 24 25 typedef struct dns_tcpmsg { 26 /* private (don't touch!) */ 27 unsigned int magic; 28 uint16_t size; 29 isc_buffer_t buffer; 30 unsigned int maxsize; 31 isc_mem_t *mctx; 32 isc_socket_t *sock; 33 isc_task_t *task; 34 isc_taskaction_t action; 35 void *arg; 36 isc_event_t event; 37 /* public (read-only) */ 38 isc_result_t result; 39 isc_sockaddr_t address; 40 } dns_tcpmsg_t; 41 42 ISC_LANG_BEGINDECLS 43 44 void 45 dns_tcpmsg_init(isc_mem_t *mctx, isc_socket_t *sock, dns_tcpmsg_t *tcpmsg); 46 /*%< 47 * Associate a tcp message state with a given memory context and 48 * TCP socket. 49 * 50 * Requires: 51 * 52 *\li "mctx" and "sock" be non-NULL and valid types. 53 * 54 *\li "sock" be a read/write TCP socket. 55 * 56 *\li "tcpmsg" be non-NULL and an uninitialized or invalidated structure. 57 * 58 * Ensures: 59 * 60 *\li "tcpmsg" is a valid structure. 61 */ 62 63 void 64 dns_tcpmsg_setmaxsize(dns_tcpmsg_t *tcpmsg, unsigned int maxsize); 65 /*%< 66 * Set the maximum packet size to "maxsize" 67 * 68 * Requires: 69 * 70 *\li "tcpmsg" be valid. 71 * 72 *\li 512 <= "maxsize" <= 65536 73 */ 74 75 isc_result_t 76 dns_tcpmsg_readmessage(dns_tcpmsg_t *tcpmsg, isc_task_t *task, 77 isc_taskaction_t action, void *arg); 78 /*%< 79 * Schedule an event to be delivered when a DNS message is readable, or 80 * when an error occurs on the socket. 81 * 82 * Requires: 83 * 84 *\li "tcpmsg" be valid. 85 * 86 *\li "task", "taskaction", and "arg" be valid. 87 * 88 * Returns: 89 * 90 *\li ISC_R_SUCCESS -- no error 91 *\li Anything that the isc_socket_recv() call can return. XXXMLG 92 * 93 * Notes: 94 * 95 *\li The event delivered is a fully generic event. It will contain no 96 * actual data. The sender will be a pointer to the dns_tcpmsg_t. 97 * The result code inside that structure should be checked to see 98 * what the final result was. 99 */ 100 101 void 102 dns_tcpmsg_cancelread(dns_tcpmsg_t *tcpmsg); 103 /*%< 104 * Cancel a readmessage() call. The event will still be posted with a 105 * CANCELED result code. 106 * 107 * Requires: 108 * 109 *\li "tcpmsg" be valid. 110 */ 111 112 void 113 dns_tcpmsg_keepbuffer(dns_tcpmsg_t *tcpmsg, isc_buffer_t *buffer); 114 /*%< 115 * If a dns buffer is to be kept between calls, this function marks the 116 * internal state-machine buffer as invalid, and copies all the contents 117 * of the state into "buffer". 118 * 119 * Requires: 120 * 121 *\li "tcpmsg" be valid. 122 * 123 *\li "buffer" be non-NULL. 124 */ 125 126 void 127 dns_tcpmsg_invalidate(dns_tcpmsg_t *tcpmsg); 128 /*%< 129 * Clean up all allocated state, and invalidate the structure. 130 * 131 * Requires: 132 * 133 *\li "tcpmsg" be valid. 134 * 135 * Ensures: 136 * 137 *\li "tcpmsg" is invalidated and disassociated with all memory contexts, 138 * sockets, etc. 139 */ 140 141 ISC_LANG_ENDDECLS 142 143 #endif /* DNS_TCPMSG_H */ 144