35 |
52 |
36 #ifdef __cplusplus |
53 #ifdef __cplusplus |
37 extern "C" { |
54 extern "C" { |
38 #endif |
55 #endif |
39 |
56 |
40 /* no autoextend or autofree behaviour */ |
57 /** |
|
58 * No buffer features enabled (all flags cleared). |
|
59 */ |
41 #define UCX_BUFFER_DEFAULT 0x00 |
60 #define UCX_BUFFER_DEFAULT 0x00 |
42 /* the buffer shall free the occupied memory space */ |
61 |
|
62 /** |
|
63 * If this flag is enabled, the buffer will automatically free its contents. |
|
64 */ |
43 #define UCX_BUFFER_AUTOFREE 0x01 |
65 #define UCX_BUFFER_AUTOFREE 0x01 |
44 /* the buffer may automatically double its size on write operations */ |
66 |
|
67 /** |
|
68 * If this flag is enabled, the buffer will automatically extends its capacity. |
|
69 */ |
45 #define UCX_BUFFER_AUTOEXTEND 0x02 |
70 #define UCX_BUFFER_AUTOEXTEND 0x02 |
46 |
71 |
47 /* the user shall not modify values, but may get the latest pointer */ |
72 /** UCX Buffer. */ |
48 typedef struct { |
73 typedef struct { |
|
74 /** A pointer to the buffer contents. */ |
49 char *space; |
75 char *space; |
|
76 /** Current position of the buffer. */ |
50 size_t pos; |
77 size_t pos; |
|
78 /** Current capacity (i.e. maximum size) of the buffer. */ |
51 size_t capacity; |
79 size_t capacity; |
|
80 /** Current size of the buffer content. */ |
52 size_t size; |
81 size_t size; |
|
82 /** |
|
83 * Flag register for buffer features. |
|
84 * @see #UCX_BUFFER_DEFAULT |
|
85 * @see #UCX_BUFFER_AUTOFREE |
|
86 * @see #UCX_BUFFER_AUTOEXTEND |
|
87 */ |
53 int flags; |
88 int flags; |
54 } UcxBuffer; |
89 } UcxBuffer; |
55 |
90 |
56 /* if space is NULL, new space is allocated and the autofree flag is enforced */ |
91 /** |
|
92 * Creates a new buffer. |
|
93 * |
|
94 * <b>Note:</b> you may provide <code>NULL</code> as argument for |
|
95 * <code>space</code>. Then this function will allocate the space and enforce |
|
96 * the #UCX_BUFFER_AUTOFREE flag. |
|
97 * |
|
98 * @param space pointer to the memory area, or <code>NULL</code> to allocate |
|
99 * new memory |
|
100 * @param size the size of the buffer |
|
101 * @param flags buffer features (see UcxBuffer.flags) |
|
102 * @return the new buffer |
|
103 */ |
57 UcxBuffer *ucx_buffer_new(void *space, size_t size, int flags); |
104 UcxBuffer *ucx_buffer_new(void *space, size_t size, int flags); |
|
105 |
|
106 /** |
|
107 * Destroys a buffer. |
|
108 * |
|
109 * If the #UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer |
|
110 * are also freed. |
|
111 * |
|
112 * @param buffer the buffer to destroy |
|
113 */ |
58 void ucx_buffer_free(UcxBuffer* buffer); |
114 void ucx_buffer_free(UcxBuffer* buffer); |
59 |
115 |
60 /* |
116 /** |
61 * the autofree flag is enforced for the new buffer |
117 * Creates a new buffer and fills it with extracted content from another buffer. |
62 * if length is zero, the whole remaining buffer shall be extracted |
118 * |
63 * the position of the new buffer is set to zero |
119 * <b>Note:</b> the #UCX_BUFFER_AUTOFREE feature is enforced for the new buffer. |
|
120 * |
|
121 * @param src the source buffer |
|
122 * @param start the start position of extraction |
|
123 * @param length the count of bytes to extract or 0 if all of the remaining |
|
124 * bytes shall be extracted |
|
125 * @param flags feature mask for the new buffer |
|
126 * @return |
64 */ |
127 */ |
65 UcxBuffer* ucx_buffer_extract(UcxBuffer *src, |
128 UcxBuffer* ucx_buffer_extract(UcxBuffer *src, |
66 size_t start, size_t length, int flags); |
129 size_t start, size_t length, int flags); |
|
130 |
|
131 /** |
|
132 * A shorthand macro for the full extraction of the buffer. |
|
133 * |
|
134 * @param src the source buffer |
|
135 * @param flags feature mask for the new buffer |
|
136 * @return a new buffer with the extracted content |
|
137 */ |
67 #define ucx_buffer_clone(src,flags) \ |
138 #define ucx_buffer_clone(src,flags) \ |
68 ucx_buffer_extract(src, 0, 0, flags) |
139 ucx_buffer_extract(src, 0, 0, flags) |
69 |
140 |
70 /* |
141 /** |
71 * Moves the position of the buffer to a new position relative to whence. |
142 * Moves the position of the buffer. |
72 * |
143 * |
73 * SEEK_SET marks the start of the buffer |
144 * The new position is relative to the <code>whence</code> argument. |
74 * SEEK_CUR marks the current position |
145 * |
75 * SEEK_END marks the first 0-byte in the buffer |
146 * SEEK_SET marks the start of the buffer. |
76 * |
147 * SEEK_CUR marks the current position. |
77 * ucx_buffer_seek returns 0 on success and -1 if the new position is beyond the |
148 * SEEK_END marks the first 0-byte in the buffer. |
78 * bounds of the allocated buffer. In that case the position of the buffer |
149 * |
79 * remains unchanged. |
150 * @param buffer |
|
151 * @param offset position offset relative to <code>whence</code> |
|
152 * @param whence one of SEEK_SET, SEEK_CUR or SEEK_END |
|
153 * @return 0 on success, non-zero if the position is invalid |
80 * |
154 * |
81 */ |
155 */ |
82 int ucx_buffer_seek(UcxBuffer *buffer, off_t offset, int whence); |
156 int ucx_buffer_seek(UcxBuffer *buffer, off_t offset, int whence); |
83 |
157 |
84 #define ucx_buffer_clear(buffer) memset(buffer->space, 0, buffer->size); \ |
158 /** |
85 buffer->size = 0; buffer->pos = 0; |
159 * Clears the buffer by resetting the position and deleting the data. |
86 |
160 * |
87 /* |
161 * The data is deleted by a zeroing it with call to <code>memset()</code>. |
88 * returns non-zero, if the current buffer position has exceeded the last |
162 * |
89 * available byte of the underlying buffer |
163 * @param buffer the buffer to be cleared |
90 * |
164 */ |
|
165 #define ucx_buffer_clear(buffer) memset(buffer->space, 0, buffer->size); \ |
|
166 buffer->size = 0; buffer->pos = 0; |
|
167 |
|
168 /** |
|
169 * Tests, if the buffer position has exceeded the buffer capacity. |
|
170 * |
|
171 * @param buffer the buffer to test |
|
172 * @return non-zero, if the current buffer position has exceeded the last |
|
173 * available byte of the buffer. |
91 */ |
174 */ |
92 int ucx_buffer_eof(UcxBuffer *buffer); |
175 int ucx_buffer_eof(UcxBuffer *buffer); |
93 |
176 |
94 |
177 |
95 int ucx_buffere_extend(UcxBuffer *buffer, size_t len); |
178 /** |
96 |
179 * Extends the capacity of the buffer. |
|
180 * |
|
181 * <b>Note:</b> The buffer capacity increased by a power of two. I.e. |
|
182 * the buffer capacity is doubled, as long as it would not hold the current |
|
183 * content plus the additional required bytes. |
|
184 * |
|
185 * <b>Attention:</b> the argument provided is the count of <i>additional</i> |
|
186 * bytes the buffer shall hold. It is <b>NOT</b> the total count of bytes the |
|
187 * buffer shall hold. |
|
188 * |
|
189 * @param buffer the buffer to extend |
|
190 * @param additional_bytes the count of additional bytes the buffer shall |
|
191 * <i>at least</i> hold |
|
192 * @return 0 on success or a non-zero value on failure |
|
193 */ |
|
194 int ucx_buffer_extend(UcxBuffer *buffer, size_t additional_bytes); |
|
195 |
|
196 /** |
|
197 * Writes data to an UcxBuffer. |
|
198 * |
|
199 * The position of the buffer is increased by the number of bytes read. |
|
200 * |
|
201 * @param ptr a pointer to the memory area containing the bytes to be written |
|
202 * @param size the length of one element |
|
203 * @param nitems the element count |
|
204 * @param buffer the UcxBuffer to write to |
|
205 * @return the total count of bytes written |
|
206 */ |
97 size_t ucx_buffer_write(const void *ptr, size_t size, size_t nitems, |
207 size_t ucx_buffer_write(const void *ptr, size_t size, size_t nitems, |
98 UcxBuffer *buffer); |
208 UcxBuffer *buffer); |
99 |
209 |
|
210 /** |
|
211 * Reads data from an UcxBuffer. |
|
212 * |
|
213 * The position of the buffer is increased by the number of bytes read. |
|
214 * |
|
215 * @param ptr a pointer to the memory area where to store the read data |
|
216 * @param size the length of one element |
|
217 * @param nitems the element count |
|
218 * @param buffer the UcxBuffer to read from |
|
219 * @return the total count of bytes read |
|
220 */ |
100 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems, |
221 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems, |
101 UcxBuffer *buffer); |
222 UcxBuffer *buffer); |
102 |
223 |
103 int ucx_buffer_putc(UcxBuffer *b, int c); |
224 /** |
104 int ucx_buffer_getc(UcxBuffer *b); |
225 * Writes a character to a buffer. |
105 |
226 * |
106 |
227 * The least significant byte of the argument is written to the buffer. If the |
107 /* |
228 * end of the buffer is reached and #UCX_BUFFER_AUTOEXTEND feature is enabled, |
108 * copies all bytes from s1 to s2 |
229 * the buffer capacity is extended by ucx_buffer_extend(). If the feature is |
109 * uses the read function r to read from s1 und writes the data using the |
230 * disabled or buffer extension fails, <code>EOF</code> is returned. |
110 * write function w to s2 |
231 * |
111 * returns the number of bytes copied |
232 * On successful write the position of the buffer is increased. |
112 */ |
233 * |
113 size_t ucx_buffer_generic_copy(void *s1, void *s2, read_func r, write_func w, |
234 * @param buffer the buffer to write to |
114 size_t bufsize); |
235 * @param c the character to write as <code>int</code> value |
115 |
236 * @return the byte that has bean written as <code>int</code> value or |
116 size_t ucx_buffer_generic_ncopy(void *s1, void *s2, read_func r, write_func w, |
237 * <code>EOF</code> when the end of the stream is reached and automatic |
117 size_t bufsize, size_t n); |
238 * extension is not enabled or not possible |
118 |
239 */ |
119 #define UCX_DEFAULT_BUFFER_SIZE 0x1000 |
240 int ucx_buffer_putc(UcxBuffer *buffer, int c); |
120 |
241 |
121 #define ucx_buffer_copy(s1,s2,r,w) \ |
242 /** |
122 ucx_buffer_generic_copy(s1, s2, (read_func)r, (write_func)w, \ |
243 * Gets a character from a buffer. |
123 UCX_DEFAULT_BUFFER_SIZE) |
244 * |
124 |
245 * The current position of the buffer is increased after a successful read. |
125 #define ucx_buffer_ncopy(s1,s2,r,w, n) \ |
246 * |
126 ucx_buffer_generic_ncopy(s1, s2, (read_func)r, (write_func)w, \ |
247 * @param buffer the buffer to read from |
127 UCX_DEFAULT_BUFFER_SIZE, n) |
248 * @return the character as <code>int</code> value or <code>EOF</code>, if the |
|
249 * end of the buffer is reached |
|
250 */ |
|
251 int ucx_buffer_getc(UcxBuffer *buffer); |
|
252 |
|
253 /** |
|
254 * Writes a string to a buffer. |
|
255 * |
|
256 * @param buffer the buffer |
|
257 * @param str the string |
|
258 * @return the number of bytes written |
|
259 */ |
|
260 size_t ucx_buffer_puts(UcxBuffer *buffer, char *str); |
128 |
261 |
129 #ifdef __cplusplus |
262 #ifdef __cplusplus |
130 } |
263 } |
131 #endif |
264 #endif |
132 |
265 |