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 */