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