+/* -*-c-*-
+ *
+ * $Id: lbuf.h,v 1.1 1999/05/14 21:01:14 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.1 1999/05/14 21:01:14 mdw
+ * Integrated `select' handling bits from the background resolver project.
+ *
+ */
+
+#ifndef LBUF_H
+#define 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>
+
+/*----- 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.
+ */
+
+typedef struct lbuf {
+ void (*func)(char */*s*/, void */*p*/); /* Handler function */
+ void *p; /* Argument for handler */
+ size_t len; /* Length of data in buffer */
+ unsigned f; /* Various useful state flags */
+ char buf[256]; /* The actual buffer */
+} lbuf;
+
+enum {
+ lbuf_cr = 1, /* Read a carriage return */
+ lbuf_enable = 2 /* Buffer is currently enabled */
+};
+
+/*----- 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_init@ --- *
+ *
+ * Arguments: @lbuf *b@ = pointer to buffer block
+ * @void (*func)(char *s, void *p)@ = 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*/,
+ void (*/*func*/)(char */*s*/, void */*p*/),
+ void */*p*/);
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+ }
+#endif
+
+#endif
~mdw / mLib / commitdiff