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

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