Track interface change for @lbuf@.

[mLib] / lbuf.h

/* -*-c-*-
 *
 * $Id: lbuf.h,v 1.7 2002/01/13 13:32:52 mdw Exp $
 *
 * Block-to-line buffering
 *
 * (c) 1999 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: lbuf.h,v $
 * Revision 1.7  2002/01/13 13:32:52  mdw
 * Pass line length to line handler function.  Provide a @typedef@ for
 * handler functions.  Allow run-time configuration of line delimiters.
 *
 * Revision 1.6  2001/02/03 16:23:33  mdw
 * Bug fix: handle a disable during a close-induced flush without dumping
 * core.
 *
 * Revision 1.5  2001/01/20 12:06:01  mdw
 * Define flags with macros, to ensure unsignedness.
 *
 * Revision 1.4  2000/06/17 10:38:14  mdw
 * Add support for variable buffer sizes.
 *
 * Revision 1.3  1999/12/10 23:42:04  mdw
 * Change header file guard names.
 *
 * Revision 1.2  1999/05/17 20:36:08  mdw
 * Make the magical constants for the buffer flags uppercase.
 *
 * Revision 1.1  1999/05/14 21:01:14  mdw
 * Integrated `select' handling bits from the background resolver project.
 *
 */

#ifndef MLIB_LBUF_H
#define MLIB_LBUF_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Line buffering ----------------------------------------------------*
 *
 * The line buffer accepts as input arbitrary-sized lumps of data and
 * converts them, by passing them to a client-supplied function, into a
 * sequence of lines.  It's particularly useful when performing multiplexed
 * network I/O.  It's not normally acceptable to block while waiting for the
 * rest of a text line to arrive, for example.  The line buffer stores the
 * start of the line until the rest of it arrives later.
 *
 * A line is a piece of text terminated by either a linefeed or a carriage-
 * return/linefeed pair.  (The former is there to cope with Unix; the latter
 * copes with Internet-format line ends.)
 *
 * There's a limit to the size of lines that the buffer can cope with.  It's
 * not hard to remove this limit, but it's probably a bad idea in a lot of
 * cases, because it'd allow a remote user to gobble arbitrary amounts of
 * your memory.  If a line exceeds the limit, it is truncated: the initial
 * portion of the line is processed normally, and the remaining portion is
 * simply discarded.
 *
 * Lines extracted from the input data are passed, one at a time, to a
 * `handler function', along with a caller-supplied pointer argument to
 * provide the handler with some context.  The line read is null-terminated
 * and does not include the trailing newline characters.  It is legal for a
 * handler function to modify the string it is passed.  However, writing
 * beyond the terminating null byte is not allowed.  An end-of-file condition
 * is signalled to the handler by passing it a null pointer rather than the
 * address of a string.
 *
 * A complexity arises because of the concept of a `disabled' buffer.
 * Disablement is really a higher-level concept, but it turns out to be
 * important to implement it here.  It's useful for a line handler function
 * to `disable' itself, so that it doesn't get called any more.  For example,
 * this might happen if it encouters an error, or when it finishes reading
 * everything it wanted to read.  The line buffer needs to be `in the loop'
 * so that it stops attempting to flush any further lines stored in its
 * buffer towards a handler function which isn't ready to accept them.
 * Buffers are initially enabled, although higher- level buffering systems
 * might well disable them immediately for their own purposes.
 */

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

#include <stddef.h>

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

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

/* --- The buffer structure --- *
 *
 * The only thing that's safe to fiddle with in here is the @lbuf_enable@
 * flag.  Only higher-level buffering systems should be playing with even
 * that.
 */

struct lbuf;

typedef void lbuf_func(char */*s*/, size_t /*len*/, void */*p*/);

typedef struct lbuf {
  lbuf_func *func;                      /* Handler function */
  void *p;                              /* Argument for handler */
  size_t len;                           /* Length of data in buffer */
  size_t sz;                            /* Buffer size */
  unsigned delim;                       /* Delimiter to look for */
  unsigned f;                           /* Various useful state flags */
  arena *a;                             /* Memory allocation arena */
  char *buf;                            /* The actual buffer */
} lbuf;

#define LBUF_CR 1u                      /* Read a carriage return */
#define LBUF_ENABLE 2u                  /* Buffer is currently enabled */
#define LBUF_CLOSE 4u                   /* Buffer is now closed */

enum {
  LBUF_CRLF = 256,
  LBUF_STRICTCRLF = 257
};

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

/* --- @lbuf_flush@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *              @char *p@ = pointer to where to start searching
 *              @size_t len@ = length of new material added
 *
 * Returns:     ---
 *
 * Use:         Flushes any complete lines in a line 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 @lbuf_flush@ can cope with this eventuality.  Any pending
 *              data is left at the start of the buffer and can be flushed
 *              out by calling @lbuf_flush(b, 0, 0)@ if the buffer is ever
 *              re-enabled.
 */

extern void lbuf_flush(lbuf */*b*/, char */*p*/, size_t /*len*/);

/* --- @lbuf_close@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *
 * Returns:     ---
 *
 * Use:         Empties the buffer of any data currently lurking in it, and
 *              informs the client that this has happened.  It's assumed that
 *              the buffer is enabled: you shouldn't be reading close events
 *              on disabled buffers.
 */

extern void lbuf_close(lbuf */*b*/);

/* --- @lbuf_free@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *              @char **p@ = output pointer to free space
 *
 * Returns:     Free buffer size.
 *
 * Use:         Returns the free portion of a line buffer.  Data can then be
 *              written to this portion, and split out into lines by calling
 *              @lbuf_flush@.
 */

extern size_t lbuf_free(lbuf */*b*/, char **/*p*/);

/* --- @lbuf_snarf@ --- *
 *
 * Arguments:   @lbuf *b@ = 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
 *              lines.  This interface ignores the complexities of dealing
 *              with disablement: you should be using @lbuf_free@ to
 *              contribute data if you want to cope with that.
 */

extern void lbuf_snarf(lbuf */*b*/, const void */*p*/, size_t /*sz*/);

/* --- @lbuf_setsize@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *              @size_t sz@ = requested maximum line size
 *
 * Returns:     ---
 *
 * Use:         Allocates a buffer of the requested size reading lines.
 */

extern void lbuf_setsize(lbuf */*b*/, size_t /*sz*/);

/* --- @lbuf_init@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *              @lbuf_func *func@ = handler function
 *              @void *p@ = argument pointer for @func@
 *
 * Returns:     ---
 *
 * Use:         Initializes a line buffer block.  Any recognized lines are
 *              passed to @func@ for processing.
 */

extern void lbuf_init(lbuf */*b*/, lbuf_func */*func*/, void */*p*/);

/* --- @lbuf_destroy@ --- *
 *
 * Arguments:   @lbuf *b@ = pointer to buffer block
 *
 * Returns:     ---
 *
 * Use:         Deallocates a line buffer and frees any resources it owned.
 */

extern void lbuf_destroy(lbuf */*b*/);

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

#ifdef __cplusplus
  }
#endif

#endif