2 * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: lwbuffer.h,v 1.16.18.2 2005/04/29 00:17:22 marka Exp $ */
23 * A buffer is a region of memory, together with a set of related subregions.
24 * Buffers are used for parsing and I/O operations.
26 * The 'used region' and the 'available' region are disjoint, and their
27 * union is the buffer's region. The used region extends from the beginning
28 * of the buffer region to the last used byte. The available region
29 * extends from one byte greater than the last used byte to the end of the
30 * buffer's region. The size of the used region can be changed using various
31 * buffer commands. Initially, the used region is empty.
33 * The used region is further subdivided into two disjoint regions: the
34 * 'consumed region' and the 'remaining region'. The union of these two
35 * regions is the used region. The consumed region extends from the beginning
36 * of the used region to the byte before the 'current' offset (if any). The
37 * 'remaining' region the current pointer to the end of the used
38 * region. The size of the consumed region can be changed using various
39 * buffer commands. Initially, the consumed region is empty.
41 * The 'active region' is an (optional) subregion of the remaining region.
42 * It extends from the current offset to an offset in the remaining region
43 * that is selected with lwres_buffer_setactive(). Initially, the active
44 * region is empty. If the current offset advances beyond the chosen offset,
45 * the active region will also be empty.
48 * /----- used region -----\/-- available --\
49 * +----------------------------------------+
50 * | consumed | remaining | |
51 * +----------------------------------------+
54 * a == base of buffer.
55 * b == current pointer. Can be anywhere between a and d.
56 * c == active pointer. Meaningful between b and d.
58 * e == length of buffer.
60 * a-e == entire (length) of buffer.
62 * a-b == consumed region.
63 * b-d == remaining region.
64 * b-c == optional active region.
67 * The following invariants are maintained by all routines:
72 * base is a valid pointer to length bytes of memory
76 * 0 <= current <= used
79 * (although active < current implies empty active region)
83 * Buffers have no synchronization. Clients must ensure exclusive
87 * No anticipated impact.
90 * Memory: 1 pointer + 6 unsigned integers per buffer.
93 * No anticipated impact.
99 #ifndef LWRES_LWBUFFER_H
100 #define LWRES_LWBUFFER_H 1
106 #include <lwres/lang.h>
107 #include <lwres/int.h>
109 LWRES_LANG_BEGINDECLS
114 #define LWRES_BUFFER_MAGIC 0x4275663fU /* Buf?. */
116 #define LWRES_BUFFER_VALID(b) ((b) != NULL && \
117 (b)->magic == LWRES_BUFFER_MAGIC)
120 * The following macros MUST be used only on valid buffers. It is the
121 * caller's responsibility to ensure this by using the LWRES_BUFFER_VALID
122 * check above, or by calling another lwres_buffer_*() function (rather than
127 * Get the length of the used region of buffer "b"
129 #define LWRES_BUFFER_USEDCOUNT(b) ((b)->used)
132 * Get the length of the available region of buffer "b"
134 #define LWRES_BUFFER_AVAILABLECOUNT(b) ((b)->length - (b)->used)
136 #define LWRES_BUFFER_REMAINING(b) ((b)->used - (b)->current)
139 * Note that the buffer structure is public. This is principally so buffer
140 * operations can be implemented using macros. Applications are strongly
141 * discouraged from directly manipulating the structure.
144 typedef struct lwres_buffer lwres_buffer_t;
146 * Buffer data structure
148 struct lwres_buffer {
151 /* The following integers are byte offsets from 'base'. */
154 unsigned int current;
163 lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
165 * Make 'b' refer to the 'length'-byte region starting at base.
171 * 'base' is a pointer to a sequence of 'length' bytes.
176 lwres_buffer_invalidate(lwres_buffer_t *b);
178 * Make 'b' an invalid buffer.
181 * 'b' is a valid buffer.
184 * If assertion checking is enabled, future attempts to use 'b' without
185 * calling lwres_buffer_init() on it will cause an assertion failure.
189 lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
191 * Increase the 'used' region of 'b' by 'n' bytes.
195 * 'b' is a valid buffer
202 lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
204 * Decrease the 'used' region of 'b' by 'n' bytes.
208 * 'b' is a valid buffer
215 lwres_buffer_clear(lwres_buffer_t *b);
217 * Make the used region empty.
221 * 'b' is a valid buffer
231 lwres_buffer_first(lwres_buffer_t *b);
233 * Make the consumed region empty.
237 * 'b' is a valid buffer
246 lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
248 * Increase the 'consumed' region of 'b' by 'n' bytes.
252 * 'b' is a valid buffer
254 * current + n <= used
259 lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
261 * Decrease the 'consumed' region of 'b' by 'n' bytes.
265 * 'b' is a valid buffer
272 lwres_buffer_getuint8(lwres_buffer_t *b);
274 * Read an unsigned 8-bit integer from 'b' and return it.
278 * 'b' is a valid buffer.
280 * The length of the available region of 'b' is at least 1.
284 * The current pointer in 'b' is advanced by 1.
288 * A 8-bit unsigned integer.
292 lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
294 * Store an unsigned 8-bit integer from 'val' into 'b'.
297 * 'b' is a valid buffer.
299 * The length of the unused region of 'b' is at least 1.
302 * The used pointer in 'b' is advanced by 1.
306 lwres_buffer_getuint16(lwres_buffer_t *b);
308 * Read an unsigned 16-bit integer in network byte order from 'b', convert
309 * it to host byte order, and return it.
313 * 'b' is a valid buffer.
315 * The length of the available region of 'b' is at least 2.
319 * The current pointer in 'b' is advanced by 2.
323 * A 16-bit unsigned integer.
327 lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
329 * Store an unsigned 16-bit integer in host byte order from 'val'
330 * into 'b' in network byte order.
333 * 'b' is a valid buffer.
335 * The length of the unused region of 'b' is at least 2.
338 * The used pointer in 'b' is advanced by 2.
342 lwres_buffer_getuint32(lwres_buffer_t *b);
344 * Read an unsigned 32-bit integer in network byte order from 'b', convert
345 * it to host byte order, and return it.
349 * 'b' is a valid buffer.
351 * The length of the available region of 'b' is at least 2.
355 * The current pointer in 'b' is advanced by 2.
359 * A 32-bit unsigned integer.
363 lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
365 * Store an unsigned 32-bit integer in host byte order from 'val'
366 * into 'b' in network byte order.
369 * 'b' is a valid buffer.
371 * The length of the unused region of 'b' is at least 4.
374 * The used pointer in 'b' is advanced by 4.
378 lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base,
379 unsigned int length);
381 * Copy 'length' bytes of memory at 'base' into 'b'.
384 * 'b' is a valid buffer.
386 * 'base' points to 'length' bytes of valid memory.
391 lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base,
392 unsigned int length);
394 * Copy 'length' bytes of memory from 'b' into 'base'.
397 * 'b' is a valid buffer.
399 * 'base' points to at least 'length' bytes of valid memory.
401 * 'b' have at least 'length' bytes remaining.
406 #endif /* LWRES_LWBUFFER_H */