1 /*************************************************************************** 2 $RCSfile$ 3 ------------------- 4 cvs : $Id$ 5 begin : Sun Jan 25 2004 6 copyright : (C) 2004 by Martin Preuss 7 email : martin@libchipcard.de 8 9 *************************************************************************** 10 * * 11 * This library is free software; you can redistribute it and/or * 12 * modify it under the terms of the GNU Lesser General Public * 13 * License as published by the Free Software Foundation; either * 14 * version 2.1 of the License, or (at your option) any later version. * 15 * * 16 * This library is distributed in the hope that it will be useful, * 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 19 * Lesser General Public License for more details. * 20 * * 21 * You should have received a copy of the GNU Lesser General Public * 22 * License along with this library; if not, write to the Free Software * 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * 24 * MA 02111-1307 USA * 25 * * 26 ***************************************************************************/ 27 28 29 #ifndef GWEN_RINGBUFFER_H 30 #define GWEN_RINGBUFFER_H 31 32 #include <gwenhywfar/types.h> 33 #include <gwenhywfar/gwenhywfarapi.h> 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 40 /** @defgroup MOD_RINGBUFFER Ringbuffer Management 41 * @ingroup MOD_BASE 42 * 43 * @brief This file contains the definition of a GWEN_RINGBUFFER. 44 * 45 */ 46 /*@{*/ 47 48 typedef struct GWEN_RINGBUFFER GWEN_RINGBUFFER; 49 50 51 /** @name Constructor And Destructor 52 * 53 */ 54 /*@{*/ 55 /** 56 * Creates a new ring buffer 57 * @param size maximum size of the ring buffer 58 */ 59 GWENHYWFAR_API 60 GWEN_RINGBUFFER *GWEN_RingBuffer_new(unsigned int size); 61 62 /** 63 * Destructor. 64 */ 65 GWENHYWFAR_API 66 void GWEN_RingBuffer_free(GWEN_RINGBUFFER *rb); 67 68 69 /** @name Reading And Writing 70 * 71 */ 72 /*@{*/ 73 /** 74 * Writes the given bytes into the ring buffer. 75 * @param rb ring buffer 76 * @param buffer pointer to bytes to write 77 * @param size pointer to a variable that contains the number of bytes 78 * to write. Upon return this variable contains the number of bytes actually 79 * copied. 80 */ 81 GWENHYWFAR_API 82 int GWEN_RingBuffer_WriteBytes(GWEN_RINGBUFFER *rb, 83 const char *buffer, 84 uint32_t *size); 85 86 /** 87 * Writes a single byte to the ring buffer. 88 */ 89 GWENHYWFAR_API 90 int GWEN_RingBuffer_WriteByte(GWEN_RINGBUFFER *rb, char c); 91 92 93 /** 94 * Read bytes from the ring buffer. 95 * @param rb ring buffer 96 * @param buffer pointer to the destination buffer 97 * @param size pointer to a variable that contains the number of bytes 98 * to read. Upon return this variable contains the number of bytes actually 99 * copied. 100 */ 101 GWENHYWFAR_API 102 int GWEN_RingBuffer_ReadBytes(GWEN_RINGBUFFER *rb, 103 char *buffer, 104 uint32_t *size); 105 106 /** 107 * Reads a single byte from the ring buffer. 108 */ 109 GWENHYWFAR_API 110 int GWEN_RingBuffer_ReadByte(GWEN_RINGBUFFER *rb); 111 /*@}*/ 112 113 114 /** @name Informational Functions 115 * 116 */ 117 /*@{*/ 118 /** 119 * Returns the number of bytes stored inside the ring buffer. 120 */ 121 GWENHYWFAR_API 122 uint32_t GWEN_RingBuffer_GetUsedBytes(const GWEN_RINGBUFFER *rb); 123 124 /** 125 * Returns the number of bytes which still can be stored inside the ring 126 * buffer. 127 */ 128 GWENHYWFAR_API 129 uint32_t GWEN_RingBuffer_GetBytesLeft(const GWEN_RINGBUFFER *rb); 130 131 /** 132 * Returns the size of the ring buffer. 133 */ 134 GWENHYWFAR_API 135 uint32_t GWEN_RingBuffer_GetBufferSize(const GWEN_RINGBUFFER *rb); 136 /*@}*/ 137 138 139 140 /** @name Statistical Functions 141 * 142 */ 143 /*@{*/ 144 /** 145 * Returns the number of times the buffer was empty. 146 */ 147 GWENHYWFAR_API 148 uint32_t GWEN_RingBuffer_GetEmptyCounter(const GWEN_RINGBUFFER *rb); 149 150 GWENHYWFAR_API 151 void GWEN_RingBuffer_ResetEmptyCounter(GWEN_RINGBUFFER *rb); 152 153 154 /** 155 * Returns the number of times the buffer was full. 156 */ 157 GWENHYWFAR_API 158 uint32_t GWEN_RingBuffer_GetFullCounter(const GWEN_RINGBUFFER *rb); 159 160 GWENHYWFAR_API 161 void GWEN_RingBuffer_ResetFullCounter(GWEN_RINGBUFFER *rb); 162 163 164 /** 165 * Returns the number of bytes which have passed through this buffer (i.e. 166 * bytes that have been written to <strong>and</strong> read from the buffer. 167 */ 168 GWENHYWFAR_API 169 uint32_t GWEN_RingBuffer_GetThroughput(GWEN_RINGBUFFER *rb); 170 171 /** 172 * Resets the buffers throughput counter to zero. 173 */ 174 GWENHYWFAR_API 175 void GWEN_RingBuffer_ResetThroughput(GWEN_RINGBUFFER *rb); 176 177 178 179 /** 180 * Returns the maximum number of bytes which has been stored in the buffer. 181 */ 182 GWENHYWFAR_API 183 uint32_t GWEN_RingBuffer_GetMaxUsedBytes(const GWEN_RINGBUFFER *rb); 184 185 /** 186 * Resets the counter for the maximum number of bytes stored in the 187 * buffer. 188 */ 189 GWENHYWFAR_API 190 void GWEN_RingBuffer_ResetMaxUsedBytes(GWEN_RINGBUFFER *rb); 191 192 GWENHYWFAR_API 193 void GWEN_RingBuffer_Reset(GWEN_RINGBUFFER *rb); 194 195 196 /*@}*/ /* name */ 197 198 199 200 /** @name Functions For Direct Manipulation Of The Buffer 201 * 202 * Please use these functions with care. These function are supported in order 203 * to avoid unnecessary copying. 204 */ 205 /*@{*/ 206 /** 207 * Returns the maximum number of bytes which can be read with a following 208 * call to @ref GWEN_RingBuffer_ReadBytes. This value (if not 0) can be 209 * used for @ref GWEN_RingBuffer_SkipBytesRead. 210 */ 211 GWENHYWFAR_API 212 uint32_t 213 GWEN_RingBuffer_GetMaxUnsegmentedRead(GWEN_RINGBUFFER *rb); 214 215 /** 216 * Returns the maximum number of bytes which can be written with a following 217 * call to @ref GWEN_RingBuffer_WriteBytes. This value (if not 0) can be 218 * used for @ref GWEN_RingBuffer_SkipBytesWrite. 219 */ 220 GWENHYWFAR_API 221 uint32_t 222 GWEN_RingBuffer_GetMaxUnsegmentedWrite(GWEN_RINGBUFFER *rb); 223 224 /** 225 * Adjusts the internal pointers and statistical data as if 226 * @ref GWEN_RingBuffer_ReadBytes had been called. Please note that the 227 * size value given here MUST be <= the value returned by 228 * @ref GWEN_RingBuffer_GetMaxUnsegmentedRead ! 229 */ 230 GWENHYWFAR_API 231 void GWEN_RingBuffer_SkipBytesRead(GWEN_RINGBUFFER *rb, 232 uint32_t psize); 233 234 /** 235 * Adjusts the internal pointers and statistical data as if 236 * @ref GWEN_RingBuffer_WriteBytes had been called. Please note that the 237 * size value given here MUST be <= the value returned by 238 * @ref GWEN_RingBuffer_GetMaxUnsegmentedWrite ! 239 */ 240 GWENHYWFAR_API 241 void GWEN_RingBuffer_SkipBytesWrite(GWEN_RINGBUFFER *rb, 242 uint32_t psize); 243 244 /** 245 * Returne the current read pointer. Please note that the return value of 246 * @ref GWEN_RingBuffer_GetMaxUnsegmentedRead indicates the maximum number 247 * of bytes at this position available! Trying to access bytes beyond that 248 * boundary will most likely result in segmentation faults. 249 * Please make sure that you call @ref GWEN_RingBuffer_SkipBytesRead after 250 * taking data from the buffer in order to keep the internal structure 251 * intact. 252 */ 253 GWENHYWFAR_API 254 const char *GWEN_RingBuffer_GetReadPointer(const GWEN_RINGBUFFER *rb); 255 256 /** 257 * Returne the current write pointer. Please note that the return value of 258 * @ref GWEN_RingBuffer_GetMaxUnsegmentedWrite indicates the maximum number 259 * of bytes at this position available! Trying to access bytes beyond that 260 * boundary will most likely result in segmentation faults. 261 * Please make sure that you call @ref GWEN_RingBuffer_SkipBytesWrite after 262 * writing data to the buffer in order to keep the internal structure 263 * intact. 264 */ 265 GWENHYWFAR_API 266 char *GWEN_RingBuffer_GetWritePointer(const GWEN_RINGBUFFER *rb); 267 268 /*@}*/ /* name */ 269 270 271 /*@}*/ /* group */ 272 273 #ifdef __cplusplus 274 } 275 #endif 276 277 278 #endif /* GWEN_RINGBUFFER_H */ 279 280 281 282 283