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