libpurple/circbuffer.h

   1 /**
   2  * @file circbuffer.h Buffer Utility Functions
   3  * @ingroup core
   4  */
   5
   6 /* Purple is the legal property of its developers, whose names are too numerous
   7  * to list here.  Please refer to the COPYRIGHT file distributed with this
   8  * source distribution.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  23  */
  24 #ifndef _CIRCBUFFER_H
  25 #define _CIRCBUFFER_H
  26
  27 #include <glib.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 typedef struct _PurpleCircBuffer {
  34
  35         /** A pointer to the starting address of our chunk of memory. */
  36         gchar *buffer;
  37
  38         /** The incremental amount to increase this buffer by when
  39          *  the buffer is not big enough to hold incoming data, in bytes. */
  40         gsize growsize;
  41
  42         /** The length of this buffer, in bytes. */
  43         gsize buflen;
  44
  45         /** The number of bytes of this buffer that contain unread data. */
  46         gsize bufused;
  47
  48         /** A pointer to the next byte where new incoming data is
  49          *  buffered to. */
  50         gchar *inptr;
  51
  52         /** A pointer to the next byte of buffered data that should be
  53          *  read by the consumer. */
  54         gchar *outptr;
  55
  56 } PurpleCircBuffer;
  57
  58 /**
  59  * Creates a new circular buffer.  This will not allocate any memory for the
  60  * actual buffer until data is appended to it.
  61  *
  62  * @param growsize The amount that the buffer should grow the first time data
  63  *                 is appended and every time more space is needed.  Pass in
  64  *                 "0" to use the default of 256 bytes.
  65  *
  66  * @return The new PurpleCircBuffer. This should be freed with
  67  *         purple_circ_buffer_destroy when you are done with it
  68  */
  69 PurpleCircBuffer *purple_circ_buffer_new(gsize growsize);
  70
  71 /**
  72  * Dispose of the PurpleCircBuffer and free any memory used by it (including any
  73  * memory used by the internal buffer).
  74  *
  75  * @param buf The PurpleCircBuffer to free
  76  */
  77 void purple_circ_buffer_destroy(PurpleCircBuffer *buf);
  78
  79 /**
  80  * Append data to the PurpleCircBuffer.  This will grow the internal
  81  * buffer to fit the added data, if needed.
  82  *
  83  * @param buf The PurpleCircBuffer to which to append the data
  84  * @param src pointer to the data to copy into the buffer
  85  * @param len number of bytes to copy into the buffer
  86  */
  87 void purple_circ_buffer_append(PurpleCircBuffer *buf, gconstpointer src, gsize len);
  88
  89 /**
  90  * Determine the maximum number of contiguous bytes that can be read from the
  91  * PurpleCircBuffer.
  92  * Note: This may not be the total number of bytes that are buffered - a
  93  * subsequent call after calling purple_circ_buffer_mark_read() may indicate more
  94  * data is available to read.
  95  *
  96  * @param buf the PurpleCircBuffer for which to determine the maximum contiguous
  97  *            bytes that can be read.
  98  *
  99  * @return the number of bytes that can be read from the PurpleCircBuffer
 100  */
 101 gsize purple_circ_buffer_get_max_read(const PurpleCircBuffer *buf);
 102
 103 /**
 104  * Mark the number of bytes that have been read from the buffer.
 105  *
 106  * @param buf The PurpleCircBuffer to mark bytes read from
 107  * @param len The number of bytes to mark as read
 108  *
 109  * @return TRUE if we successfully marked the bytes as having been read, FALSE
 110  *         otherwise.
 111  */
 112 gboolean purple_circ_buffer_mark_read(PurpleCircBuffer *buf, gsize len);
 113
 114 #ifdef __cplusplus
 115 }
 116 #endif
 117
 118 #endif /* _CIRCBUFFER_H */