lib/silcutil/silcbuffer.h

   1 /*
   2
   3   silcbuffer.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 1998 - 2000 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef SILCBUFFER_H
  22 #define SILCBUFFER_H
  23
  24 /*
  25    SILC Buffer object.
  26
  27    SilcBuffer is very simple and easy to use, yet you can do to the
  28    buffer almost anything you want with its method functions. The buffer
  29    is constructed of four different data sections that in whole creates
  30    the allocated data area. Following short description of the fields
  31    of the buffer.
  32
  33    unsigned int truelen;
  34
  35        True length of the buffer. This is set at the allocation of the
  36        buffer and it should not be touched after that. This field should
  37        be considered read-only.
  38
  39    unsigned int len;
  40
  41        Length of the currently valid data area. Tells the length of the
  42        data at the buffer. This is set to zero at the allocation of the
  43        buffer and should not be updated by hand. Method functions of the
  44        buffer automatically updates this field. However, it is not
  45        read-only field and can be updated manually if necessary.
  46
  47    unsiged char *head;
  48
  49        Head of the allocated buffer. This is the start of the allocated
  50        data area and remains as same throughout the lifetime of the buffer.
  51        However, the end of the head area or the start of the currently valid
  52        data area is variable.
  53
  54        --------------------------------
  55        | head  | data         | tail  |
  56        --------------------------------
  57        ^       ^
  58
  59        Current head section in the buffer is sb->data - sb->head.
  60
  61    unsigned char *data;
  62
  63        Currently valid data area. This is the start of the currently valid
  64        main data area. The data area is variable in all directions.
  65
  66        --------------------------------
  67        | head  | data         | tail  |
  68        --------------------------------
  69                ^              ^
  70
  71        Current valid data area in the buffer is sb->tail - sb->data.
  72
  73     unsigned char *tail;
  74
  75        Tail of the buffer. This is the end of the currently valid data area
  76        or start of the tail area. The start of the tail area is variable.
  77
  78        --------------------------------
  79        | head  | data         | tail  |
  80        --------------------------------
  81                               ^       ^
  82
  83        Current tail section in the buffer is sb->end - sb->tail.
  84
  85    unsigned char *end;
  86
  87        End of the allocated buffer. This is the end of the allocated data
  88        area and remains as same throughout the lifetime of the buffer.
  89        Usually this field is not needed except when checking the size
  90        of the buffer.
  91
  92        --------------------------------
  93        | head  | data         | tail  |
  94        --------------------------------
  95                                       ^
  96
  97        Length of the entire buffer is (ie. truelen) sb->end - sb->head.
  98
  99     Currently valid data area is considered to be the main data area in
 100     the buffer. However, the entire buffer is of course valid data and can
 101     be used as such. Usually head section of the buffer includes different
 102     kind of headers or similiar. Data section includes the main data of
 103     the buffer. Tail section can be seen as a reserve space of the data
 104     section. Tail section can be pulled towards end thus the data section
 105     becomes larger.
 106
 107     This buffer scheme is based on Linux kernel's Socket Buffer, the
 108     idea were taken directly from there and credits should go there.
 109
 110 */
 111
 112 typedef struct SilcBufferStruct {
 113   unsigned int truelen;
 114   unsigned int len;
 115   unsigned char *head;
 116   unsigned char *data;
 117   unsigned char *tail;
 118   unsigned char *end;
 119 } SilcBufferObject;
 120
 121 typedef SilcBufferObject *SilcBuffer;
 122
 123 /* Macros */
 124
 125 /* Returns the true length of the buffer. This is used to pull
 126    the buffer area to the end of the buffer. */
 127 #define SILC_BUFFER_END(x) ((x)->end - (x)->head)
 128
 129 #ifndef SILC_DEBUG              /* When we are not doing debugging we use
 130                                    optimized inline buffer functions. */
 131 /*
 132  * Optimized buffer managing routines.  These are short inline
 133  * functions.
 134  */
 135
 136 extern inline
 137 SilcBuffer silc_buffer_alloc(unsigned int len)
 138 {
 139   SilcBuffer sb;
 140   unsigned char *data;
 141
 142   /* Allocate new SilcBuffer */
 143   sb = silc_calloc(1, sizeof(*sb));
 144
 145   /* Allocate the actual data area */
 146   data = silc_calloc(len, sizeof(*data));
 147
 148   /* Set pointers to the new buffer */
 149   sb->truelen = len;
 150   sb->len = 0;
 151   sb->head = data;
 152   sb->data = data;
 153   sb->tail = data;
 154   sb->end = data + sb->truelen;
 155
 156   return sb;
 157 }
 158
 159 /* Free's a SilcBuffer */
 160
 161 extern inline
 162 void silc_buffer_free(SilcBuffer sb)
 163 {
 164   if (sb) {
 165     memset(sb->head, 'F', sb->truelen);
 166     silc_free(sb->head);
 167     silc_free(sb);
 168   }
 169 }
 170
 171 /* Pulls current data area towards end. The length of the currently
 172    valid data area is also decremented. Returns pointer to the data
 173    area before pulling.
 174
 175    Example:
 176    ---------------------------------
 177    | head  | data       | tail     |
 178    ---------------------------------
 179            ^
 180            Pulls the start of the data area.
 181
 182    ---------------------------------
 183    | head     | data    | tail     |
 184    ---------------------------------
 185            ^
 186 */
 187
 188 extern inline
 189 unsigned char *silc_buffer_pull(SilcBuffer sb, unsigned int len)
 190 {
 191   unsigned char *old_data = sb->data;
 192
 193   assert(len <= (sb->tail - sb->data));
 194
 195   sb->data += len;
 196   sb->len -= len;
 197
 198   return old_data;
 199 }
 200
 201 /* Pushes current data area towards beginning. Length of the currently
 202    valid data area is also incremented. Returns a pointer to the
 203    data area before pushing.
 204
 205    Example:
 206    ---------------------------------
 207    | head     | data    | tail     |
 208    ---------------------------------
 209               ^
 210               Pushes the start of the data area.
 211
 212    ---------------------------------
 213    | head  | data       | tail     |
 214    ---------------------------------
 215               ^
 216 */
 217
 218 extern inline
 219 unsigned char *silc_buffer_push(SilcBuffer sb, unsigned int len)
 220 {
 221   unsigned char *old_data = sb->data;
 222
 223   assert((sb->data - len) >= sb->head);
 224
 225   sb->data -= len;
 226   sb->len += len;
 227
 228   return old_data;
 229 }
 230
 231 /* Pulls current tail section towards end. Length of the current valid
 232    data area is also incremented. Returns a pointer to the data area
 233    before pulling.
 234
 235    Example:
 236    ---------------------------------
 237    | head  | data       | tail     |
 238    ---------------------------------
 239                         ^
 240                         Pulls the start of the tail section.
 241
 242    ---------------------------------
 243    | head  | data           | tail |
 244    ---------------------------------
 245                         ^
 246 */
 247
 248 extern inline
 249 unsigned char *silc_buffer_pull_tail(SilcBuffer sb, unsigned int len)
 250 {
 251   unsigned char *old_tail = sb->tail;
 252
 253   assert((sb->end - sb->tail) >= len);
 254
 255   sb->tail += len;
 256   sb->len += len;
 257
 258   return old_tail;
 259 }
 260
 261 /* Pushes current tail section towards beginning. Length of the current
 262    valid data area is also decremented. Returns a pointer to the
 263    tail section before pushing.
 264
 265    Example:
 266    ---------------------------------
 267    | head  | data           | tail |
 268    ---------------------------------
 269                             ^
 270                             Pushes the start of the tail section.
 271
 272    ---------------------------------
 273    | head  | data       | tail     |
 274    ---------------------------------
 275                             ^
 276 */
 277
 278 extern inline
 279 unsigned char *silc_buffer_push_tail(SilcBuffer sb, unsigned int len)
 280 {
 281   unsigned char *old_tail = sb->tail;
 282
 283   assert((sb->tail - len) >= sb->data);
 284
 285   sb->tail -= len;
 286   sb->len -= len;
 287
 288   return old_tail;
 289 }
 290
 291 /* Puts data at the head of the buffer. Returns pointer to the copied
 292    data area.
 293
 294    Example:
 295    ---------------------------------
 296    | head  | data       | tail     |
 297    ---------------------------------
 298    ^
 299    Puts data to the head section.
 300 */
 301
 302 extern inline
 303 unsigned char *silc_buffer_put_head(SilcBuffer sb,
 304                                     unsigned char *data,
 305                                     unsigned int len)
 306 {
 307   assert((sb->data - sb->head) >= len);
 308   return memcpy(sb->head, data, len);
 309 }
 310
 311 /* Puts data at the start of the valid data area. Returns a pointer
 312    to the copied data area.
 313
 314    Example:
 315    ---------------------------------
 316    | head  | data       | tail     |
 317    ---------------------------------
 318            ^
 319            Puts data to the data section.
 320 */
 321
 322 extern inline
 323 unsigned char *silc_buffer_put(SilcBuffer sb,
 324                                unsigned char *data,
 325                                unsigned int len)
 326 {
 327   assert((sb->tail - sb->data) >= len);
 328   return memcpy(sb->data, data, len);
 329 }
 330
 331 /* Puts data at the tail of the buffer. Returns pointer to the copied
 332    data area.
 333
 334    Example:
 335    ---------------------------------
 336    | head  | data           | tail |
 337    ---------------------------------
 338                             ^
 339                             Puts data to the tail section.
 340 */
 341
 342 extern inline
 343 unsigned char *silc_buffer_put_tail(SilcBuffer sb,
 344                                     unsigned char *data,
 345                                     unsigned int len)
 346 {
 347   assert((sb->end - sb->tail) >= len);
 348   return memcpy(sb->tail, data, len);
 349 }
 350
 351 #endif /* !SILC_DEBUG */
 352
 353 /* Prototypes */
 354 #ifdef SILC_DEBUG
 355 SilcBuffer silc_buffer_alloc(unsigned int len);
 356 void silc_buffer_free(SilcBuffer sb);
 357 unsigned char *silc_buffer_pull(SilcBuffer sb, unsigned int len);
 358 unsigned char *silc_buffer_push(SilcBuffer sb, unsigned int len);
 359 unsigned char *silc_buffer_pull_tail(SilcBuffer sb, unsigned int len);
 360 unsigned char *silc_buffer_push_tail(SilcBuffer sb, unsigned int len);
 361 unsigned char *silc_buffer_put_head(SilcBuffer sb,
 362                                     unsigned char *data,
 363                                     unsigned int len);
 364 unsigned char *silc_buffer_put(SilcBuffer sb,
 365                                unsigned char *data,
 366                                unsigned int len);
 367 unsigned char *silc_buffer_put_tail(SilcBuffer sb,
 368                                     unsigned char *data,
 369                                     unsigned int len);
 370 #endif
 371
 372 #endif