root/src/include/private/ftdm_buffer.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /*
   2  * Copyright (c) 2007, Anthony Minessale II
   3  * All rights reserved.
   4  * 
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 
   9  * * Redistributions of source code must retain the above copyright
  10  * notice, this list of conditions and the following disclaimer.
  11  * 
  12  * * Redistributions in binary form must reproduce the above copyright
  13  * notice, this list of conditions and the following disclaimer in the
  14  * documentation and/or other materials provided with the distribution.
  15  * 
  16  * * Neither the name of the original author; nor the names of any contributors
  17  * may be used to endorse or promote products derived from this software
  18  * without specific prior written permission.
  19  * 
  20  * 
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER
  25  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  26  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  27  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  28  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  29  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  30  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  31  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33 
  34 #ifndef FTDM_BUFFER_H
  35 #define FTDM_BUFFER_H
  36 
  37 #include "freetdm.h"
  38 
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42 
  43 /**
  44  * @defgroup ftdm_buffer Buffer Routines
  45  * @ingroup buffer
  46  * The purpose of this module is to make a plain buffering interface that can be used for read/write buffers
  47  * throughout the application.
  48  * @{
  49  */
  50 struct ftdm_buffer;
  51 typedef struct ftdm_buffer ftdm_buffer_t;
  52 
  53 /*! \brief Allocate a new dynamic ftdm_buffer 
  54  * \param buffer returned pointer to the new buffer
  55  * \param blocksize length to realloc by as data is added
  56  * \param start_len ammount of memory to reserve initially
  57  * \param max_len length the buffer is allowed to grow to
  58  * \return status
  59  */
  60 FT_DECLARE(ftdm_status_t) ftdm_buffer_create(ftdm_buffer_t **buffer, ftdm_size_t blocksize, ftdm_size_t start_len, ftdm_size_t max_len);
  61 
  62 /*! \brief Get the length of a ftdm_buffer_t 
  63  * \param buffer any buffer of type ftdm_buffer_t
  64  * \return int size of the buffer.
  65  */
  66 FT_DECLARE(ftdm_size_t) ftdm_buffer_len(ftdm_buffer_t *buffer);
  67 
  68 /*! \brief Get the freespace of a ftdm_buffer_t 
  69  * \param buffer any buffer of type ftdm_buffer_t
  70  * \return int freespace in the buffer.
  71  */
  72 FT_DECLARE(ftdm_size_t) ftdm_buffer_freespace(ftdm_buffer_t *buffer);
  73 
  74 /*! \brief Get the in use amount of a ftdm_buffer_t 
  75  * \param buffer any buffer of type ftdm_buffer_t
  76  * \return int ammount of buffer curently in use
  77  */
  78 FT_DECLARE(ftdm_size_t) ftdm_buffer_inuse(ftdm_buffer_t *buffer);
  79 
  80 /*! \brief Read data from a ftdm_buffer_t up to the ammount of datalen if it is available.  Remove read data from buffer. 
  81  * \param buffer any buffer of type ftdm_buffer_t
  82  * \param data pointer to the read data to be returned
  83  * \param datalen amount of data to be returned
  84  * \return int ammount of data actually read
  85  */
  86 FT_DECLARE(ftdm_size_t) ftdm_buffer_read(ftdm_buffer_t *buffer, void *data, ftdm_size_t datalen);
  87 
  88 /*! \brief Read data endlessly from a ftdm_buffer_t 
  89  * \param buffer any buffer of type ftdm_buffer_t
  90  * \param data pointer to the read data to be returned
  91  * \param datalen amount of data to be returned
  92  * \return int ammount of data actually read
  93  * \note Once you have read all the data from the buffer it will loop around.
  94  */
  95 FT_DECLARE(ftdm_size_t) ftdm_buffer_read_loop(ftdm_buffer_t *buffer, void *data, ftdm_size_t datalen);
  96 
  97 /*! \brief Assign a number of loops to read
  98  * \param buffer any buffer of type ftdm_buffer_t
  99  * \param loops the number of loops (-1 for infinite)
 100  */
 101 FT_DECLARE(void) ftdm_buffer_set_loops(ftdm_buffer_t *buffer, int32_t loops);
 102 
 103 /*! \brief Write data into a ftdm_buffer_t up to the length of datalen
 104  * \param buffer any buffer of type ftdm_buffer_t
 105  * \param data pointer to the data to be written
 106  * \param datalen amount of data to be written
 107  * \return int amount of buffer used after the write, or 0 if no space available
 108  */
 109 FT_DECLARE(ftdm_size_t) ftdm_buffer_write(ftdm_buffer_t *buffer, const void *data, ftdm_size_t datalen);
 110 
 111 /*! \brief Remove data from the buffer
 112  * \param buffer any buffer of type ftdm_buffer_t
 113  * \param datalen amount of data to be removed
 114  * \return int size of buffer, or 0 if unable to toss that much data
 115  */
 116 FT_DECLARE(ftdm_size_t) ftdm_buffer_toss(ftdm_buffer_t *buffer, ftdm_size_t datalen);
 117 
 118 /*! \brief Remove all data from the buffer
 119  * \param buffer any buffer of type ftdm_buffer_t
 120  */
 121 FT_DECLARE(void) ftdm_buffer_zero(ftdm_buffer_t *buffer);
 122 
 123 /*! \brief Destroy the buffer
 124  * \param buffer buffer to destroy
 125  * \note only neccessary on dynamic buffers (noop on pooled ones)
 126  */
 127 FT_DECLARE(void) ftdm_buffer_destroy(ftdm_buffer_t **buffer);
 128 
 129 /*! \brief Seek to offset from the beginning of the buffer
 130  * \param buffer buffer to seek
 131  * \param datalen offset in bytes
 132  * \return new position
 133  */
 134 FT_DECLARE(ftdm_size_t) ftdm_buffer_seek(ftdm_buffer_t *buffer, ftdm_size_t datalen);
 135 
 136 /** @} */
 137 
 138 FT_DECLARE(ftdm_size_t) ftdm_buffer_zwrite(ftdm_buffer_t *buffer, const void *data, ftdm_size_t datalen);
 139 
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143 
 144 #endif
 145 /* For Emacs:
 146  * Local Variables:
 147  * mode:c
 148  * indent-tabs-mode:t
 149  * tab-width:4
 150  * c-basic-offset:4
 151  * End:
 152  * For VIM:
 153  * vim:set softtabstop=4 shiftwidth=4 tabstop=4:
 154  */

/* [<][>][^][v][top][bottom][index][help] */