libUPnP  1.8.0
membuffer.h
1 //
3 // Copyright (c) 2000-2003 Intel Corporation
4 // All rights reserved.
5 //
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are met:
8 //
9 // * Redistributions of source code must retain the above copyright notice,
10 // this list of conditions and the following disclaimer.
11 // * Redistributions in binary form must reproduce the above copyright notice,
12 // this list of conditions and the following disclaimer in the documentation
13 // and/or other materials provided with the distribution.
14 // * Neither name of Intel Corporation nor the names of its contributors
15 // may be used to endorse or promote products derived from this software
16 // without specific prior written permission.
17 //
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
22 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
25 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
26 // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 //
31 
32 #ifndef GENLIB_UTIL_MEMBUFFER_H
33 #define GENLIB_UTIL_MEMBUFFER_H
34 
35 
36 #include <stdlib.h>
37 #include "util.h"
38 
39 #define MINVAL( a, b ) ( (a) < (b) ? (a) : (b) )
40 #define MAXVAL( a, b ) ( (a) > (b) ? (a) : (b) )
41 
42 // pointer to a chunk of memory
43 typedef struct // memptr
44 {
45  char *buf; // start of memory (read/write)
46  size_t length; // length of memory (read-only)
47 } memptr;
48 
49 
50 // maintains a block of dynamically allocated memory
51 // note: Total length/capacity should not exceed MAX_INT
52 typedef struct // membuffer
53 {
54  char *buf; // mem buffer; must not write beyond buf[length-1] (read/write)
55  size_t length; // length of buffer (read-only)
56  size_t capacity; // total allocated memory (read-only)
57  size_t size_inc; // used to increase size; MUST be > 0; (read/write)
58 
59  // default value of size_inc
60  #define MEMBUF_DEF_SIZE_INC 5
61 } membuffer;
62 
63 //--------------------------------------------------
65 //--------------------------------------------------
66 
67 #ifdef __cplusplus
68 extern "C" {
69 #endif // __cplusplus
70 
71 /************************************************************************
72 * Function : str_alloc
73 *
74 * Parameters :
75 * IN const char* str ; input string object
76 * IN size_t str_len ; input string length
77 *
78 * Description : Allocate memory and copy information from the input
79 * string to the newly allocated memory.
80 *
81 * Return : char* ;
82 * Pointer to the newly allocated memory.
83 * NULL if memory cannot be allocated.
84 *
85 * Note :
86 ************************************************************************/
87 char* str_alloc( IN const char* str, IN size_t str_len );
88 
89 /************************************************************************
90 * Function : memptr_cmp
91 *
92 * Parameters :
93 * IN memptr* m ; input memory object
94 * IN const char* s ; constatnt string for the memory object to be
95 * compared with
96 *
97 * Description : Compares characters of strings passed for number of
98 * bytes. If equal for the number of bytes, the length of the bytes
99 * determines which buffer is shorter.
100 *
101 * Return : int ;
102 * < 0 string1 substring less than string2 substring
103 * 0 string1 substring identical to string2 substring
104 * > 0 string1 substring greater than string2 substring
105 *
106 * Note :
107 ************************************************************************/
108 int memptr_cmp( IN memptr* m, IN const char* s );
109 
110 /************************************************************************
111 * Function : memptr_cmp_nocase
112 *
113 * Parameters :
114 * IN memptr* m ; input memory object
115 * IN const char* s ; constatnt string for the memory object to be
116 * compared with
117 *
118 * Description : Compares characters of 2 strings irrespective of the
119 * case for a specific count of bytes If the character comparison
120 * is the same the length of the 2 srings determines the shorter
121 * of the 2 strings.
122 *
123 * Return : int ;
124 * < 0 string1 substring less than string2 substring
125 * 0 string1 substring identical to string2 substring
126 * > 0 string1 substring greater than string2 substring
127 *
128 * Note :
129 ************************************************************************/
130 int memptr_cmp_nocase( IN memptr* m, IN const char* s );
131 
132 
133 /************************************************************************
134 * Function : membuffer_set_size
135 *
136 * Parameters :
137 * INOUT membuffer* m ; buffer whose size is to be modified
138 * IN size_t new_length ; new size to which the buffer will be
139 * modified
140 *
141 * Description : Increases or decreases buffer cap so that at least
142 * 'new_length' bytes can be stored
143 *
144 * Return : int ;
145 * UPNP_E_SUCCESS - On Success
146 * UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
147 *
148 * Note :
149 ************************************************************************/
150 int membuffer_set_size( INOUT membuffer* m, IN size_t new_length );
151 
152 /************************************************************************
153 * Function : membuffer_init
154 *
155 * Parameters :
156 * INOUT membuffer* m ; buffer to be initialized
157 *
158 * Description : Wrapper to membuffer_initialize().
159 * Set the size of the buffer to MEMBUF_DEF_SIZE_INC
160 * Initializes m->buf to NULL, length=0
161 *
162 * Return : void ;
163 *
164 * Note :
165 ************************************************************************/
166 void membuffer_init( INOUT membuffer* m );
167 
168 /************************************************************************
169 * Function : membuffer_destroy
170 *
171 * Parameters :
172 * INOUT membuffer* m ; buffer to be destroyed
173 *
174 * Description : Free's memory allocated for membuffer* m.
175 *
176 * Return : void ;
177 *
178 * Note :
179 ************************************************************************/
180 void membuffer_destroy( INOUT membuffer* m );
181 
182 
183 /************************************************************************
184 * Function : membuffer_assign
185 *
186 * Parameters :
187 * INOUT membuffer* m ; buffer whose memory is to be allocated and
188 * assigned.
189 * IN const void* buf ; source buffer whose contents will be copied
190 * IN size_t buf_len ; length of the source buffer
191 *
192 * Description : Allocate memory to membuffer* m and copy the contents
193 * of the in parameter IN const void* buf.
194 *
195 * Return : int ;
196 * UPNP_E_SUCCESS
197 * UPNP_E_OUTOF_MEMORY
198 *
199 * Note :
200 ************************************************************************/
201 int membuffer_assign( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
202 
203 /************************************************************************
204 * Function : membuffer_assign_str
205 *
206 * Parameters :
207 * INOUT membuffer* m ; buffer to be allocated and assigned
208 * IN const char* c_str ; source buffer whose contents will be
209 * copied
210 *
211 * Description : Wrapper function for membuffer_assign()
212 *
213 * Return : int ;
214 * UPNP_E_SUCCESS
215 * UPNP_E_OUTOF_MEMORY
216 *
217 * Note :
218 ************************************************************************/
219 int membuffer_assign_str( INOUT membuffer* m, IN const char* c_str );
220 
221 /************************************************************************
222 * Function : membuffer_append
223 *
224 * Parameters :
225 * INOUT membuffer* m ; buffer whose memory is to be appended.
226 * IN const void* buf ; source buffer whose contents will be
227 * copied
228 * IN size_t buf_len ; length of the source buffer
229 *
230 * Description : Invokes function to appends data from a constant buffer
231 * to the buffer
232 *
233 * Return : int ;
234 *
235 * Note :
236 ************************************************************************/
237 int membuffer_append( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
238 
239 /************************************************************************
240 * Function : membuffer_append_str
241 *
242 * Parameters :
243 * INOUT membuffer* m ; buffer whose memory is to be appended.
244 * IN const char* c_str ; source buffer whose contents will be
245 * copied
246 *
247 * Description : Invokes function to appends data from a constant string
248 * to the buffer
249 *
250 * Return : int ;
251 *
252 * Note :
253 ************************************************************************/
254 int membuffer_append_str( INOUT membuffer* m, IN const char* c_str );
255 
256 /************************************************************************
257 * Function : membuffer_insert
258 *
259 * Parameters :
260 * INOUT membuffer* m ; buffer whose memory size is to be increased
261 * and appended.
262 * IN const void* buf ; source buffer whose contents will be
263 * copied
264 * IN size_t buf_len ; size of the source buffer
265 * int index ; index to determine the bounds while movinf the data
266 *
267 * Description : Allocates memory for the new data to be inserted. Does
268 * memory management by moving the data from the existing memory to
269 * the newly allocated memory and then appending the new data.
270 *
271 * Return : int ;
272 *
273 * Note :
274 ************************************************************************/
275 int membuffer_insert( INOUT membuffer* m, IN const void* buf, IN size_t buf_len, int index );
276 
277 
278 /************************************************************************
279 * Function : membuffer_delete
280 *
281 * Parameters :
282 * INOUT membuffer* m ; buffer whose memory size is to be decreased
283 * and copied to the odified location
284 * IN int index ; index to determine bounds while moving data
285 * IN size_t num_bytes ; number of bytes that the data needs to
286 * shrink by
287 *
288 * Description : Shrink the size of the buffer depending on the current
289 * size of the bufer and te input parameters. Move contents from the
290 * old buffer to the new sized buffer.
291 *
292 * Return : void ;
293 *
294 * Note :
295 ************************************************************************/
296 void membuffer_delete( INOUT membuffer* m, IN int index, IN size_t num_bytes );
297 
298 
299 /************************************************************************
300 * Function : membuffer_detach
301 *
302 * Parameters :
303 * INOUT membuffer* m ; buffer to be returned and updated.
304 *
305 * Description : Detaches current buffer and returns it. The caller
306 * must free the returned buffer using free().
307 * After this call, length becomes 0.
308 *
309 * Return : char* ;
310 * a pointer to the current buffer
311 *
312 * Note :
313 ************************************************************************/
314 char* membuffer_detach( INOUT membuffer* m );
315 
316 /************************************************************************
317 * Function : membuffer_attach
318 *
319 * Parameters :
320 * INOUT membuffer* m ; buffer to be updated
321 * IN char* new_buf ; source buffer which will be assigned to the
322 * buffer to be updated
323 * IN size_t buf_len ; length of the source buffer
324 *
325 * Description : Free existing memory in membuffer and assign the new
326 * buffer in its place.
327 *
328 * Return : void ;
329 *
330 * Note : 'new_buf' must be allocted using malloc or realloc so
331 * that it can be freed using free()
332 ************************************************************************/
333 void membuffer_attach( INOUT membuffer* m, IN char* new_buf, IN size_t buf_len );
334 #ifdef __cplusplus
335 } // extern "C"
336 #endif // __cplusplus
337 
338 #endif // GENLIB_UTIL_H
Definition: membuffer.h:52
Definition: membuffer.h:43