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

   1 /* -*-c-*-
   2  *
   3  * $Id: lbuf.h,v 1.1 1999/05/14 21:01:14 mdw Exp $
   4  *
   5  * Block-to-line buffering
   6  *
   7  * (c) 1999 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: lbuf.h,v $
  33  * Revision 1.1  1999/05/14 21:01:14  mdw
  34  * Integrated `select' handling bits from the background resolver project.
  35  *
  36  */
  37
  38 #ifndef LBUF_H
  39 #define LBUF_H
  40
  41 #ifdef __cplusplus
  42   extern "C" {
  43 #endif
  44
  45 /*----- Line buffering ----------------------------------------------------*
  46  *
  47  * The line buffer accepts as input arbitrary-sized lumps of data and
  48  * converts them, by passing them to a client-supplied function, into a
  49  * sequence of lines.  It's particularly useful when performing multiplexed
  50  * network I/O.  It's not normally acceptable to block while waiting for the
  51  * rest of a text line to arrive, for example.  The line buffer stores the
  52  * start of the line until the rest of it arrives later.
  53  *
  54  * A line is a piece of text terminated by either a linefeed or a carriage-
  55  * return/linefeed pair.  (The former is there to cope with Unix; the latter
  56  * copes with Internet-format line ends.)
  57  *
  58  * There's a limit to the size of lines that the buffer can cope with.  It's
  59  * not hard to remove this limit, but it's probably a bad idea in a lot of
  60  * cases, because it'd allow a remote user to gobble arbitrary amounts of
  61  * your memory.  If a line exceeds the limit, it is truncated: the initial
  62  * portion of the line is processed normally, and the remaining portion is
  63  * simply discarded.
  64  *
  65  * Lines extracted from the input data are passed, one at a time, to a
  66  * `handler function', along with a caller-supplied pointer argument to
  67  * provide the handler with some context.  The line read is null-terminated
  68  * and does not include the trailing newline characters.  It is legal for a
  69  * handler function to modify the string it is passed.  However, writing
  70  * beyond the terminating null byte is not allowed.  An end-of-file condition
  71  * is signalled to the handler by passing it a null pointer rather than the
  72  * address of a string.
  73  *
  74  * A complexity arises because of the concept of a `disabled' buffer.
  75  * Disablement is really a higher-level concept, but it turns out to be
  76  * important to implement it here.  It's useful for a line handler function
  77  * to `disable' itself, so that it doesn't get called any more.  For example,
  78  * this might happen if it encouters an error, or when it finishes reading
  79  * everything it wanted to read.  The line buffer needs to be `in the loop'
  80  * so that it stops attempting to flush any further lines stored in its
  81  * buffer towards a handler function which isn't ready to accept them.
  82  * Buffers are initially enabled, although higher- level buffering systems
  83  * might well disable them immediately for their own purposes.
  84  */
  85
  86 /*----- Header files ------------------------------------------------------*/
  87
  88 #include <stddef.h>
  89
  90 /*----- Data structures ---------------------------------------------------*/
  91
  92 /* --- The buffer structure --- *
  93  *
  94  * The only thing that's safe to fiddle with in here is the @lbuf_enable@
  95  * flag.  Only higher-level buffering systems should be playing with even
  96  * that.
  97  */
  98
  99 typedef struct lbuf {
 100   void (*func)(char */*s*/, void */*p*/); /* Handler function */
 101   void *p;                              /* Argument for handler */
 102   size_t len;                           /* Length of data in buffer */
 103   unsigned f;                           /* Various useful state flags */
 104   char buf[256];                        /* The actual buffer */
 105 } lbuf;
 106
 107 enum {
 108   lbuf_cr = 1,                          /* Read a carriage return */
 109   lbuf_enable = 2                       /* Buffer is currently enabled */
 110 };
 111
 112 /*----- Functions provided ------------------------------------------------*/
 113
 114 /* --- @lbuf_flush@ --- *
 115  *
 116  * Arguments:   @lbuf *b@ = pointer to buffer block
 117  *              @char *p@ = pointer to where to start searching
 118  *              @size_t len@ = length of new material added
 119  *
 120  * Returns:     ---
 121  *
 122  * Use:         Flushes any complete lines in a line buffer.  New material
 123  *              is assumed to have been added starting at @p@.  If @p@ is
 124  *              null, then the scan starts at the beginning of the buffer,
 125  *              and the size of data already in the buffer is used in place
 126  *              of @len@.
 127  *
 128  *              It is assumed that the buffer is initially enabled.  You
 129  *              shouldn't be contributing data to a disabled buffer anyway.
 130  *              However, the buffer handler may at some point disable itself,
 131  *              and @lbuf_flush@ can cope with this eventuality.  Any pending
 132  *              data is left at the start of the buffer and can be flushed
 133  *              out by calling @lbuf_flush(b, 0, 0)@ if the buffer is ever
 134  *              re-enabled.
 135  */
 136
 137 extern void lbuf_flush(lbuf */*b*/, char */*p*/, size_t /*len*/);
 138
 139 /* --- @lbuf_close@ --- *
 140  *
 141  * Arguments:   @lbuf *b@ = pointer to buffer block
 142  *
 143  * Returns:     ---
 144  *
 145  * Use:         Empties the buffer of any data currently lurking in it, and
 146  *              informs the client that this has happened.  It's assumed that
 147  *              the buffer is enabled: you shouldn't be reading close events
 148  *              on disabled buffers.
 149  */
 150
 151 extern void lbuf_close(lbuf */*b*/);
 152
 153 /* --- @lbuf_free@ --- *
 154  *
 155  * Arguments:   @lbuf *b@ = pointer to buffer block
 156  *              @char **p@ = output pointer to free space
 157  *
 158  * Returns:     Free buffer size.
 159  *
 160  * Use:         Returns the free portion of a line buffer.  Data can then be
 161  *              written to this portion, and split out into lines by calling
 162  *              @lbuf_flush@.
 163  */
 164
 165 extern size_t lbuf_free(lbuf */*b*/, char **/*p*/);
 166
 167 /* --- @lbuf_snarf@ --- *
 168  *
 169  * Arguments:   @lbuf *b@ = pointer to buffer block
 170  *              @const void *p@ = pointer to input data buffer
 171  *              @size_t sz@ = size of data in input buffer
 172  *
 173  * Returns:     ---
 174  *
 175  * Use:         Snarfs the data from the input buffer and spits it out as
 176  *              lines.  This interface ignores the complexities of dealing
 177  *              with disablement: you should be using @lbuf_free@ to
 178  *              contribute data if you want to cope with that.
 179  */
 180
 181 extern void lbuf_snarf(lbuf */*b*/, const void */*p*/, size_t /*sz*/);
 182
 183 /* --- @lbuf_init@ --- *
 184  *
 185  * Arguments:   @lbuf *b@ = pointer to buffer block
 186  *              @void (*func)(char *s, void *p)@ = handler function
 187  *              @void *p@ = argument pointer for @func@
 188  *
 189  * Returns:     ---
 190  *
 191  * Use:         Initializes a line buffer block.  Any recognized lines are
 192  *              passed to @func@ for processing.
 193  */
 194
 195 extern void lbuf_init(lbuf */*b*/,
 196                       void (*/*func*/)(char */*s*/, void */*p*/),
 197                       void */*p*/);
 198
 199 /*----- That's all, folks -------------------------------------------------*/
 200
 201 #ifdef __cplusplus
 202   }
 203 #endif
 204
 205 #endif