|
1 /* |
|
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
|
3 * |
|
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. |
|
5 * |
|
6 * Redistribution and use in source and binary forms, with or without |
|
7 * modification, are permitted provided that the following conditions are met: |
|
8 * |
|
9 * 1. Redistributions of source code must retain the above copyright |
|
10 * notice, this list of conditions and the following disclaimer. |
|
11 * |
|
12 * 2. Redistributions in binary form must reproduce the above copyright |
|
13 * notice, this list of conditions and the following disclaimer in the |
|
14 * documentation and/or other materials provided with the distribution. |
|
15 * |
|
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
|
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
|
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
|
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
|
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
|
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
|
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
|
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
|
26 * POSSIBILITY OF SUCH DAMAGE. |
|
27 */ |
|
28 |
|
29 /** |
|
30 * \file buffer.h |
|
31 * |
|
32 * \brief Advanced buffer implementation. |
|
33 * |
|
34 * Instances of CxBuffer can be used to read from or to write to like one |
|
35 * would do with a stream. |
|
36 * |
|
37 * Some features for convenient use of the buffer |
|
38 * can be enabled. See the documentation of the macro constants for more |
|
39 * information. |
|
40 * |
|
41 * \author Mike Becker |
|
42 * \author Olaf Wintermann |
|
43 * \version 3.0 |
|
44 * \copyright 2-Clause BSD License |
|
45 */ |
|
46 |
|
47 #ifndef UCX_BUFFER_H |
|
48 #define UCX_BUFFER_H |
|
49 |
|
50 #include <sys/types.h> |
|
51 #include <stdio.h> |
|
52 |
|
53 #ifdef __cplusplus |
|
54 extern "C" { |
|
55 #endif |
|
56 |
|
57 /** |
|
58 * No buffer features enabled (all flags cleared). |
|
59 */ |
|
60 #define CX_BUFFER_DEFAULT 0x00 |
|
61 |
|
62 /** |
|
63 * If this flag is enabled, the buffer will automatically free its contents when destroyed. |
|
64 */ |
|
65 #define CX_BUFFER_FREE_CONTENTS 0x01 |
|
66 |
|
67 /** |
|
68 * If this flag is enabled, the buffer will automatically extends its capacity. |
|
69 */ |
|
70 #define CX_BUFFER_AUTO_EXTEND 0x02 |
|
71 |
|
72 /** Structure for the UCX buffer data. */ |
|
73 typedef struct { |
|
74 /** A pointer to the buffer contents. */ |
|
75 union { |
|
76 /** |
|
77 * Data is interpreted as text. |
|
78 */ |
|
79 char *space; |
|
80 /** |
|
81 * Data is interpreted as binary. |
|
82 */ |
|
83 unsigned char *bytes; |
|
84 }; |
|
85 /** Current position of the buffer. */ |
|
86 size_t pos; |
|
87 /** Current capacity (i.e. maximum size) of the buffer. */ |
|
88 size_t capacity; |
|
89 /** Current size of the buffer content. */ |
|
90 size_t size; |
|
91 /** |
|
92 * Flag register for buffer features. |
|
93 * \see #CX_BUFFER_DEFAULT |
|
94 * \see #CX_BUFFER_FREE_CONTENTS |
|
95 * \see #CX_BUFFER_AUTO_EXTEND |
|
96 */ |
|
97 int flags; |
|
98 } cx_buffer_s; |
|
99 |
|
100 /** |
|
101 * UCX buffer. |
|
102 */ |
|
103 typedef cx_buffer_s *CxBuffer; |
|
104 |
|
105 /** |
|
106 * Creates a new buffer. |
|
107 * |
|
108 * \note You may provide \c NULL as argument for \p space. |
|
109 * Then this function will allocate the space and enforce |
|
110 * the #CX_BUFFER_FREE_CONTENTS flag. |
|
111 * |
|
112 * \param space pointer to the memory area, or <code>NULL</code> to allocate |
|
113 * new memory |
|
114 * \param capacity the capacity of the buffer |
|
115 * \param flags buffer features (see cx_buffer_s.flags) |
|
116 * \return the new buffer |
|
117 */ |
|
118 CxBuffer cxBufferCreate( |
|
119 void *space, |
|
120 size_t capacity, |
|
121 int flags |
|
122 ); |
|
123 |
|
124 /** |
|
125 * Destroys a buffer. |
|
126 * |
|
127 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer |
|
128 * are also freed. |
|
129 * |
|
130 * \param buffer the buffer to destroy |
|
131 */ |
|
132 void cxBufferDestroy(CxBuffer buffer); |
|
133 |
|
134 /** |
|
135 * Creates a new buffer and fills it with content copied from another buffer. |
|
136 * |
|
137 * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer. |
|
138 * |
|
139 * \param src the source buffer |
|
140 * \param start the start position of extraction |
|
141 * \param length the count of bytes to extract (must not be zero) |
|
142 * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
|
143 * \return a new buffer containing the extraction |
|
144 */ |
|
145 CxBuffer cxBufferExtract( |
|
146 CxBuffer src, |
|
147 size_t start, |
|
148 size_t length, |
|
149 int flags |
|
150 ); |
|
151 |
|
152 /** |
|
153 * A shorthand macro for copying an entire buffer. |
|
154 * |
|
155 * \param src the source buffer |
|
156 * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) |
|
157 * \return a new buffer with the copied content |
|
158 */ |
|
159 #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags) |
|
160 |
|
161 |
|
162 /** |
|
163 * Shifts the contents of the buffer by the given offset. |
|
164 * |
|
165 * If the offset is positive, the contents are shifted to the right. |
|
166 * If auto extension is enabled, the buffer grows, if necessary. |
|
167 * In case the auto extension fails, this function returns a non-zero value and |
|
168 * no contents are changed. |
|
169 * If auto extension is disabled, the contents that do not fit into the buffer |
|
170 * are discarded. |
|
171 * |
|
172 * If the offset is negative, the contents are shifted to the left where the |
|
173 * first \p shift bytes are discarded. |
|
174 * The new size of the buffer is the old size minus the absolute shift value. |
|
175 * If this value is larger than the buffer size, the buffer is emptied (but |
|
176 * not cleared, see the security note below). |
|
177 * |
|
178 * The buffer position gets shifted alongside with the content but is kept |
|
179 * within the boundaries of the buffer. |
|
180 * |
|
181 * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and |
|
182 * cxBufferShiftRight() functions using a \c size_t as parameter type. |
|
183 * |
|
184 * \par Security Note |
|
185 * The shifting operation does \em not erase the previously occupied memory cells. |
|
186 * You can easily do that manually, e.g. by calling |
|
187 * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or |
|
188 * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code> |
|
189 * for a left shift. |
|
190 * |
|
191 * \param buffer the buffer |
|
192 * \param shift the shift offset (negative means left shift) |
|
193 * \return 0 on success, non-zero if a required auto-extension fails |
|
194 */ |
|
195 int cxBufferShift( |
|
196 CxBuffer buffer, |
|
197 off_t shift |
|
198 ); |
|
199 |
|
200 /** |
|
201 * Shifts the buffer to the right. |
|
202 * See cxBufferShift() for details. |
|
203 * |
|
204 * \param buffer the buffer |
|
205 * \param shift the shift offset |
|
206 * \return 0 on success, non-zero if a required auto-extension fails |
|
207 * \see cxBufferShift() |
|
208 */ |
|
209 int cxBufferShiftRight( |
|
210 CxBuffer buffer, |
|
211 size_t shift |
|
212 ); |
|
213 |
|
214 /** |
|
215 * Shifts the buffer to the left. |
|
216 * See cxBufferShift() for details. |
|
217 * |
|
218 * \note Since a left shift cannot fail due to memory allocation problems, this |
|
219 * function always returns zero. |
|
220 * |
|
221 * \param buffer the buffer |
|
222 * \param shift the positive shift offset |
|
223 * \return always zero |
|
224 * \see cxBufferShift() |
|
225 */ |
|
226 int cxBufferShiftLeft( |
|
227 CxBuffer buffer, |
|
228 size_t shift |
|
229 ); |
|
230 |
|
231 |
|
232 /** |
|
233 * Moves the position of the buffer. |
|
234 * |
|
235 * The new position is relative to the \p whence argument. |
|
236 * |
|
237 * \li \c SEEK_SET marks the start of the buffer. |
|
238 * \li \c SEEK_CUR marks the current position. |
|
239 * \li \c SEEK_END marks the end of the buffer. |
|
240 * |
|
241 * With an offset of zero, this function sets the buffer position to zero |
|
242 * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position |
|
243 * unchanged (\c SEEK_CUR). |
|
244 * |
|
245 * \param buffer the buffer |
|
246 * \param offset position offset relative to \p whence |
|
247 * \param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END |
|
248 * \return 0 on success, non-zero if the position is invalid |
|
249 * |
|
250 */ |
|
251 int cxBufferSeek( |
|
252 CxBuffer buffer, |
|
253 off_t offset, |
|
254 int whence |
|
255 ); |
|
256 |
|
257 /** |
|
258 * Clears the buffer by resetting the position and deleting the data. |
|
259 * |
|
260 * The data is deleted by zeroing it with a call to memset(). |
|
261 * |
|
262 * \param buffer the buffer to be cleared |
|
263 */ |
|
264 #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \ |
|
265 (buffer)->size = 0; (buffer)->pos = 0; |
|
266 |
|
267 /** |
|
268 * Tests, if the buffer position has exceeded the buffer capacity. |
|
269 * |
|
270 * \param buffer the buffer to test |
|
271 * \return non-zero, if the current buffer position has exceeded the last |
|
272 * available byte of the buffer. |
|
273 */ |
|
274 int cxBufferEof(CxBuffer buffer); |
|
275 |
|
276 |
|
277 /** |
|
278 * Ensures that the buffer has a minimum capacity. |
|
279 * |
|
280 * If the current capacity is not sufficient, the buffer will be extended. |
|
281 * |
|
282 * \param buffer the buffer |
|
283 * \param capacity the minimum required capacity for this buffer |
|
284 * \return 0 on success or a non-zero value on failure |
|
285 */ |
|
286 int cxBufferMinimumCapacity( |
|
287 CxBuffer buffer, |
|
288 size_t capacity |
|
289 ); |
|
290 |
|
291 /** |
|
292 * Writes data to a CxBuffer. |
|
293 * |
|
294 * The position of the buffer is increased by the number of bytes written. |
|
295 * |
|
296 * \note The signature is compatible with the fwrite() family of functions. |
|
297 * |
|
298 * \param ptr a pointer to the memory area containing the bytes to be written |
|
299 * \param size the length of one element |
|
300 * \param nitems the element count |
|
301 * \param buffer the CxBuffer to write to |
|
302 * \return the total count of bytes written |
|
303 */ |
|
304 size_t cxBufferWrite( |
|
305 const void *ptr, |
|
306 size_t size, |
|
307 size_t nitems, |
|
308 CxBuffer buffer |
|
309 ); |
|
310 |
|
311 /** |
|
312 * Reads data from a CxBuffer. |
|
313 * |
|
314 * The position of the buffer is increased by the number of bytes read. |
|
315 * |
|
316 * \note The signature is compatible with the fread() family of functions. |
|
317 * |
|
318 * \param ptr a pointer to the memory area where to store the read data |
|
319 * \param size the length of one element |
|
320 * \param nitems the element count |
|
321 * \param buffer the CxBuffer to read from |
|
322 * \return the total number of elements read |
|
323 */ |
|
324 size_t cxBufferRead( |
|
325 void *ptr, |
|
326 size_t size, |
|
327 size_t nitems, |
|
328 CxBuffer buffer |
|
329 ); |
|
330 |
|
331 /** |
|
332 * Writes a character to a buffer. |
|
333 * |
|
334 * The least significant byte of the argument is written to the buffer. If the |
|
335 * end of the buffer is reached and #CX_BUFFER_AUTO_EXTEND feature is enabled, |
|
336 * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is |
|
337 * disabled or buffer extension fails, \c EOF is returned. |
|
338 * |
|
339 * On successful write, the position of the buffer is increased. |
|
340 * |
|
341 * \param buffer the buffer to write to |
|
342 * \param c the character to write |
|
343 * \return the byte that has bean written or \c EOF when the end of the stream is |
|
344 * reached and automatic extension is not enabled or not possible |
|
345 */ |
|
346 int cxBufferPut( |
|
347 CxBuffer buffer, |
|
348 int c |
|
349 ); |
|
350 |
|
351 /** |
|
352 * Gets a character from a buffer. |
|
353 * |
|
354 * The current position of the buffer is increased after a successful read. |
|
355 * |
|
356 * \param buffer the buffer to read from |
|
357 * \return the character or \c EOF, if the end of the buffer is reached |
|
358 */ |
|
359 int cxBufferGet(CxBuffer buffer); |
|
360 |
|
361 /** |
|
362 * Writes a string to a buffer. |
|
363 * |
|
364 * \param buffer the buffer |
|
365 * \param str the zero-terminated string |
|
366 * \return the number of bytes written |
|
367 */ |
|
368 size_t cxBufferPutString( |
|
369 CxBuffer buffer, |
|
370 const char *str |
|
371 ); |
|
372 |
|
373 #ifdef __cplusplus |
|
374 } |
|
375 #endif |
|
376 |
|
377 #endif /* UCX_BUFFER_H */ |