innfeed/buffer.h

   1 /*  $Id: buffer.h 7285 2005-06-07 06:38:24Z eagle $
   2 **
   3 **  The public interface to the Buffer class.
   4 **
   5 **  Written by James Brister <brister@vix.com>
   6 **
   7 **  The Buffer class encapsulates a region of memory. It provides reference
   8 **  counting so that redundant memory allocation and copying is minimized. A
   9 **  good example of this is the need to write the same data (e.g. an article
  10 **  body) out more than one socket. The data is stored in a Buffer and the
  11 **  Buffer is given to each EndPoint that is to write it. With the Refcount
  12 **  appropriately set the EndPoints can release their references at will and
  13 **  the Buffer will be cleaned up when necessary.
  14 */
  15
  16 #if ! defined ( buffer_h__ )
  17 #define buffer_h__
  18
  19
  20 #include <sys/types.h>
  21 #include <stdio.h>
  22
  23 #include "misc.h"
  24
  25
  26 /*
  27  * Create a new Buffer object and initialize it.
  28  */
  29 Buffer newBuffer (size_t size) ;
  30
  31 /* Create a new Buffer object around the preallocted PTR, which is SIZE
  32    bytes long. The data size of the Buffer is set to DATASIZE. When then
  33    buffer is released it will not delete the ptr (this is useful to have
  34    Buffers around contant strings, or Buffers around other Buffers) */
  35 Buffer newBufferByCharP (const char *ptr, size_t size, size_t dataSize) ;
  36
  37 /*
  38  * give up interest in the Buffer. Decrement refcount and delete if no
  39  * more referants
  40  */
  41 void delBuffer (Buffer buff) ;
  42
  43   /* print some debugging information about the buffer. */
  44 void printBufferInfo (Buffer buffer, FILE *fp, unsigned int indentAmt) ;
  45
  46   /* print debugging information about all outstanding buffers. */
  47 void gPrintBufferInfo (FILE *fp, unsigned int indentAmt) ;
  48
  49 /* increment reference counts so that the buffer object can be */
  50 /* handed off to another function without it being deleted when that */
  51 /* function calls bufferDelete(). Returns buff, so the call can be */
  52 /* used in function arg list. */
  53 Buffer bufferTakeRef (Buffer buff) ;
  54
  55 /* returns the address of the base of the memory owned by the Buffer */
  56 void *bufferBase (Buffer buff) ;
  57
  58 /* returns the size of the memory buffer has available. This always returns
  59    1 less than the real size so that there's space left for a null byte
  60    when needed. The extra byte is accounted for when the newBuffer function
  61    is called. */
  62 size_t bufferSize (Buffer) ;
  63
  64 /* return the amount of data actually in the buffer */
  65 size_t bufferDataSize (Buffer buff) ;
  66
  67 /* increment the size of the buffer's data region */
  68 void bufferIncrDataSize (Buffer buff, size_t size) ;
  69
  70 /* decrement the size of the buffer's data region */
  71 void bufferDecrDataSize (Buffer buff, size_t size) ;
  72
  73 /* set the size of the data actually in the buffer */
  74 void bufferSetDataSize (Buffer buff, size_t size) ;
  75
  76 /* callback to be called when buffer gets deleted */
  77 void bufferSetDeletedCbk (Buffer buff, void (*cbk)(void *), void *data);
  78
  79 /* walk down the BUFFS releasing each buffer and then freeing BUFFS itself */
  80 void freeBufferArray (Buffer *buffs) ;
  81
  82 /* All arguments are non-NULL Buffers, except for the last which must be
  83    NULL. Creates a free'able array and puts all the buffers into it (does
  84    not call bufferTakeRef on them). */
  85 Buffer *makeBufferArray (Buffer buff, ...) ;
  86
  87 /* returns true if the buffer was created via
  88    newBuffer (vs. newBufferByCharP) */
  89 bool isDeletable (Buffer buff) ;
  90
  91 /* Dups the array including taking out references on the Buffers
  92    inside. Return value must be freed (or given to freeBufferArray) */
  93 Buffer *dupBufferArray (Buffer *array) ;
  94
  95 /* return the number of non-NULL elements in the array. */
  96 unsigned int bufferArrayLen (Buffer *array) ;
  97
  98 /* copies the contents of the SRC buffer into the DEST buffer and sets the
  99    data size appropriately. Returns false if src is bigger than dest. */
 100 bool copyBuffer (Buffer dest, Buffer src) ;
 101
 102 /* return the ref count on the buffer */
 103 unsigned int bufferRefCount (Buffer buff) ;
 104
 105 /* insert a null byte at the end of the data region */
 106 void bufferAddNullByte (Buffer buff) ;
 107
 108 /* append the data of src to the data of dest, if dest is big enough */
 109 bool concatBuffer (Buffer dest, Buffer src) ;
 110
 111 /* expand the buffer's memory by the given AMT */
 112 bool expandBuffer (Buffer buff, size_t amt) ;
 113
 114 /* Expand the buffer (if necessary) and insert carriage returns before very
 115    line feed. Adjusts the data size. The base address may change
 116    afterwards. */
 117 bool nntpPrepareBuffer (Buffer buffer) ;
 118
 119 #endif /* buffer_h__ */