chiark / gitweb /
buf: Fix two embarassing bugs found while writing Lisp bindings.
[mLib] / pkbuf.h
CommitLineData
436fddaa 1/* -*-c-*-
2 *
8656dc50 3 * $Id: pkbuf.h,v 1.5 2004/04/08 01:36:13 mdw Exp $
436fddaa 4 *
5 * Simple packet buffering
6 *
7 * (c) 2000 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
436fddaa 30#ifndef MLIB_PKBUF_H
31#define MLIB_PKBUF_H
32
33#ifdef __cplusplus
34 extern "C" {
35#endif
36
37/*----- Header files ------------------------------------------------------*/
38
39#include <stddef.h>
40
41#ifndef MLIB_ARENA_H
42# include "arena.h"
43#endif
44
45#ifndef MLIB_BITS_H
46# include "bits.h"
47#endif
48
49/*----- Data structures ---------------------------------------------------*/
50
0daaeb18 51struct pkbuf;
52
53typedef void pkbuf_func(octet */*b*/, size_t /*sz*/,
54 struct pkbuf */*pk*/, size_t */*keep*/,
55 void */*p*/);
56
436fddaa 57typedef struct pkbuf {
58 size_t sz; /* Size of current buffer */
59 size_t len; /* Length of data in the buffer */
60 size_t want; /* Want this many bytes for packet */
61 unsigned f; /* Various state flags */
0daaeb18 62 pkbuf_func *func; /* Handler function */
436fddaa 63 void *p; /* Argument for handler */
64 arena *a; /* Memory allocation arena */
65 octet *buf; /* Actual buffer space */
66} pkbuf;
67
393cf1d9 68#define PKBUF_ENABLE 1u /* Buffer is currently enabled */
3fd896a4 69#define PKBUF_CLOSE 2u /* Buffer is now closed */
436fddaa 70
71/*----- Functions provided ------------------------------------------------*/
72
73/* --- @pkbuf_flush@ --- *
74 *
75 * Arguments: @pkbuf *pk@ = pointer to buffer block
76 * @octet *p@ = pointer to where to start searching
77 * @size_t len@ = length of new material added
78 *
79 * Returns: ---
80 *
81 * Use: Flushes any complete packets in a packet buffer. New
82 * material is assumed to have been added starting at @p@. If
83 * @p@ is null, then the scan starts at the beginning of the
84 * buffer, and the size of data already in the buffer is used in
85 * place of @len@.
86 *
87 * It is assumed that the buffer is initially enabled. You
88 * shouldn't be contributing data to a disabled buffer anyway.
89 * However, the buffer handler may at some point disable itself,
90 * and @pkbuf_flush@ can cope with this eventuality. Any
91 * pending data is left at the start of the buffer and can be
92 * flushed out by calling @pkbuf_flush(b, 0, 0)@ if the buffer
93 * is ever re-enabled.
94 */
95
96extern void pkbuf_flush(pkbuf */*pk*/, octet */*p*/, size_t /*len*/);
97
98/* --- @pkbuf_close@ --- *
99 *
100 * Arguments: @pkbuf *pk@ = pointer to buffer block
101 *
102 * Returns: ---
103 *
104 * Use: Informs the client that no more data is likely to arrive. If
105 * there is a partial packet in the buffer, it is discarded.
106 */
107
108extern void pkbuf_close(pkbuf */*pk*/);
109
110/* --- @pkbuf_free@ --- *
111 *
112 * Arguments: @pkbuf *pk@ = pointer to buffer block
113 * @octet **p@ = output pointer to free space
114 *
115 * Returns: Free buffer size.
116 *
117 * Use: Returns the free portion of a packet buffer. Data can then
118 * be written to this portion, and split out into packets by
119 * calling @pkbuf_flush@.
120 */
121
122extern size_t pkbuf_free(pkbuf */*pk*/, octet **/*p*/);
123
124/* --- @pkbuf_snarf@ --- *
125 *
126 * Arguments: @pkbuf *pk@ = pointer to buffer block
127 * @const void *p@ = pointer to input data buffer
128 * @size_t sz@ = size of data in input buffer
129 *
130 * Returns: ---
131 *
132 * Use: Snarfs the data from the input buffer and spits it out as
133 * packets. This interface ignores the complexities of dealing
134 * with disablement: you should be using @pkbuf_free@ to
135 * contribute data if you want to cope with that.
136 */
137
138extern void pkbuf_snarf(pkbuf */*pk*/, const void */*p*/, size_t /*sz*/);
139
140/* --- @pkbuf_want@ --- *
141 *
142 * Arguments: @pkbuf *pk@ = pointer to buffer block
143 * @size_t want@ = how many octets wanted for next packet
144 *
145 * Returns: ---
146 *
147 * Use: Sets the desired size for the next packet to be read. If
148 * it's larger than the current buffer, the buffer is extended.
149 */
150
151extern void pkbuf_want(pkbuf */*pk*/, size_t /*want*/);
152
153/* --- @pkbuf_init@ --- *
154 *
155 * Arguments: @pkbuf *pk@ = pointer to buffer block
0daaeb18 156 * @pkbuf_func *func@ = handler function
436fddaa 157 * @void *p@ = argument pointer for @func@
158 *
159 * Returns: ---
160 *
161 * Use: Initializes a packet buffer block. Any packets are passed to
162 * the provided function for handling.
163 */
164
0daaeb18 165extern void pkbuf_init(pkbuf */*pk*/, pkbuf_func */*func*/, void */*p*/);
436fddaa 166
167/* --- @pkbuf_destroy@ --- *
168 *
169 * Arguments: @pkbuf *pk@ = pointer to buffer block
170 *
171 * Returns: ---
172 *
173 * Use: Deallocates a packet buffer and frees any resources it owned.
174 */
175
176extern void pkbuf_destroy(pkbuf */*pk*/);
177
178/*----- That's all, folks -------------------------------------------------*/
179
180#ifdef __cplusplus
181 }
182#endif
183
184#endif