1/*
2 * Portions Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Portions Copyright (C) 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 AND NOMINUM DISCLAIMS ALL
10 * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
11 * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
12 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 *
17 * Portions Copyright (C) 2001  Nominum, Inc.
18 *
19 * Permission to use, copy, modify, and/or distribute this software for any
20 * purpose with or without fee is hereby granted, provided that the above
21 * copyright notice and this permission notice appear in all copies.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC AND NOMINUM DISCLAIMS ALL
24 * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
25 * OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY
26 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
27 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
28 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
29 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
30 */
31
32/* $Id: ccmsg.h,v 1.11 2007/08/28 07:20:43 tbox Exp $ */
33
34#ifndef ISCCC_CCMSG_H
35#define ISCCC_CCMSG_H 1
36
37/*! \file isccc/ccmsg.h */
38
39#include <isc/buffer.h>
40#include <isc/lang.h>
41#include <isc/socket.h>
42
43/*% ISCCC Message Structure */
44typedef struct isccc_ccmsg {
45	/* private (don't touch!) */
46	unsigned int		magic;
47	isc_uint32_t		size;
48	isc_buffer_t		buffer;
49	unsigned int		maxsize;
50	isc_mem_t	       *mctx;
51	isc_socket_t	       *sock;
52	isc_task_t	       *task;
53	isc_taskaction_t	action;
54	void		       *arg;
55	isc_event_t		event;
56	/* public (read-only) */
57	isc_result_t		result;
58	isc_sockaddr_t		address;
59} isccc_ccmsg_t;
60
61ISC_LANG_BEGINDECLS
62
63void
64isccc_ccmsg_init(isc_mem_t *mctx, isc_socket_t *sock, isccc_ccmsg_t *ccmsg);
65/*%
66 * Associate a cc message state with a given memory context and
67 * TCP socket.
68 *
69 * Requires:
70 *
71 *\li	"mctx" and "sock" be non-NULL and valid types.
72 *
73 *\li	"sock" be a read/write TCP socket.
74 *
75 *\li	"ccmsg" be non-NULL and an uninitialized or invalidated structure.
76 *
77 * Ensures:
78 *
79 *\li	"ccmsg" is a valid structure.
80 */
81
82void
83isccc_ccmsg_setmaxsize(isccc_ccmsg_t *ccmsg, unsigned int maxsize);
84/*%
85 * Set the maximum packet size to "maxsize"
86 *
87 * Requires:
88 *
89 *\li	"ccmsg" be valid.
90 *
91 *\li	512 <= "maxsize" <= 4294967296
92 */
93
94isc_result_t
95isccc_ccmsg_readmessage(isccc_ccmsg_t *ccmsg,
96		       isc_task_t *task, isc_taskaction_t action, void *arg);
97/*%
98 * Schedule an event to be delivered when a command channel message is
99 * readable, or when an error occurs on the socket.
100 *
101 * Requires:
102 *
103 *\li	"ccmsg" be valid.
104 *
105 *\li	"task", "taskaction", and "arg" be valid.
106 *
107 * Returns:
108 *
109 *\li	#ISC_R_SUCCESS		-- no error
110 *\li	Anything that the isc_socket_recv() call can return.  XXXMLG
111 *
112 * Notes:
113 *
114 *\li	The event delivered is a fully generic event.  It will contain no
115 *	actual data.  The sender will be a pointer to the isccc_ccmsg_t.
116 *	The result code inside that structure should be checked to see
117 *	what the final result was.
118 */
119
120void
121isccc_ccmsg_cancelread(isccc_ccmsg_t *ccmsg);
122/*%
123 * Cancel a readmessage() call.  The event will still be posted with a
124 * CANCELED result code.
125 *
126 * Requires:
127 *
128 *\li	"ccmsg" be valid.
129 */
130
131void
132isccc_ccmsg_invalidate(isccc_ccmsg_t *ccmsg);
133/*%
134 * Clean up all allocated state, and invalidate the structure.
135 *
136 * Requires:
137 *
138 *\li	"ccmsg" be valid.
139 *
140 * Ensures:
141 *
142 *\li	"ccmsg" is invalidated and disassociated with all memory contexts,
143 *	sockets, etc.
144 */
145
146ISC_LANG_ENDDECLS
147
148#endif /* ISCCC_CCMSG_H */
149