1 #ifndef CONNECT___NCBI_BUFFER__H 2 #define CONNECT___NCBI_BUFFER__H 3 4 /* $Id: ncbi_buffer.h,v 6.21 2016/02/03 16:19:16 fukanchi Exp $ 5 * =========================================================================== 6 * 7 * PUBLIC DOMAIN NOTICE 8 * National Center for Biotechnology Information 9 * 10 * This software/database is a "United States Government Work" under the 11 * terms of the United States Copyright Act. It was written as part of 12 * the author's official duties as a United States Government employee and 13 * thus cannot be copyrighted. This software/database is freely available 14 * to the public for use. The National Library of Medicine and the U.S. 15 * Government have not placed any restriction on its use or reproduction. 16 * 17 * Although all reasonable efforts have been taken to ensure the accuracy 18 * and reliability of the software and data, the NLM and the U.S. 19 * Government do not and cannot warrant the performance or results that 20 * may be obtained by using this software or data. The NLM and the U.S. 21 * Government disclaim all warranties, express or implied, including 22 * warranties of performance, merchantability or fitness for any particular 23 * purpose. 24 * 25 * Please cite the author in any work or product based on this material. 26 * 27 * =========================================================================== 28 * 29 * Author: Denis Vakatov, Anton Lavrentiev 30 * 31 * File Description: 32 * Memory-resident storage area (to be used e.g. in I/O buffering) 33 * 34 * Handle: BUF 35 * 36 * Functions: 37 * BUF_SetChunkSize 38 * BUF_Size 39 * BUF_Prepend[Ex] 40 * BUF_Append[Ex] 41 * BUF_Write 42 * BUF_Pushback 43 * BUF_Peek 44 * BUF_PeekAt 45 * BUF_PeekAtCB 46 * BUF_Read 47 * BUF_Erase 48 * BUF_Splice 49 * BUF_Destroy 50 * 51 */ 52 53 #include <connect/connect_export.h> 54 #include <stddef.h> /* ...to define "size_t"... */ 55 56 57 /** @addtogroup BuffServices 58 * 59 * @{ 60 */ 61 62 63 #ifdef __cplusplus 64 extern "C" { 65 #endif 66 67 68 struct SNcbiBuf; 69 typedef struct SNcbiBuf* BUF; /* handle of a buffer */ 70 71 72 /*! 73 * Set minimal size of a buffer memory chunk. 74 * Return the actually set chunk size on success; zero on error. 75 * NOTE: if "*pBuf" == NULL then create it; 76 * if "chunk_size" is passed 0 then set it to BUF_DEF_CHUNK_SIZE. 77 */ 78 #define BUF_DEF_CHUNK_SIZE 1024 79 extern NCBI_XCONNECT_EXPORT size_t BUF_SetChunkSize 80 (BUF* pBuf, 81 size_t chunk_size 82 ); 83 84 85 /*! 86 * Return the number of bytes stored in "buf". 87 * NOTE: return 0 if "buf" == NULL. 88 */ 89 extern NCBI_XCONNECT_EXPORT size_t BUF_Size(BUF buf); 90 91 92 /*! 93 * Prepend a block of data (of the specified size) at the beginning of the 94 * buffer (to be read first). Note that unlike BUF_Pushback(), in this call 95 * the data is not copied into the buffer but instead is just linked in from 96 * the original location. Return non-zero (true) if succeeded, zero (false) 97 * if failed. 98 */ 99 extern NCBI_XCONNECT_EXPORT int/*bool*/ BUF_PrependEx 100 (BUF* pBuf, 101 void* base, /* base to be "free"d when the buffer chunk is unlinked */ 102 size_t alloc_size, /* usable size of "data" (0 to make the use read-only) */ 103 void* data, /* points to data to be prepended by linking in the list */ 104 size_t size /* size of "data" occupied */ 105 ); 106 107 108 /*! 109 * Equivalent to BUF_PrependEx(pBuf, 0, 0, data, size) 110 * NOTE: the prepended chunk is thus read-only and will not be auto-freed. 111 */ 112 113 extern NCBI_XCONNECT_EXPORT int/*bool*/ BUF_Prepend 114 (BUF* pBuf, 115 const void* data, 116 size_t size 117 ); 118 119 120 /*! 121 * Append a block of data (of the specified size) past the end of the buffer 122 * (to be read last). Note that unlike BUF_Write(), in this call the data is 123 * not copied to the buffer but instead is just linked in from the original 124 * location. Return non-zero (true) if succeeded, zero (false) if failed. 125 */ 126 extern NCBI_XCONNECT_EXPORT int/*bool*/ BUF_AppendEx 127 (BUF* pBuf, 128 void* base, /* base to be "free"d when the chunk is unlinked */ 129 size_t alloc_size, /* usable size of "data" (0 to make the use read-only) */ 130 void* data, /* points to data to be appended by linking in the list */ 131 size_t size /* size of "data" occupied */ 132 ); 133 134 135 /*! 136 * Equivalent to BUF_AppendEx(pBuf, 0, 0, data, size) 137 * NOTE: the appended chunk is thus read-only and will not be auto-freed. 138 */ 139 extern NCBI_XCONNECT_EXPORT int/*bool*/ BUF_Append 140 (BUF* pBuf, 141 const void* data, 142 size_t size 143 ); 144 145 146 /*! 147 * Add new data to the end of "*pBuf" (to be read last). 148 * On error (failed memory allocation), return zero value; 149 * otherwise return non-zero (i.e. including when "size" passed as 0). 150 * NOTE: if "*pBuf" == NULL then create it if necessary (e.g. if size != 0). 151 * NOTE: writing immediately past the end of the data into an unoccupied space 152 * of a chunk that was previosuly appended with BUF_AppendEx() results in a 153 * zero copy operation (just the pointers updated as necessary). 154 */ 155 extern NCBI_XCONNECT_EXPORT /*bool*/int BUF_Write 156 (BUF* pBuf, 157 const void* data, 158 size_t size 159 ); 160 161 162 /*! 163 * Write the data to the very beginning of "*pBuf" (to be read first). 164 * On error (failed memory allocation), return zero value. 165 * NOTE: if "*pBuf" == NULL then create it. 166 */ 167 extern NCBI_XCONNECT_EXPORT /*bool*/int BUF_Pushback 168 (BUF* pBuf, 169 const void* data, 170 size_t size 171 ); 172 173 174 /*! 175 * Equivalent to "BUF_PeekAt(buf, 0, data, size)", see description below. 176 */ 177 extern NCBI_XCONNECT_EXPORT size_t BUF_Peek 178 (BUF buf, 179 void* data, 180 size_t size 181 ); 182 183 184 /*! 185 * Copy up to "size" bytes stored in "buf" (starting at position "pos") 186 * to "data". 187 * Return the # of copied bytes (can be less than "size"). 188 * Return zero and do nothing if "buf" is NULL or "pos" >= BUF_Size(buf). 189 * Do nothing and return min(BUF_Size(buf)-pos, size) if "data" is NULL. 190 */ 191 extern NCBI_XCONNECT_EXPORT size_t BUF_PeekAt 192 (BUF buf, 193 size_t pos, 194 void* data, 195 size_t size 196 ); 197 198 199 /*! 200 * Call "callback" repeatedly on up to "size" bytes stored in "buf" (starting 201 * at position "pos"), in chunks. Pass "cbdata" as an opaque parameter to the 202 * "callback". Processing stops when all buffer bytes (but no more than 203 * "size" bytes) have been visited by the "callback", or when the "callback" 204 * returns a value less than its passed "size" argument (the "callback" may 205 * _not_ return a value greater than its "size" argument!). 206 * Return the # of processed bytes (can be less than "size"). 207 * Return zero and do nothing if "buf" is NULL or "pos" >= BUF_Size(buf). 208 * Do nothing and return min(BUF_Size(buf)-pos, size) if "callback" is NULL. 209 */ 210 extern NCBI_XCONNECT_EXPORT size_t BUF_PeekAtCB 211 (BUF buf, 212 size_t pos, 213 size_t (*callback)(void* cbdata, const void* buf, size_t size), 214 void* cbdata, 215 size_t size 216 ); 217 218 219 /*! 220 * Copy up to "size" bytes stored in "buf" to "data" and remove the copied 221 * data from the "buf". 222 * Return the # of copied-and/or-removed bytes (can be less than "size"). 223 * NOTE: if "buf" == NULL then do nothing and return 0 224 * if "data" == NULL then do not copy data anywhere(still, remove it) 225 */ 226 extern NCBI_XCONNECT_EXPORT size_t BUF_Read 227 (BUF buf, 228 void* data, 229 size_t size 230 ); 231 232 233 /*! 234 * Make the buffer empty. 235 * NOTE: do nothing if "buf" == NULL. 236 */ 237 extern NCBI_XCONNECT_EXPORT void BUF_Erase(BUF buf); 238 239 240 /*! 241 * Append all contents of the source buffer "src" to the destination buffer 242 * "*dst", making the source buffer empty (as with BUF_Erase(src)). 243 * Return non-zero if successful; 0 in case of an error. 244 * NOTE: do nothing if "src" is either NULL or contains no data. 245 */ 246 extern NCBI_XCONNECT_EXPORT int/*bool*/ BUF_Splice(BUF* dst, BUF src); 247 248 249 /*! 250 * Destroy all internal data. 251 * NOTE: do nothing if "buf" == NULL. 252 */ 253 extern NCBI_XCONNECT_EXPORT void BUF_Destroy(BUF buf); 254 255 256 #ifdef __cplusplus 257 } 258 #endif 259 260 261 /* @} */ 262 263 #endif /* CONNECT___NCBI_BUFFER__H */ 264