xref: /netbsd-src/external/mpl/bind/dist/lib/isccc/include/isccc/ccmsg.h (revision bcda20f65a8566e103791ec395f7f499ef322704)
1 /*	$NetBSD: ccmsg.h,v 1.8 2025/01/26 16:25:44 christos Exp $	*/
2 
3 /*
4  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
5  *
6  * SPDX-License-Identifier: MPL-2.0 AND ISC
7  *
8  * This Source Code Form is subject to the terms of the Mozilla Public
9  * License, v. 2.0. If a copy of the MPL was not distributed with this
10  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
11  *
12  * See the COPYRIGHT file distributed with this work for additional
13  * information regarding copyright ownership.
14  */
15 
16 /*
17  * 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 #pragma once
33 
34 /*! \file isccc/ccmsg.h */
35 
36 #include <inttypes.h>
37 
38 #include <isc/buffer.h>
39 #include <isc/lang.h>
40 #include <isc/netmgr.h>
41 #include <isc/sockaddr.h>
42 
43 #include <isccc/types.h>
44 
45 /*% ISCCC Message Structure */
46 typedef struct isccc_ccmsg {
47 	/* private (don't touch!) */
48 	unsigned int	magic;
49 	uint32_t	size;
50 	isc_buffer_t   *buffer;
51 	unsigned int	maxsize;
52 	isc_mem_t      *mctx;
53 	isc_nmhandle_t *handle;
54 	isc_nm_cb_t	recv_cb;
55 	void	       *recv_cbarg;
56 	isc_nm_cb_t	send_cb;
57 	void	       *send_cbarg;
58 } isccc_ccmsg_t;
59 
60 ISC_LANG_BEGINDECLS
61 
62 void
63 isccc_ccmsg_init(isc_mem_t *mctx, isc_nmhandle_t *handle, isccc_ccmsg_t *ccmsg);
64 /*%
65  * Associate a cc message state with a given memory context and
66  * netmgr handle. (Note that the caller must hold a reference to
67  * the handle during asynchronous ccmsg operations; the ccmsg code
68  * does not hold the reference itself.)
69  *
70  * Requires:
71  *
72  *\li	"mctx" be a valid memory context.
73  *
74  *\li	"handle" be a netmgr handle for a stream socket.
75  *
76  *\li	"ccmsg" be non-NULL and an uninitialized or invalidated structure.
77  *
78  * Ensures:
79  *
80  *\li	"ccmsg" is a valid structure.
81  */
82 
83 void
84 isccc_ccmsg_setmaxsize(isccc_ccmsg_t *ccmsg, unsigned int maxsize);
85 /*%
86  * Set the maximum packet size to "maxsize"
87  *
88  * Requires:
89  *
90  *\li	"ccmsg" be valid.
91  *
92  *\li	512 <= "maxsize" <= 4294967296
93  */
94 
95 void
96 isccc_ccmsg_readmessage(isccc_ccmsg_t *ccmsg, isc_nm_cb_t cb, void *cbarg);
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  * Notes:
106  *
107  *\li	The event delivered is a fully generic event.  It will contain no
108  *	actual data.  The sender will be a pointer to the isccc_ccmsg_t.
109  *	The result code inside that structure should be checked to see
110  *	what the final result was.
111  */
112 
113 void
114 isccc_ccmsg_sendmessage(isccc_ccmsg_t *ccmsg, isc_region_t *region,
115 			isc_nm_cb_t cb, void *cbarg);
116 /*%
117  * Sends region over the command channel message.
118  *
119  * CAVEAT: Only a single send message can be scheduled at the time.
120  */
121 
122 void
123 isccc_ccmsg_disconnect(isccc_ccmsg_t *ccmsg);
124 /*%
125  * Disconnect from the connected netmgr handle associated with a command
126  * channel message.
127  *
128  * Requires:
129  *
130  *\li	"ccmsg" to be valid.
131  */
132 
133 void
134 isccc_ccmsg_invalidate(isccc_ccmsg_t *ccmsg);
135 /*%
136  * Clean up the magic number and the dynamic buffer associated with a command
137  * channel message.
138  *
139  * Requires:
140  *
141  *\li	"ccmsg" to be valid.
142  */
143 
144 void
145 isccc_ccmsg_toregion(isccc_ccmsg_t *ccmsg, isccc_region_t *ccregion);
146 
147 ISC_LANG_ENDDECLS
148