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