membuffer.h

00001 
00002 //
00003 // Copyright (c) 2000-2003 Intel Corporation 
00004 // All rights reserved. 
00005 //
00006 // Redistribution and use in source and binary forms, with or without 
00007 // modification, are permitted provided that the following conditions are met: 
00008 //
00009 // * Redistributions of source code must retain the above copyright notice, 
00010 // this list of conditions and the following disclaimer. 
00011 // * Redistributions in binary form must reproduce the above copyright notice, 
00012 // this list of conditions and the following disclaimer in the documentation 
00013 // and/or other materials provided with the distribution. 
00014 // * Neither name of Intel Corporation nor the names of its contributors 
00015 // may be used to endorse or promote products derived from this software 
00016 // without specific prior written permission.
00017 // 
00018 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00019 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00020 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
00021 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
00022 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00023 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
00024 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
00025 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
00026 // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00027 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
00028 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029 //
00031 
00032 #ifndef GENLIB_UTIL_MEMBUFFER_H
00033 #define GENLIB_UTIL_MEMBUFFER_H
00034 
00035 
00036 #include <stdlib.h>
00037 #include "util.h"
00038 
00039 #define MINVAL( a, b ) ( (a) < (b) ? (a) : (b) )
00040 #define MAXVAL( a, b ) ( (a) > (b) ? (a) : (b) )
00041 
00042 // pointer to a chunk of memory
00043 typedef struct // memptr
00044 {
00045         char    *buf;                   // start of memory (read/write)
00046         size_t  length;                 // length of memory (read-only)
00047 } memptr;
00048 
00049 
00050 // maintains a block of dynamically allocated memory
00051 // note: Total length/capacity should not exceed MAX_INT
00052 typedef struct // membuffer
00053 {
00054         char    *buf;                   // mem buffer; must not write beyond buf[length-1] (read/write)
00055         size_t  length;                 // length of buffer (read-only)
00056         size_t  capacity;               // total allocated memory (read-only)
00057         size_t  size_inc;               // used to increase size; MUST be > 0; (read/write)
00058 
00059         // default value of size_inc
00060         #define MEMBUF_DEF_SIZE_INC             5
00061 } membuffer;
00062 
00063 //--------------------------------------------------
00065 //--------------------------------------------------
00066 
00067 #ifdef __cplusplus
00068 extern "C" {
00069 #endif // __cplusplus
00070 
00071 /************************************************************************
00072 *       Function :      str_alloc
00073 *
00074 *       Parameters :
00075 *               IN const char* str ;    input string object
00076 *               IN size_t str_len ;             input string length
00077 *
00078 *       Description :   Allocate memory and copy information from the input 
00079 *               string to the newly allocated memory.
00080 *
00081 *       Return : char* ;
00082 *               Pointer to the newly allocated memory.
00083 *               NULL if memory cannot be allocated.
00084 *
00085 *       Note :
00086 ************************************************************************/
00087 char* str_alloc( IN const char* str, IN size_t str_len );
00088 
00089 /************************************************************************
00090 *       Function :      memptr_cmp
00091 *
00092 *       Parameters :
00093 *               IN memptr* m ;  input memory object
00094 *               IN const char* s ;      constatnt string for the memory object to be 
00095 *                                       compared with
00096 *
00097 *       Description : Compares characters of strings passed for number of 
00098 *               bytes. If equal for the number of bytes, the length of the bytes 
00099 *               determines which buffer is shorter.
00100 *
00101 *       Return : int ;
00102 *               < 0 string1 substring less than string2 substring 
00103 *               0 string1 substring identical to string2 substring 
00104 *               > 0 string1 substring greater than string2 substring 
00105 *
00106 *       Note :
00107 ************************************************************************/
00108 int memptr_cmp( IN memptr* m, IN const char* s );
00109 
00110 /************************************************************************
00111 *       Function :      memptr_cmp_nocase
00112 *
00113 *       Parameters :
00114 *               IN memptr* m ;  input memory object
00115 *               IN const char* s ;      constatnt string for the memory object to be 
00116 *                                       compared with
00117 *
00118 *       Description : Compares characters of 2 strings irrespective of the 
00119 *               case for a specific count of bytes  If the character comparison 
00120 *               is the same the length of the 2 srings determines the shorter 
00121 *               of the 2 strings.
00122 *
00123 *       Return : int ;
00124 *               < 0 string1 substring less than string2 substring 
00125 *               0 string1 substring identical to string2 substring 
00126 *               > 0 string1 substring greater than string2 substring 
00127 *  
00128 *       Note :
00129 ************************************************************************/
00130 int memptr_cmp_nocase( IN memptr* m, IN const char* s );
00131 
00132 
00133 /************************************************************************
00134 *       Function :      membuffer_set_size
00135 *
00136 *       Parameters :
00137 *               INOUT membuffer* m ;    buffer whose size is to be modified
00138 *               IN size_t new_length ;  new size to which the buffer will be 
00139 *                                       modified
00140 *
00141 *       Description : Increases or decreases buffer cap so that at least
00142 *          'new_length' bytes can be stored
00143 *
00144 *       Return : int ;
00145 *               UPNP_E_SUCCESS - On Success
00146 *               UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
00147 *
00148 *       Note :
00149 ************************************************************************/
00150 int membuffer_set_size( INOUT membuffer* m, IN size_t new_length );
00151 
00152 /************************************************************************
00153 *       Function :      membuffer_init
00154 *
00155 *       Parameters :
00156 *               INOUT membuffer* m ; buffer     to be initialized
00157 *
00158 *       Description : Wrapper to membuffer_initialize().
00159 *               Set the size of the buffer to MEMBUF_DEF_SIZE_INC
00160 *               Initializes m->buf to NULL, length=0
00161 *
00162 *       Return : void ;
00163 *
00164 *       Note :
00165 ************************************************************************/
00166 void membuffer_init( INOUT membuffer* m );
00167 
00168 /************************************************************************
00169 *       Function :      membuffer_destroy
00170 *
00171 *       Parameters :
00172 *               INOUT membuffer* m ;    buffer to be destroyed
00173 *
00174 *       Description : Free's memory allocated for membuffer* m.
00175 *
00176 *       Return : void ;
00177 *
00178 *       Note :
00179 ************************************************************************/
00180 void membuffer_destroy( INOUT membuffer* m );
00181 
00182 
00183 /************************************************************************
00184 *       Function :      membuffer_assign
00185 *
00186 *       Parameters :
00187 *               INOUT membuffer* m ; buffer whose memory is to be allocated and 
00188 *                                       assigned.
00189 *               IN const void* buf ; source buffer whose contents will be copied
00190 *               IN size_t buf_len ;      length of the source buffer
00191 *
00192 *       Description : Allocate memory to membuffer* m and copy the contents 
00193 *               of the in parameter IN const void* buf.
00194 *
00195 *       Return : int ;
00196 *        UPNP_E_SUCCESS
00197 *        UPNP_E_OUTOF_MEMORY
00198 *
00199 *       Note :
00200 ************************************************************************/
00201 int membuffer_assign( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
00202 
00203 /************************************************************************
00204 *       Function :      membuffer_assign_str
00205 *
00206 *       Parameters :
00207 *               INOUT membuffer* m ;    buffer to be allocated and assigned
00208 *               IN const char* c_str ;  source buffer whose contents will be 
00209 *                                       copied
00210 *
00211 *       Description : Wrapper function for membuffer_assign()
00212 *
00213 *       Return : int ;
00214 *        UPNP_E_SUCCESS
00215 *        UPNP_E_OUTOF_MEMORY
00216 *
00217 *       Note :
00218 ************************************************************************/
00219 int membuffer_assign_str( INOUT membuffer* m, IN const char* c_str );
00220 
00221 /************************************************************************
00222 *       Function :      membuffer_append
00223 *
00224 *       Parameters :
00225 *               INOUT membuffer* m ; buffer whose memory is to be appended.
00226 *               IN const void* buf ; source buffer whose contents will be 
00227 *                                       copied
00228 *               IN size_t buf_len ;     length of the source buffer
00229 *
00230 *       Description : Invokes function to appends data from a constant buffer 
00231 *               to the buffer 
00232 *
00233 *       Return : int ;
00234 *
00235 *       Note :
00236 ************************************************************************/
00237 int membuffer_append( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
00238 
00239 /************************************************************************
00240 *       Function :      membuffer_append_str
00241 *
00242 *       Parameters :
00243 *               INOUT membuffer* m ;    buffer whose memory is to be appended.
00244 *               IN const char* c_str ;  source buffer whose contents will be 
00245 *                                       copied
00246 *
00247 *       Description : Invokes function to appends data from a constant string 
00248 *               to the buffer   
00249 *
00250 *       Return : int ;
00251 *
00252 *       Note :
00253 ************************************************************************/
00254 int membuffer_append_str( INOUT membuffer* m, IN const char* c_str );
00255 
00256 /************************************************************************
00257 *       Function :      membuffer_insert
00258 *
00259 *       Parameters :
00260 *               INOUT membuffer* m ; buffer whose memory size is to be increased  
00261 *                                       and appended.
00262 *               IN const void* buf ; source buffer whose contents will be 
00263 *                                       copied
00264 *                IN size_t buf_len ; size of the source buffer
00265 *               int index ;     index to determine the bounds while movinf the data
00266 *
00267 *       Description : Allocates memory for the new data to be inserted. Does
00268 *               memory management by moving the data from the existing memory to 
00269 *               the newly allocated memory and then appending the new data.
00270 *
00271 *       Return : int ;
00272 *
00273 *       Note :
00274 ************************************************************************/
00275 int membuffer_insert( INOUT membuffer* m, IN const void* buf, IN size_t buf_len, int index );
00276 
00277 
00278 /************************************************************************
00279 *       Function :      membuffer_delete
00280 *
00281 *       Parameters :
00282 *               INOUT membuffer* m ; buffer whose memory size is to be decreased
00283 *                                       and copied to the odified location
00284 *               IN int index ;  index to determine bounds while moving data
00285 *               IN size_t num_bytes ;   number of bytes that the data needs to 
00286 *                                       shrink by
00287 *
00288 *       Description : Shrink the size of the buffer depending on the current 
00289 *               size of the bufer and te input parameters. Move contents from the 
00290 *               old buffer to the new sized buffer.
00291 *
00292 *       Return : void ;
00293 *
00294 *       Note :
00295 ************************************************************************/
00296 void membuffer_delete( INOUT membuffer* m, IN int index, IN size_t num_bytes );
00297 
00298 
00299 /************************************************************************
00300 *       Function :      membuffer_detach
00301 *
00302 *       Parameters :
00303 *               INOUT membuffer* m ; buffer to be returned and updated. 
00304 *
00305 *       Description : Detaches current buffer and returns it. The caller
00306 *               must free the returned buffer using free().
00307 *               After this call, length becomes 0.
00308 *
00309 *       Return : char* ;
00310 *               a pointer to the current buffer
00311 *
00312 *       Note :
00313 ************************************************************************/
00314 char* membuffer_detach( INOUT membuffer* m );
00315 
00316 /************************************************************************
00317 *       Function :      membuffer_attach
00318 *
00319 *       Parameters :
00320 *               INOUT membuffer* m ;    buffer to be updated
00321 *               IN char* new_buf ;       source buffer which will be assigned to the 
00322 *                                       buffer to be updated
00323 *               IN size_t buf_len ;     length of the source buffer 
00324 *
00325 *       Description : Free existing memory in membuffer and assign the new 
00326 *               buffer in its place.
00327 *
00328 *       Return : void ;
00329 *
00330 *       Note : 'new_buf' must be allocted using malloc or realloc so
00331 *               that it can be freed using free()
00332 ************************************************************************/
00333 void membuffer_attach( INOUT membuffer* m, IN char* new_buf, IN size_t buf_len );
00334 #ifdef __cplusplus
00335 }               // extern "C"
00336 #endif  // __cplusplus
00337 
00338 #endif // GENLIB_UTIL_H
Generated on Fri May 21 00:33:58 2010 for libUPnP by  doxygen 1.6.3