3 * Testy, Virtual(-izable) Buffer of guint8*'s
5 * "Testy" -- the buffer gets mad when an attempt is made to access data
6 * beyond the bounds of the buffer. An exception is thrown.
8 * "Virtual" -- the buffer can have its own data, can use a subset of
9 * the data of a backing tvbuff, or can be a composite of
12 * $Id: tvbuff.h,v 1.6 2000/11/13 07:19:37 guy Exp $
14 * Copyright (c) 2000 by Gilbert Ramirez <gram@xiexie.org>
16 * Ethereal - Network traffic analyzer
17 * By Gerald Combs <gerald@zing.org>
18 * Copyright 1998 Gerald Combs
21 * This program is free software; you can redistribute it and/or
22 * modify it under the terms of the GNU General Public License
23 * as published by the Free Software Foundation; either version 2
24 * of the License, or (at your option) any later version.
26 * This program is distributed in the hope that it will be useful,
27 * but WITHOUT ANY WARRANTY; without even the implied warranty of
28 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
29 * GNU General Public License for more details.
31 * You should have received a copy of the GNU General Public License
32 * along with this program; if not, write to the Free Software
33 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
40 #include "exceptions.h"
42 typedef struct tvbuff tvbuff_t;
44 typedef void (*tvbuff_free_cb_t)(void*);
46 /* The different types of tvbuff's */
53 /* TVBUFF_REAL_DATA contains a guint8* that points to real data.
54 * The data is allocated and contiguous.
56 * TVBUFF_SUBSET has a backing tvbuff. The TVBUFF_SUBSET is a "window"
57 * through which the program sees only a portion of the backing tvbuff.
59 * TVBUFF_COMPOSITE combines multiple tvbuffs sequentually to produce
60 * a larger byte array.
62 * tvbuff's of any type can be used as the backing-tvbuff of a
63 * TVBUFF_SUBSET or as the member of a TVBUFF_COMPOSITE.
64 * TVBUFF_COMPOSITEs can have member-tvbuffs of different types.
66 * Once a tvbuff is create/initialized/finalized, the tvbuff is read-only.
67 * That is, it cannot point to any other data. A new tvbuff must be created if
68 * you want a tvbuff that points to other data.
72 /* "class" initialization. Called once during execution of program
73 * so that tvbuff.c can initialize its data. */
74 void tvbuff_init(void);
76 /* "class" cleanup. Called once during execution of program
77 * so that tvbuff.c can clean up its data. */
78 void tvbuff_cleanup(void);
81 /* Returns a pointer to a newly initialized tvbuff. Note that
82 * tvbuff's of types TVBUFF_SUBSET and TVBUFF_COMPOSITE
83 * require further initialization via the appropriate functions */
84 tvbuff_t* tvb_new(tvbuff_type);
86 /* Marks a tvbuff for freeing. The guint8* data of a TVBUFF_REAL_DATA
87 * is *never* freed by the tvbuff routines. The tvbuff itself is actually freed
88 * once its usage count drops to 0.
90 * Usage counts increment for any time the tvbuff is
91 * used as a member of another tvbuff, i.e., as the backing buffer for
92 * a TVBUFF_SUBSET or as a member of a TVBUFF_COMPOSITE.
94 * Although you may call tvb_free(), the tvbuff may still be in use
95 * by other tvbuff's (TVBUFF_SUBSET or TVBUFF_COMPOSITE), so it is not
96 * safe, unless you know otherwise, to free your guint8* data. If you
97 * cannot be sure that your TVBUFF_REAL_DATA is not in use by another
98 * tvbuff, register a callback with tvb_set_free_cb(); when your tvbuff
99 * is _really_ freed, then your callback will be called, and at that time
100 * you can free your original data.
102 * The caller can artificially increment/decrement the usage count
103 * with tvbuff_increment_usage_count()/tvbuff_decrement_usage_count().
105 void tvb_free(tvbuff_t*);
107 /* Free the tvbuff_t and all tvbuff's created from it. */
108 void tvb_free_chain(tvbuff_t*);
110 /* Both return the new usage count, after the increment or decrement */
111 guint tvb_increment_usage_count(tvbuff_t*, guint count);
113 /* If a decrement causes the usage count to drop to 0, a the tvbuff
114 * is immediately freed. Be sure you know exactly what you're doing
115 * if you decide to use this function, as another tvbuff could
116 * still have a pointer to the just-freed tvbuff, causing corrupted data
117 * or a segfault in the future */
118 guint tvb_decrement_usage_count(tvbuff_t*, guint count);
120 /* Set a callback function to call when a tvbuff is actually freed
121 * (once the usage count drops to 0). One argument is passed to
122 * that callback --- the guint* that points to the real data.
123 * Obviously, this only applies to a TVBUFF_REAL_DATA tvbuff. */
124 void tvb_set_free_cb(tvbuff_t*, tvbuff_free_cb_t);
127 /* Sets parameters for TVBUFF_REAL_DATA. Can throw ReportedBoundsError. */
128 void tvb_set_real_data(tvbuff_t*, const guint8* data, guint length, gint reported_length);
130 /* Combination of tvb_new() and tvb_set_real_data(). Can throw ReportedBoundsError. */
131 tvbuff_t* tvb_new_real_data(const guint8* data, guint length, gint reported_length);
134 /* Define the subset of the backing buffer to use.
136 * 'backing_offset' can be negative, to indicate bytes from
137 * the end of the backing buffer.
139 * 'backing_length' can be 0, although the usefulness of the buffer would
142 * 'backing_length' of -1 means "to the end of the backing buffer"
144 * Will throw BoundsError if 'backing_offset'/'length'
145 * is beyond the bounds of the backing tvbuff.
146 * Can throw ReportedBoundsError. */
147 void tvb_set_subset(tvbuff_t* tvb, tvbuff_t* backing,
148 gint backing_offset, gint backing_length, gint reported_length);
150 /* Combination of tvb_new() and tvb_set_subset()
151 * Can throw ReportedBoundsError. */
152 tvbuff_t* tvb_new_subset(tvbuff_t* backing,
153 gint backing_offset, gint backing_length, gint reported_length);
156 /* Both tvb_composite_append and tvb_composite_prepend can throw
157 * BoundsError if member_offset/member_length goes beyond bounds of
158 * the 'member' tvbuff. */
160 /* Append to the list of tvbuffs that make up this composite tvbuff */
161 void tvb_composite_append(tvbuff_t* tvb, tvbuff_t* member);
163 /* Prepend to the list of tvbuffs that make up this composite tvbuff */
164 void tvb_composite_prepend(tvbuff_t* tvb, tvbuff_t* member);
166 /* Helper function that calls tvb_new(TVBUFF_COMPOSITE).
167 * Provided only to maintain symmetry with other constructors */
168 tvbuff_t* tvb_new_composite(void);
170 /* Mark a composite tvbuff as initialized. No further appends or prepends
171 * occur, data access can finally happen after this finalization. */
172 void tvb_composite_finalize(tvbuff_t* tvb);
175 /* Get total length of buffer */
176 guint tvb_length(tvbuff_t*);
178 /* Computes bytes to end of buffer, from offset (which can be negative,
179 * to indicate bytes from end of buffer). Function returns -1 to
180 * indicate that offset is out of bounds. No exception is thrown. */
181 guint tvb_length_remaining(tvbuff_t*, gint offset);
183 /* Checks (w/o throwing exception) that the bytes referred to by 'offset'/'length'
184 * actualy exist in the buffer */
185 gboolean tvb_bytes_exist(tvbuff_t*, gint offset, gint length);
187 /* Checks (w/o throwing exception) that offset exists in buffer */
188 gboolean tvb_offset_exists(tvbuff_t*, gint offset);
190 /* Get reported length of buffer */
191 guint tvb_reported_length(tvbuff_t*);
193 /* Returns the offset from the first byte of real data. This is
194 * the same value as 'offset' in tvb_compat() */
195 gint tvb_raw_offset(tvbuff_t*);
197 /************** START OF ACCESSORS ****************/
198 /* All accessors will throw BoundsError or ReportedBoundsError if appropriate */
200 guint8 tvb_get_guint8(tvbuff_t*, gint offset);
202 guint16 tvb_get_ntohs(tvbuff_t*, gint offset);
203 guint32 tvb_get_ntoh24(tvbuff_t*, gint offset);
204 guint32 tvb_get_ntohl(tvbuff_t*, gint offset);
206 guint64 tvb_get_ntohll(tvbuff_t*, gint offset);
209 guint16 tvb_get_letohs(tvbuff_t*, gint offset);
210 guint32 tvb_get_letoh24(tvbuff_t*, gint offset);
211 guint32 tvb_get_letohl(tvbuff_t*, gint offset);
213 guint64 tvb_get_letohll(tvbuff_t*, gint offset);
216 /* Returns target for convenience. Does not suffer from possible
217 * expense of tvb_get_ptr(), since this routine is smart enough
218 * to copy data in chunks if the request range actually exists in
219 * different TVBUFF_REAL_DATA tvbuffs. This function assumes that the
220 * target memory is already allocated; it does not allocate or free the
222 guint8* tvb_memcpy(tvbuff_t*, guint8* target, gint offset, gint length);
224 /* It is the user's responsibility to g_free() the memory allocated by
225 * tvb_memdup(). Calls tvb_memcpy() */
226 guint8* tvb_memdup(tvbuff_t*, gint offset, gint length);
228 /* WARNING! This function is possibly expensive, temporarily allocating
229 * another copy of the packet data. Furthermore, it's dangerous because once
230 * this pointer is given to the user, there's no guarantee that the user will
231 * honor the 'length' and not overstep the boundaries of the buffer.
233 * The returned pointer is data that is internal to the tvbuff, so do not
234 * attempt to free it. Don't modify the data, either, because another tvbuff
235 * that might be using this tvbuff may have already copied that portion of
236 * the data (sometimes tvbuff's need to make copies of data, but that's the
237 * internal implementation that you need not worry about). Assume that the
238 * guint8* points to read-only data that the tvbuff manages.
240 * Return a pointer into our buffer if the data asked for via 'offset'/'length'
241 * is contiguous (which might not be the case for TVBUFF_COMPOSITE). If the
242 * data is not contiguous, a tvb_memdup() is called for the entire buffer
243 * and the pointer to the newly-contiguous data is returned. This dynamically-
244 * allocated memory will be freed when the tvbuff is freed, after the
245 * tvbuff_free_cb_t() is called, if any. */
246 guint8* tvb_get_ptr(tvbuff_t*, gint offset, gint length);
248 /* Find first occurence of any of the needles in tvbuff, starting at offset.
249 * Searches at most maxlength number of bytes; if maxlength is -1, searches
251 * Returns the offset of the found needle, or -1 if not found.
252 * Will not throw an exception, even if maxlength exceeds boundary of tvbuff;
253 * in that case, -1 will be returned if the boundary is reached before
255 gint tvb_find_guint8(tvbuff_t*, gint offset, guint maxlength, guint8 needle);
257 /* Find first occurence of any of the needles in tvbuff, starting at offset.
258 * Searches at most maxlength number of bytes. Returns the offset of the
259 * found needle, or -1 if not found. Will not throw an exception, even if
260 * maxlength exceeds boundary of tvbuff; in that case, -1 will be returned if
261 * the boundary is reached before finding needle. */
262 gint tvb_pbrk_guint8(tvbuff_t *, gint offset, guint maxlength, guint8 *needles);
264 /* Find length of string by looking for end of string ('\0'), up to
265 * 'maxlength' characters'; if 'maxlength' is -1, searches to end
267 * Returns -1 if 'maxlength' reached before finding EOS. */
268 gint tvb_strnlen(tvbuff_t*, gint offset, guint maxlength);
271 * Format the data in the tvb from offset for size ...
273 guint8 * tvb_format_text(tvbuff_t *tvb, gint offset, gint size);
275 /* Looks for a stringz (NUL-terminated string) in tvbuff and copies
276 * no more than maxlength number of bytes, including terminating NUL, to buffer.
277 * Returns length of string (not including terminating NUL), or -1 if the string was
278 * truncated in the buffer due to not having reached the terminating NUL.
279 * In this way, it acts like snprintf().
281 gint tvb_get_nstringz(tvbuff_t *tvb, gint offset, guint maxlength, guint8* buffer);
283 /* Like tvb_get_nstringz(), but never returns -1. The string is guaranteed to
284 * have a terminating NUL. If the string was truncated when copied into buffer,
285 * a NUL is placed at the end of buffer to terminate it.
287 gint tvb_get_nstringz0(tvbuff_t *tvb, gint offset, guint maxlength, guint8* buffer);
290 * Given a tvbuff, an offset into the tvbuff, and a length that starts
291 * at that offset (which may be -1 for "all the way to the end of the
292 * tvbuff"), find the end of the (putative) line that starts at the
293 * specified offset in the tvbuff, going no further than the specified
296 * Return the offset right past the end of the line as the return value,
297 * and return the offset of the EOL character(s) in "*eol".
299 gint tvb_find_line_end(tvbuff_t *tvb, gint offset, int len, gint *eol);
302 * Given a tvbuff, an offset into the tvbuff, and a length that starts
303 * at that offset (which may be -1 for "all the way to the end of the
304 * tvbuff"), find the end of the (putative) line that starts at the
305 * specified offset in the tvbuff, going no further than the specified
308 * However, treat quoted strings inside the buffer specially - don't
309 * treat newlines in quoted strings as line terminators.
311 * Return the length of the line (not counting the line terminator at
312 * the end), or the amount of data remaining in the buffer if we don't
313 * find a line terminator.
315 * Set "*next_offset" to the offset of the character past the line
316 * terminator, or past the end of the buffer if we don't find a line
319 gint tvb_find_line_end_unquoted(tvbuff_t *tvb, gint offset, int len,
322 /* Call strncmp after checking if enough chars left, otherwise return -1 */
323 gint tvb_strneql(tvbuff_t *tvb, gint offset, const guint8 *str, gint size);
325 /* Call strncasecmp after checking if enough chars left, otherwise return -1 */
326 gint tvb_strncaseeql(tvbuff_t *tvb, gint offset, const guint8 *str, gint size);
329 * Format a bunch of data from a tvbuff as bytes, returning a pointer
330 * to the string with the formatted data.
332 gchar *tvb_bytes_to_str(tvbuff_t *tvb, gint offset, gint len);
334 /************** END OF ACCESSORS ****************/
336 /* Sets pd and offset so that tvbuff's can be used with code
337 * that only understands pd/offset and not tvbuffs.
338 * This is the "compatibility" function */
339 void tvb_compat(tvbuff_t*, const guint8 **pd, int *offset);
341 #define tvb_create_from_top(offset) \
342 tvb_new_subset(pi.compat_top_tvb, (offset), \
343 pi.captured_len - (offset), pi.len - (offset))
345 #endif /* __TVBUFF_H__ */