Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/circbuffer.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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 */