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