gatchat/ringbuffer.h

   1 /*
   2  *
   3  *  AT chat library with GLib integration
   4  *
   5  *  Copyright (C) 2008-2011  Intel Corporation. All rights reserved.
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License version 2 as
   9  *  published by the Free Software Foundation.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  */
  21
  22 struct ring_buffer;
  23
  24 /*!
  25  * Creates a new ring buffer with capacity size
  26  */
  27 struct ring_buffer *ring_buffer_new(unsigned int size);
  28
  29 /*!
  30  * Frees the resources allocated for the ring buffer
  31  */
  32 void ring_buffer_free(struct ring_buffer *buf);
  33
  34 /*!
  35  * Returns the capacity of the ring buffer
  36  */
  37 int ring_buffer_capacity(struct ring_buffer *buf);
  38
  39 /*!
  40  * Resets the ring buffer, all data inside the buffer is lost
  41  */
  42 void ring_buffer_reset(struct ring_buffer *buf);
  43
  44 /*!
  45  * Writes data of size len into the ring buffer buf.  Returns -1 if the
  46  * write failed or the number of bytes written
  47  */
  48 int ring_buffer_write(struct ring_buffer *buf, const void *data,
  49                         unsigned int len);
  50
  51 /*!
  52  * Advances the write counter by len, this is meant to be used with
  53  * the ring_buffer_write_ptr function.  Returns the number of bytes
  54  * actually advanced (the capacity of the buffer)
  55  */
  56 int ring_buffer_write_advance(struct ring_buffer *buf, unsigned int len);
  57
  58 /*!
  59  * Returns the write pointer with write offset specified by offset.  Careful
  60  * not to write past the end of the buffer.  Use the ring_buffer_avail_no_wrap
  61  * function, and ring_buffer_write_advance.
  62  */
  63 unsigned char *ring_buffer_write_ptr(struct ring_buffer *buf,
  64                                         unsigned int offset);
  65
  66 /*!
  67  * Returns the number of free bytes available in the buffer
  68  */
  69 int ring_buffer_avail(struct ring_buffer *buf);
  70
  71 /*!
  72  * Returns the number of free bytes available in the buffer without wrapping
  73  */
  74 int ring_buffer_avail_no_wrap(struct ring_buffer *buf);
  75
  76 /*!
  77  * Reads data from the ring buffer buf into memory region pointed to by data.
  78  * A maximum of len bytes will be read.  Returns -1 if the read failed or
  79  * the number of bytes read
  80  */
  81 int ring_buffer_read(struct ring_buffer *buf, void *data,
  82                         unsigned int len);
  83
  84 /*!
  85  * Returns the read pointer with read offset specified by offset.  No bounds
  86  * checking is performed.  Be careful not to read past the end of the buffer.
  87  * Use the ring_buffer_len_no_wrap function, and ring_buffer_drain.
  88  */
  89 unsigned char *ring_buffer_read_ptr(struct ring_buffer *buf,
  90                                         unsigned int offset);
  91
  92 /*!
  93  * Returns the number of bytes currently available to be read in the buffer
  94  */
  95 int ring_buffer_len(struct ring_buffer *buf);
  96
  97 /*!
  98  * Returns the number of bytes currently available to be read in the buffer
  99  * without wrapping.
 100  */
 101 int ring_buffer_len_no_wrap(struct ring_buffer *buf);
 102
 103 /*!
 104  * Drains the ring buffer of len bytes.  Returns the number of bytes the
 105  * read counter was actually advanced.
 106  */
 107 int ring_buffer_drain(struct ring_buffer *buf, unsigned int len);