Tue, 13 Aug 2013 14:20:12 +0200
completed documentation + changed API for buffer/stream generic copy functions
universe@103 | 1 | /* |
universe@103 | 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
universe@103 | 3 | * |
universe@103 | 4 | * Copyright 2013 Olaf Wintermann. All rights reserved. |
universe@103 | 5 | * |
universe@103 | 6 | * Redistribution and use in source and binary forms, with or without |
universe@103 | 7 | * modification, are permitted provided that the following conditions are met: |
universe@103 | 8 | * |
universe@103 | 9 | * 1. Redistributions of source code must retain the above copyright |
universe@103 | 10 | * notice, this list of conditions and the following disclaimer. |
universe@103 | 11 | * |
universe@103 | 12 | * 2. Redistributions in binary form must reproduce the above copyright |
universe@103 | 13 | * notice, this list of conditions and the following disclaimer in the |
universe@103 | 14 | * documentation and/or other materials provided with the distribution. |
universe@103 | 15 | * |
universe@103 | 16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
universe@103 | 17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
universe@103 | 18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
universe@103 | 19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
universe@103 | 20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
universe@103 | 21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
universe@103 | 22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
universe@103 | 23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
universe@103 | 24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
universe@103 | 25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
universe@103 | 26 | * POSSIBILITY OF SUCH DAMAGE. |
universe@103 | 27 | */ |
universe@103 | 28 | |
universe@140 | 29 | /** |
universe@140 | 30 | * @file buffer.h |
universe@140 | 31 | * |
universe@140 | 32 | * Advanced buffer implementation. |
universe@140 | 33 | * |
universe@140 | 34 | * Instances of UcxBuffer can be used to read from or to write to like one |
universe@140 | 35 | * would do with a stream. This allows the use of ucx_stream_copy() to copy |
universe@140 | 36 | * contents from one buffer to another. |
universe@140 | 37 | * |
universe@140 | 38 | * Some features for convenient use of the buffer |
universe@140 | 39 | * can be enabled. See the documentation of the macro constants for more |
universe@140 | 40 | * information. |
universe@140 | 41 | * |
universe@140 | 42 | * @author Mike Becker |
universe@140 | 43 | * @author Olaf Wintermann |
universe@140 | 44 | */ |
universe@140 | 45 | |
olaf@120 | 46 | #ifndef UCX_BUFFER_H |
olaf@120 | 47 | #define UCX_BUFFER_H |
universe@56 | 48 | |
universe@69 | 49 | #include "ucx.h" |
universe@62 | 50 | #include <sys/types.h> |
universe@56 | 51 | #include <stdio.h> |
universe@56 | 52 | |
universe@56 | 53 | #ifdef __cplusplus |
universe@56 | 54 | extern "C" { |
universe@56 | 55 | #endif |
universe@56 | 56 | |
universe@140 | 57 | /** |
universe@140 | 58 | * No buffer features enabled (all flags cleared). |
universe@140 | 59 | */ |
universe@61 | 60 | #define UCX_BUFFER_DEFAULT 0x00 |
universe@140 | 61 | /** |
universe@140 | 62 | * If this flag is enabled, the buffer will automatically free its contents. |
universe@140 | 63 | */ |
universe@61 | 64 | #define UCX_BUFFER_AUTOFREE 0x01 |
universe@140 | 65 | /** |
universe@140 | 66 | * If this flag is enabled, the buffer will automatically extends its capacity. |
universe@140 | 67 | */ |
universe@63 | 68 | #define UCX_BUFFER_AUTOEXTEND 0x02 |
universe@56 | 69 | |
universe@140 | 70 | /** UCX Buffer. */ |
universe@63 | 71 | typedef struct { |
universe@140 | 72 | /** A pointer to the buffer contents. */ |
olaf@76 | 73 | char *space; |
universe@140 | 74 | /** Current position of the buffer. */ |
universe@63 | 75 | size_t pos; |
universe@140 | 76 | /** Current capacity (i.e. maximum size) of the buffer. */ |
olaf@76 | 77 | size_t capacity; |
universe@140 | 78 | /** Current size of the buffer content. */ |
universe@63 | 79 | size_t size; |
universe@140 | 80 | /** |
universe@140 | 81 | * Flag register for buffer features. |
universe@140 | 82 | * @see #UCX_BUFFER_DEFAULT |
universe@140 | 83 | * @see #UCX_BUFFER_AUTOFREE |
universe@140 | 84 | * @see #UCX_BUFFER_AUTOEXTEND |
universe@140 | 85 | */ |
universe@63 | 86 | int flags; |
universe@63 | 87 | } UcxBuffer; |
universe@56 | 88 | |
universe@140 | 89 | /** |
universe@140 | 90 | * Creates a new buffer. |
universe@140 | 91 | * |
universe@140 | 92 | * <b>Note:</b> you may provide <code>NULL</code> as argument for |
universe@140 | 93 | * <code>space</code>. Then this function will allocate the space and enforce |
universe@140 | 94 | * the #UCX_BUFFER_AUTOFREE flag. |
universe@140 | 95 | * |
universe@140 | 96 | * @param space pointer to the memory area, or <code>NULL</code> to allocate |
universe@140 | 97 | * new memory |
universe@140 | 98 | * @param size the size of the buffer |
universe@140 | 99 | * @param flags buffer features (see UcxBuffer.flags) |
universe@140 | 100 | * @return the new buffer |
universe@140 | 101 | */ |
olaf@76 | 102 | UcxBuffer *ucx_buffer_new(void *space, size_t size, int flags); |
universe@140 | 103 | |
universe@140 | 104 | /** |
universe@140 | 105 | * Destroys a buffer. |
universe@140 | 106 | * |
universe@140 | 107 | * If the #UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer |
universe@140 | 108 | * are also freed. |
universe@140 | 109 | * |
universe@140 | 110 | * @param buffer the buffer to destroy |
universe@140 | 111 | */ |
universe@60 | 112 | void ucx_buffer_free(UcxBuffer* buffer); |
universe@56 | 113 | |
universe@140 | 114 | /** |
universe@140 | 115 | * Creates a new buffer and fills it with extracted content from another buffer. |
universe@140 | 116 | * |
universe@140 | 117 | * <b>Note:</b> the #UCX_BUFFER_AUTOFREE feature is enforced for the new buffer. |
universe@140 | 118 | * |
universe@140 | 119 | * @param src the source buffer |
universe@140 | 120 | * @param start the start position of extraction |
universe@140 | 121 | * @param length the count of bytes to extract or 0 if all of the remaining |
universe@140 | 122 | * bytes shall be extracted |
universe@140 | 123 | * @param flags feature mask for the new buffer |
universe@140 | 124 | * @return |
universe@62 | 125 | */ |
olaf@76 | 126 | UcxBuffer* ucx_buffer_extract(UcxBuffer *src, |
universe@62 | 127 | size_t start, size_t length, int flags); |
universe@140 | 128 | |
universe@140 | 129 | /** |
universe@140 | 130 | * A shorthand macro for the full extraction of the buffer. |
universe@140 | 131 | * |
universe@140 | 132 | * @param src the source buffer |
universe@140 | 133 | * @param flags feature mask for the new buffer |
universe@140 | 134 | * @return a new buffer with the extracted content |
universe@140 | 135 | */ |
universe@62 | 136 | #define ucx_buffer_clone(src,flags) \ |
universe@62 | 137 | ucx_buffer_extract(src, 0, 0, flags) |
universe@62 | 138 | |
universe@140 | 139 | /** |
universe@140 | 140 | * Moves the position of the buffer. |
universe@140 | 141 | * |
universe@140 | 142 | * The new position is relative to the <code>whence</code> argument. |
universe@56 | 143 | * |
universe@140 | 144 | * SEEK_SET marks the start of the buffer. |
universe@140 | 145 | * SEEK_CUR marks the current position. |
universe@140 | 146 | * SEEK_END marks the first 0-byte in the buffer. |
universe@140 | 147 | * |
universe@140 | 148 | * @param buffer |
universe@140 | 149 | * @param offset position offset relative to <code>whence</code> |
universe@140 | 150 | * @param whence one of SEEK_SET, SEEK_CUR or SEEK_END |
universe@140 | 151 | * @return 0 on success, non-zero if the position is invalid |
universe@56 | 152 | * |
universe@56 | 153 | */ |
universe@60 | 154 | int ucx_buffer_seek(UcxBuffer *buffer, off_t offset, int whence); |
universe@56 | 155 | |
universe@140 | 156 | /** |
universe@140 | 157 | * Clears the buffer by resetting the position and deleting the data. |
universe@140 | 158 | * |
universe@140 | 159 | * The data is deleted by a zeroing it with call to <code>memset()</code>. |
universe@140 | 160 | * |
universe@140 | 161 | * @param buffer the buffer to be cleared |
universe@140 | 162 | */ |
universe@140 | 163 | #define ucx_buffer_clear(buffer) memset(buffer->space, 0, buffer->size); \ |
universe@140 | 164 | buffer->size = 0; buffer->pos = 0; |
universe@85 | 165 | |
universe@140 | 166 | /** |
universe@140 | 167 | * Tests, if the buffer position has exceeded the buffer capacity. |
universe@140 | 168 | * |
universe@140 | 169 | * @param buffer the buffer to test |
universe@140 | 170 | * @return non-zero, if the current buffer position has exceeded the last |
universe@140 | 171 | * available byte of the buffer. |
universe@56 | 172 | */ |
universe@60 | 173 | int ucx_buffer_eof(UcxBuffer *buffer); |
universe@56 | 174 | |
olaf@76 | 175 | |
universe@140 | 176 | /** |
universe@140 | 177 | * Extends the capacity of the buffer. |
universe@140 | 178 | * |
universe@140 | 179 | * <b>Note:</b> The buffer capacity increased by a power of two. I.e. |
universe@140 | 180 | * the buffer capacity is doubled, as long as it would not hold the current |
universe@140 | 181 | * content plus the additional required bytes. |
universe@140 | 182 | * |
universe@140 | 183 | * <b>Attention:</b> the argument provided is the count of <i>additional</i> |
universe@140 | 184 | * bytes the buffer shall hold. It is <b>NOT</b> the total count of bytes the |
universe@140 | 185 | * buffer shall hold. |
universe@140 | 186 | * |
universe@140 | 187 | * @param buffer the buffer to extend |
universe@140 | 188 | * @param additional_bytes the count of additional bytes the buffer shall |
universe@140 | 189 | * <i>at least</i> hold |
universe@140 | 190 | * @return 0 on success or a non-zero value on failure |
universe@140 | 191 | */ |
universe@140 | 192 | int ucx_buffer_extend(UcxBuffer *buffer, size_t additional_bytes); |
olaf@76 | 193 | |
universe@140 | 194 | /** |
universe@140 | 195 | * Writes data to an UcxBuffer. |
universe@140 | 196 | * |
universe@140 | 197 | * The position of the buffer is increased by the number of bytes read. |
universe@140 | 198 | * |
universe@140 | 199 | * @param ptr a pointer to the memory area containing the bytes to be written |
universe@140 | 200 | * @param size the length of one element |
universe@140 | 201 | * @param nitems the element count |
universe@140 | 202 | * @param buffer the UcxBuffer to write to |
universe@140 | 203 | * @return the total count of bytes written |
universe@140 | 204 | */ |
olaf@76 | 205 | size_t ucx_buffer_write(const void *ptr, size_t size, size_t nitems, |
olaf@76 | 206 | UcxBuffer *buffer); |
olaf@76 | 207 | |
universe@140 | 208 | /** |
universe@140 | 209 | * Reads data from an UcxBuffer. |
universe@140 | 210 | * |
universe@140 | 211 | * The position of the buffer is increased by the number of bytes read. |
universe@140 | 212 | * |
universe@140 | 213 | * @param ptr a pointer to the memory area where to store the read data |
universe@140 | 214 | * @param size the length of one element |
universe@140 | 215 | * @param nitems the element count |
universe@140 | 216 | * @param buffer the UcxBuffer to read from |
universe@140 | 217 | * @return the total count of bytes read |
universe@140 | 218 | */ |
olaf@76 | 219 | size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems, |
olaf@76 | 220 | UcxBuffer *buffer); |
olaf@76 | 221 | |
universe@140 | 222 | /** |
universe@140 | 223 | * Writes a character to a buffer. |
universe@140 | 224 | * |
universe@140 | 225 | * The least significant byte of the argument is written to the buffer. If the |
universe@140 | 226 | * end of the buffer is reached and #UCX_BUFFER_AUTOEXTEND feature is enabled, |
universe@140 | 227 | * the buffer capacity is extended by ucx_buffer_extend(). If the feature is |
universe@140 | 228 | * disabled or buffer extension fails, <code>EOF</code> is returned. |
universe@140 | 229 | * |
universe@140 | 230 | * On successful write the position of the buffer is increased. |
universe@140 | 231 | * |
universe@140 | 232 | * @param buffer the buffer to write to |
universe@140 | 233 | * @param c the character to write as <code>int</code> value |
universe@140 | 234 | * @return the byte that has bean written as <code>int</code> value or |
universe@140 | 235 | * <code>EOF</code> when the end of the stream is reached and automatic |
universe@140 | 236 | * extension is not enabled or not possible |
universe@140 | 237 | */ |
universe@140 | 238 | int ucx_buffer_putc(UcxBuffer *buffer, int c); |
universe@56 | 239 | |
universe@140 | 240 | /** |
universe@140 | 241 | * Gets a character from a buffer. |
universe@140 | 242 | * |
universe@140 | 243 | * The current position of the buffer is increased after a successful read. |
universe@140 | 244 | * |
universe@140 | 245 | * @param buffer the buffer to read from |
universe@140 | 246 | * @return the character as <code>int</code> value or <code>EOF</code>, if the |
universe@140 | 247 | * end of the buffer is reached |
universe@140 | 248 | */ |
universe@140 | 249 | int ucx_buffer_getc(UcxBuffer *buffer); |
olaf@76 | 250 | |
universe@140 | 251 | /** |
universe@140 | 252 | * Writes a string to a buffer. |
universe@140 | 253 | * |
universe@140 | 254 | * @param buffer the buffer |
universe@140 | 255 | * @param str the string |
universe@140 | 256 | * @return the number of bytes written |
olaf@76 | 257 | */ |
universe@140 | 258 | size_t ucx_buffer_puts(UcxBuffer *buffer, char *str); |
olaf@86 | 259 | |
universe@56 | 260 | #ifdef __cplusplus |
universe@56 | 261 | } |
universe@56 | 262 | #endif |
universe@56 | 263 | |
olaf@120 | 264 | #endif /* UCX_BUFFER_H */ |
universe@56 | 265 |