#ifndef GBFR_H #define GBFR_H /* ========================================================================== ** * Gbfr.h * * Copyright: * Copyright (C) 2011 by ubiqx Consulting, Inc. * * Email: ubiqx@ubiqx.com * * $Id: Gbfr.h 55 2011-04-26 03:34:55Z crh $ * * -------------------------------------------------------------------------- ** * * Description: * A byte buffer that grows as you use it. * * -------------------------------------------------------------------------- ** * * License: * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * * -------------------------------------------------------------------------- ** * * Notes: * * ========================================================================== ** */ #include /* Standard boolean type. */ /* -------------------------------------------------------------------------- ** * Defined Constants: * * STARTbSIZE - Starting buffer size, in bytes. * MAXbSIZE - Do not allow the buffers to grow larger than this. * 0x10000 == 65536 == 64KB */ #define STARTbSIZE 64 #define MAXbSIZE 0x10000 /* -------------------------------------------------------------------------- ** * Typedefs: */ typedef struct { int bSize; int len; char *bufr; } Gbfr; /* -------------------------------------------------------------------------- ** * Functions: */ Gbfr *initGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Initialize an unused Gbfr structure. * * Input: gb - The Gbfr to initialize. * * Output: A pointer to the initialized Gbfr structure (same as ), * or NULL if buffer memory could not be allocated. * * ------------------------------------------------------------------------ ** */ void clearGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Clear the current contents of a Gbfr. * * Input: gb - The Gbfr to clear. * * Output: * * ------------------------------------------------------------------------ ** */ Gbfr *resetGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Reset a used Gbfr. * * Input: gb - The Gbfr to be reset. * * Output: A pointer to the initialized Gbfr structure (same as ), * or NULL if buffer memory could not be reallocated. * * Notes: This function resets the Gbfr to an initial state. * The buffer is reallocated to the starting size, and set to * empty (at least the first byte is zeroed). The string * length is set to zero and the buffer size is set correctly. * * ------------------------------------------------------------------------ ** */ int growGbfr( Gbfr *gb, const int len ); /* ------------------------------------------------------------------------ ** * Ensure that there are at least free bytes in the Gbfr bufr. * * Input: gb - Pointer to the Gbfr to grow. * len - Minimum number of free bytes we require. * * Output: The free bytes now available in the Gbfr buffer. * If the buffer cannot be expanded, the function returns -1 and * the buffer contents are no longer considered valid. * * ------------------------------------------------------------------------ ** */ int concatGbfr( Gbfr *gb, const char *src, const int len ); /* ------------------------------------------------------------------------ ** * Concatenate a chunk of bytes to the end of a Gbfr. * * Input: gb - The Gbfr to which the new bytes will be concatenated. * src - Byte array from which bytes will be copied into the * Gbfr. * len - Number of bytes of to copy. * * Output: The number of bytes in use in , or -1 if the * buffer could not be extended to the required size. * * Notes: If -1 is returned, the contents of the Gbfr are no longer * valid. * * These are not handled as string buffers; No NUL terminator * is added. Gbfrs are length-delimited arrays of bytes. * * ------------------------------------------------------------------------ ** */ int addcGbfr( Gbfr *gb, const unsigned char b ); /* ------------------------------------------------------------------------ ** * Append a byte to the tail end of a Gbfr. * * Input: gb - Pointer to the Gbfr. * b - The byte to be appended to the string. * * Output: The number of bytes of the Gbfr now in use, or -1 if the byte * could not be added. * * ------------------------------------------------------------------------ ** */ bool isemptyGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Return true if the buffer in Gbfr is empty (or NULL). * * Input: gb - Pointer to the Gbfr. * * Output: True if the buffer is empty, else false. * * ------------------------------------------------------------------------ ** */ int lenGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Return the number of bytes currently stored in the Gbfr. * * Input: gb - Pointer to the Gbfr. * * Output: Length of the byte array stored in the Gbfr buffer. * * ------------------------------------------------------------------------ ** */ const char *bfrGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Return a pointer to the byte array currently stored in the Gbfr. * * Input: gb - Pointer to the Gbfr. * * Output: A pointer to the byte array, returned as "const" to prevent * fuddlement. NULL is returned if the Gbfr was not correctly * initialized. Note, however, that an uninitialized Gbfr may * point to random garbage. * * ------------------------------------------------------------------------ ** */ Gbfr *allocGbfr( unsigned int min ); /* ------------------------------------------------------------------------ ** * Allocate an expandable memory buffer. * * Input: min - Minimum initial size of the buffer. * * Output: On failure, NULL. Otherwise, a pointer to a structure that * contains a memory buffer at least as large as bytes. * * Notes: The value passed in to this function can be though of as * a sort of hint. The actual buffer allocated will be at least * bytes in size, but probably larger. Since the buffers * will grow if needed (up to a pre-set maximum), the goal when * calling this function is to find the sweet spot at which the * initial buffer size is just big enough, most of the time. * * See Also: * * ------------------------------------------------------------------------ ** */ Gbfr *freebfrGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Free only the buffer associated with a Gbfr. * * Input: gb - The Gbfr to be pruned. * * Output: A pointer to the now bufferless Gbfr. * * Notes: This function frees memory allocated and assigned to a Gbfr. * The Gbfr itself is *NOT* freed. * * See Also: * * ------------------------------------------------------------------------ ** */ void freeGbfr( Gbfr *gb ); /* ------------------------------------------------------------------------ ** * Free the buffer associated with a Gbfr and the Gbfr structure as well. * * Input: gb - A pointer to the Gbfr to be freed. * * Output: * * Notes: This function frees both the buffer managed by the Gbfr * structure and the Gbfr structure itself. Both must have been * allocated from the heap. * * See Also: , * * ------------------------------------------------------------------------ ** */ /* ========================================================================== */ #endif /* GBFR_H */