New interface for messing with preconnected sockets.

[mLib] / pkbuf.h

/* -*-c-*-
 *
 * $Id: pkbuf.h,v 1.4 2002/01/13 13:33:51 mdw Exp $
 *
 * Simple packet buffering
 *
 * (c) 2000 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * mLib is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with mLib; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: pkbuf.h,v $
 * Revision 1.4  2002/01/13 13:33:51  mdw
 * Packet handler functions now have a @typedef@ name.
 *
 * Revision 1.3  2001/02/03 16:23:33  mdw
 * Bug fix: handle a disable during a close-induced flush without dumping
 * core.
 *
 * Revision 1.2  2001/01/20 12:06:01  mdw
 * Define flags with macros, to ensure unsignedness.
 *
 * Revision 1.1  2000/06/17 10:39:19  mdw
 * Experimental new support for packet buffering.
 *
 */

#ifndef MLIB_PKBUF_H
#define MLIB_PKBUF_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#ifndef MLIB_ARENA_H
#  include "arena.h"
#endif

#ifndef MLIB_BITS_H
#  include "bits.h"
#endif

/*----- Data structures ---------------------------------------------------*/

struct pkbuf;

typedef void pkbuf_func(octet */*b*/, size_t /*sz*/,
			struct pkbuf */*pk*/, size_t */*keep*/,
			void */*p*/);

typedef struct pkbuf {
  size_t sz;				/* Size of current buffer */
  size_t len;				/* Length of data in the buffer */
  size_t want;				/* Want this many bytes for packet */
  unsigned f;				/* Various state flags */
  pkbuf_func *func;			/* Handler function */
  void *p;				/* Argument for handler */
  arena *a;				/* Memory allocation arena */
  octet *buf;				/* Actual buffer space */
} pkbuf;

#define PKBUF_ENABLE 1u			/* Buffer is currently enabled */
#define PKBUF_CLOSE 2u			/* Buffer is now closed */

/*----- Functions provided ------------------------------------------------*/

/* --- @pkbuf_flush@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *		@octet *p@ = pointer to where to start searching
 *		@size_t len@ = length of new material added
 *
 * Returns:	---
 *
 * Use:		Flushes any complete packets in a packet buffer.  New
 *		material is assumed to have been added starting at @p@.  If
 *		@p@ is null, then the scan starts at the beginning of the
 *		buffer, and the size of data already in the buffer is used in
 *		place of @len@.
 *
 *		It is assumed that the buffer is initially enabled.  You
 *		shouldn't be contributing data to a disabled buffer anyway.
 *		However, the buffer handler may at some point disable itself,
 *		and @pkbuf_flush@ can cope with this eventuality.  Any
 *		pending data is left at the start of the buffer and can be
 *		flushed out by calling @pkbuf_flush(b, 0, 0)@ if the buffer
 *		is ever re-enabled.
 */

extern void pkbuf_flush(pkbuf */*pk*/, octet */*p*/, size_t /*len*/);

/* --- @pkbuf_close@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *
 * Returns:	---
 *
 * Use:		Informs the client that no more data is likely to arrive.  If
 *		there is a partial packet in the buffer, it is discarded.
 */

extern void pkbuf_close(pkbuf */*pk*/);

/* --- @pkbuf_free@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *		@octet **p@ = output pointer to free space
 *
 * Returns:	Free buffer size.
 *
 * Use:		Returns the free portion of a packet buffer.  Data can then
 *		be written to this portion, and split out into packets by
 *		calling	@pkbuf_flush@.
 */

extern size_t pkbuf_free(pkbuf */*pk*/, octet **/*p*/);

/* --- @pkbuf_snarf@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *		@const void *p@ = pointer to input data buffer
 *		@size_t sz@ = size of data in input buffer
 *
 * Returns:	---
 *
 * Use:		Snarfs the data from the input buffer and spits it out as
 *		packets.  This interface ignores the complexities of dealing
 *		with disablement: you should be using @pkbuf_free@ to
 *		contribute data if you want to cope with that.
 */

extern void pkbuf_snarf(pkbuf */*pk*/, const void */*p*/, size_t /*sz*/);

/* --- @pkbuf_want@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *		@size_t want@ = how many octets wanted for next packet
 *
 * Returns:	---
 *
 * Use:		Sets the desired size for the next packet to be read.  If
 *		it's larger than the current buffer, the buffer is extended.
 */

extern void pkbuf_want(pkbuf */*pk*/, size_t /*want*/);

/* --- @pkbuf_init@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *		@pkbuf_func *func@ = handler function
 *		@void *p@ = argument pointer for @func@
 *
 * Returns:	---
 *
 * Use:		Initializes a packet buffer block.  Any packets are passed to
 *		the provided function for handling.
 */

extern void pkbuf_init(pkbuf */*pk*/, pkbuf_func */*func*/, void */*p*/);

/* --- @pkbuf_destroy@ --- *
 *
 * Arguments:	@pkbuf *pk@ = pointer to buffer block
 *
 * Returns:	---
 *
 * Use:		Deallocates a packet buffer and frees any resources it owned.
 */

extern void pkbuf_destroy(pkbuf */*pk*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif