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