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