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