chiark - git - mdw - mLib/blob - pkbuf.h

   1 /* -*-c-*-
   2  *
   3  * $Id: pkbuf.h,v 1.3 2001/02/03 16:23:33 mdw Exp $
   4  *
   5  * Simple packet buffering
   6  *
   7  * (c) 2000 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of the mLib utilities library.
  13  *
  14  * mLib is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * mLib is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with mLib; if not, write to the Free
  26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: pkbuf.h,v $
  33  * Revision 1.3  2001/02/03 16:23:33  mdw
  34  * Bug fix: handle a disable during a close-induced flush without dumping
  35  * core.
  36  *
  37  * Revision 1.2  2001/01/20 12:06:01  mdw
  38  * Define flags with macros, to ensure unsignedness.
  39  *
  40  * Revision 1.1  2000/06/17 10:39:19  mdw
  41  * Experimental new support for packet buffering.
  42  *
  43  */
  44
  45 #ifndef MLIB_PKBUF_H
  46 #define MLIB_PKBUF_H
  47
  48 #ifdef __cplusplus
  49   extern "C" {
  50 #endif
  51
  52 /*----- Header files ------------------------------------------------------*/
  53
  54 #include <stddef.h>
  55
  56 #ifndef MLIB_ARENA_H
  57 #  include "arena.h"
  58 #endif
  59
  60 #ifndef MLIB_BITS_H
  61 #  include "bits.h"
  62 #endif
  63
  64 /*----- Data structures ---------------------------------------------------*/
  65
  66 typedef struct pkbuf {
  67   size_t sz;                            /* Size of current buffer */
  68   size_t len;                           /* Length of data in the buffer */
  69   size_t want;                          /* Want this many bytes for packet */
  70   unsigned f;                           /* Various state flags */
  71   void (*func)(octet */*b*/, size_t /*sz*/,
  72                struct pkbuf */*pk*/, size_t */*keep*/,
  73                void */*p*/);            /* Handler function */
  74   void *p;                              /* Argument for handler */
  75   arena *a;                             /* Memory allocation arena */
  76   octet *buf;                           /* Actual buffer space */
  77 } pkbuf;
  78
  79 #define PKBUF_ENABLE 1u                 /* Buffer is currently enabled */
  80 #define PKBUF_CLOSE 2u                  /* Buffer is now closed */
  81
  82 /*----- Functions provided ------------------------------------------------*/
  83
  84 /* --- @pkbuf_flush@ --- *
  85  *
  86  * Arguments:   @pkbuf *pk@ = pointer to buffer block
  87  *              @octet *p@ = pointer to where to start searching
  88  *              @size_t len@ = length of new material added
  89  *
  90  * Returns:     ---
  91  *
  92  * Use:         Flushes any complete packets in a packet buffer.  New
  93  *              material is assumed to have been added starting at @p@.  If
  94  *              @p@ is null, then the scan starts at the beginning of the
  95  *              buffer, and the size of data already in the buffer is used in
  96  *              place of @len@.
  97  *
  98  *              It is assumed that the buffer is initially enabled.  You
  99  *              shouldn't be contributing data to a disabled buffer anyway.
 100  *              However, the buffer handler may at some point disable itself,
 101  *              and @pkbuf_flush@ can cope with this eventuality.  Any
 102  *              pending data is left at the start of the buffer and can be
 103  *              flushed out by calling @pkbuf_flush(b, 0, 0)@ if the buffer
 104  *              is ever re-enabled.
 105  */
 106
 107 extern void pkbuf_flush(pkbuf */*pk*/, octet */*p*/, size_t /*len*/);
 108
 109 /* --- @pkbuf_close@ --- *
 110  *
 111  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 112  *
 113  * Returns:     ---
 114  *
 115  * Use:         Informs the client that no more data is likely to arrive.  If
 116  *              there is a partial packet in the buffer, it is discarded.
 117  */
 118
 119 extern void pkbuf_close(pkbuf */*pk*/);
 120
 121 /* --- @pkbuf_free@ --- *
 122  *
 123  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 124  *              @octet **p@ = output pointer to free space
 125  *
 126  * Returns:     Free buffer size.
 127  *
 128  * Use:         Returns the free portion of a packet buffer.  Data can then
 129  *              be written to this portion, and split out into packets by
 130  *              calling @pkbuf_flush@.
 131  */
 132
 133 extern size_t pkbuf_free(pkbuf */*pk*/, octet **/*p*/);
 134
 135 /* --- @pkbuf_snarf@ --- *
 136  *
 137  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 138  *              @const void *p@ = pointer to input data buffer
 139  *              @size_t sz@ = size of data in input buffer
 140  *
 141  * Returns:     ---
 142  *
 143  * Use:         Snarfs the data from the input buffer and spits it out as
 144  *              packets.  This interface ignores the complexities of dealing
 145  *              with disablement: you should be using @pkbuf_free@ to
 146  *              contribute data if you want to cope with that.
 147  */
 148
 149 extern void pkbuf_snarf(pkbuf */*pk*/, const void */*p*/, size_t /*sz*/);
 150
 151 /* --- @pkbuf_want@ --- *
 152  *
 153  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 154  *              @size_t want@ = how many octets wanted for next packet
 155  *
 156  * Returns:     ---
 157  *
 158  * Use:         Sets the desired size for the next packet to be read.  If
 159  *              it's larger than the current buffer, the buffer is extended.
 160  */
 161
 162 extern void pkbuf_want(pkbuf */*pk*/, size_t /*want*/);
 163
 164 /* --- @pkbuf_init@ --- *
 165  *
 166  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 167  *              @void (*func)(octet *b, size_t sz, pkbuf *pk,@
 168  *                           @size_t *keep, void *p)@ =
 169  *                      handler function
 170  *              @void *p@ = argument pointer for @func@
 171  *
 172  * Returns:     ---
 173  *
 174  * Use:         Initializes a packet buffer block.  Any packets are passed to
 175  *              the provided function for handling.
 176  */
 177
 178 extern void pkbuf_init(pkbuf */*pk*/,
 179                       void (*/*func*/)(octet */*b*/, size_t /*sz*/,
 180                                        pkbuf */*pk*/, size_t */*keep*/,
 181                                        void */*p*/),
 182                       void */*p*/);
 183
 184 /* --- @pkbuf_destroy@ --- *
 185  *
 186  * Arguments:   @pkbuf *pk@ = pointer to buffer block
 187  *
 188  * Returns:     ---
 189  *
 190  * Use:         Deallocates a packet buffer and frees any resources it owned.
 191  */
 192
 193 extern void pkbuf_destroy(pkbuf */*pk*/);
 194
 195 /*----- That's all, folks -------------------------------------------------*/
 196
 197 #ifdef __cplusplus
 198   }
 199 #endif
 200
 201 #endif