Update some comments.
We no longer have TVBUFF_ values corresponding to different types of tvbuff; we have, instead, a set of method pointers for the different types. Refer to the types by name, rather than by TVBUFF_ value. Expand the description of some fields in the tvbuff structure. Change-Id: I38b5281df247ddd66b4e39abfc129053a012d241 Reviewed-on: https://code.wireshark.org/review/27036 Reviewed-by: Guy Harris <guy@alum.mit.edu>
This commit is contained in:
parent
b545c60658
commit
d5dc4677ed
|
@ -335,7 +335,7 @@ run_tests(void)
|
|||
tvb_set_free_cb(tvb_large[i], g_free);
|
||||
}
|
||||
|
||||
/* Test the TVBUFF_REAL_DATA objects. */
|
||||
/* Test the "real" tvbuff objects. */
|
||||
test(tvb_small[0], "Small 0", small[0], small_length[0], small_reported_length[0]);
|
||||
test(tvb_small[1], "Small 1", small[1], small_length[1], small_reported_length[1]);
|
||||
test(tvb_small[2], "Small 2", small[2], small_length[2], small_reported_length[2]);
|
||||
|
@ -374,7 +374,7 @@ run_tests(void)
|
|||
tvb_subset[5] = tvb_new_subset_length_caplen(tvb_subset[2], 4, 8, 9);
|
||||
subset[5] = &small[1][4];
|
||||
|
||||
/* Test the TVBUFF_SUBSET objects. */
|
||||
/* Test the "subset" tvbuff objects. */
|
||||
test(tvb_subset[0], "Subset 0", subset[0], subset_length[0], subset_reported_length[0]);
|
||||
test(tvb_subset[1], "Subset 1", subset[1], subset_length[1], subset_reported_length[1]);
|
||||
test(tvb_subset[2], "Subset 2", subset[2], subset_length[2], subset_reported_length[2]);
|
||||
|
@ -464,7 +464,7 @@ run_tests(void)
|
|||
tvb_composite_append(tvb_comp[5], tvb_comp[3]);
|
||||
tvb_composite_finalize(tvb_comp[5]);
|
||||
|
||||
/* Test the TVBUFF_COMPOSITE objects. */
|
||||
/* Test the "composite" tvbuff objects. */
|
||||
test(tvb_comp[0], "Composite 0", comp[0], comp_length[0], comp_reported_length[0]);
|
||||
test(tvb_comp[1], "Composite 1", comp[1], comp_length[1], comp_reported_length[1]);
|
||||
test(tvb_comp[2], "Composite 2", comp[2], comp_length[2], comp_reported_length[2]);
|
||||
|
|
|
@ -42,21 +42,29 @@ struct tvbuff {
|
|||
guint flags;
|
||||
struct tvbuff *ds_tvb; /**< data source top-level tvbuff */
|
||||
|
||||
/** We're either a TVBUFF_REAL_DATA or a
|
||||
* TVBUFF_SUBSET that has a backing buffer that
|
||||
* has real_data != NULL, or a TVBUFF_COMPOSITE
|
||||
* which has flattened its data due to a call
|
||||
* to tvb_get_ptr().
|
||||
/** Pointer to the data for this tvbuff.
|
||||
* It might be null, which either means that 1) it's a
|
||||
* zero-length tvbuff or 2) the tvbuff was lazily
|
||||
* constructed, so that we don't allocate a buffer of
|
||||
* backing data and fill it in unless we need that
|
||||
* data, e.g. when tvb_get_ptr() is called.
|
||||
*/
|
||||
const guint8 *real_data;
|
||||
|
||||
/** Length of virtual buffer (and/or real_data). */
|
||||
/** Amount of data that's available from the capture
|
||||
* file. This is the length of virtual buffer (and/or
|
||||
* real_data). It may be less than the reported
|
||||
* length if this is from a packet that was cut short
|
||||
* by the capture process. */
|
||||
guint length;
|
||||
|
||||
/** Reported length. */
|
||||
/** Amount of data that was reported as being in
|
||||
* the packet or other data that this represents.
|
||||
* As indicated above, it may be greater than the
|
||||
* amount of data that's available. */
|
||||
guint reported_length;
|
||||
|
||||
/* Offset from beginning of first TVBUFF_REAL. */
|
||||
/* Offset from beginning of first "real" tvbuff. */
|
||||
gint raw_offset;
|
||||
};
|
||||
|
||||
|
|
|
@ -79,18 +79,18 @@ typedef struct tvbuff tvbuff_t;
|
|||
* @{
|
||||
*/
|
||||
|
||||
/** TVBUFF_REAL_DATA contains a guint8* that points to real data.
|
||||
/** A "real" tvbuff contains a guint8* that points to real data.
|
||||
* The data is allocated and contiguous.
|
||||
*
|
||||
* TVBUFF_SUBSET has a backing tvbuff. The TVBUFF_SUBSET is a "window"
|
||||
* through which the program sees only a portion of the backing tvbuff.
|
||||
* A "subset" tvbuff has a backing tvbuff. It is a "window" through
|
||||
* which the program sees only a portion of the backing tvbuff.
|
||||
*
|
||||
* TVBUFF_COMPOSITE combines multiple tvbuffs sequentially to produce
|
||||
* a larger byte array.
|
||||
* A "composite" tvbuff combines multiple tvbuffs sequentially to
|
||||
* produce a larger byte array.
|
||||
*
|
||||
* tvbuff's of any type can be used as the backing-tvbuff of a
|
||||
* TVBUFF_SUBSET or as the member of a TVBUFF_COMPOSITE.
|
||||
* TVBUFF_COMPOSITEs can have member-tvbuffs of different types.
|
||||
* "subset" tvbuff or as a member of a "composite" tvbuff.
|
||||
* "composite" tvbuffs can have member-tvbuffs of different types.
|
||||
*
|
||||
* Once a tvbuff is create/initialized/finalized, the tvbuff is read-only.
|
||||
* That is, it cannot point to any other data. A new tvbuff must be created if
|
||||
|
@ -133,18 +133,18 @@ WS_DLL_PUBLIC void tvb_free_chain(tvbuff_t *tvb);
|
|||
/** Set a callback function to call when a tvbuff is actually freed
|
||||
* One argument is passed to that callback --- a void* that points
|
||||
* to the real data. Obviously, this only applies to a
|
||||
* TVBUFF_REAL_DATA tvbuff. */
|
||||
* "real" tvbuff. */
|
||||
WS_DLL_PUBLIC void tvb_set_free_cb(tvbuff_t *tvb, const tvbuff_free_cb_t func);
|
||||
|
||||
/** Attach a TVBUFF_REAL_DATA tvbuff to a parent tvbuff. This connection
|
||||
* is used during a tvb_free_chain()... the "child" TVBUFF_REAL_DATA acts
|
||||
* as if it is part of the chain-of-creation of the parent tvbuff, although it
|
||||
/** Attach a "real" tvbuff to a parent tvbuff. This connection is used
|
||||
* during a tvb_free_chain()... the "child" "real" tvbuff acts as if it
|
||||
* is part of the chain-of-creation of the parent tvbuff, although it
|
||||
* isn't. This is useful if you need to take the data from some tvbuff,
|
||||
* run some operation on it, like decryption or decompression, and make a new
|
||||
* tvbuff from it, yet want the new tvbuff to be part of the chain. The reality
|
||||
* is that the new tvbuff *is* part of the "chain of creation", but in a way
|
||||
* that these tvbuff routines are ignorant of. Use this function to make
|
||||
* the tvbuff routines knowledgable of this fact. */
|
||||
* run some operation on it, like decryption or decompression, and make
|
||||
* a new tvbuff from it, yet want the new tvbuff to be part of the chain.
|
||||
* The reality is that the new tvbuff *is* part of the "chain of creation",
|
||||
* but in a way that these tvbuff routines are ignorant of. Use this
|
||||
* function to make the tvbuff routines knowledgable of this fact. */
|
||||
WS_DLL_PUBLIC void tvb_set_child_real_data_tvbuff(tvbuff_t *parent,
|
||||
tvbuff_t *child);
|
||||
|
||||
|
@ -436,8 +436,8 @@ WS_DLL_PUBLIC guint32 tvb_get_bits(tvbuff_t *tvb, const guint bit_offset,
|
|||
/** Returns target for convenience. Does not suffer from possible
|
||||
* expense of tvb_get_ptr(), since this routine is smart enough
|
||||
* to copy data in chunks if the request range actually exists in
|
||||
* different TVBUFF_REAL_DATA tvbuffs. This function assumes that the
|
||||
* target memory is already allocated; it does not allocate or free the
|
||||
* different "real" tvbuffs. This function assumes that the target
|
||||
* memory is already allocated; it does not allocate or free the
|
||||
* target memory. */
|
||||
WS_DLL_PUBLIC void *tvb_memcpy(tvbuff_t *tvb, void *target, const gint offset,
|
||||
size_t length);
|
||||
|
@ -480,7 +480,7 @@ WS_DLL_PUBLIC void *tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb,
|
|||
* guint8* points to read-only data that the tvbuff manages.
|
||||
*
|
||||
* Return a pointer into our buffer if the data asked for via 'offset'/'length'
|
||||
* is contiguous (which might not be the case for TVBUFF_COMPOSITE). If the
|
||||
* is contiguous (which might not be the case for a "composite" tvbuff). If the
|
||||
* data is not contiguous, a tvb_memdup() is called for the entire buffer
|
||||
* and the pointer to the newly-contiguous data is returned. This dynamically-
|
||||
* allocated memory will be freed when the tvbuff is freed, after the
|
||||
|
|
Loading…
Reference in New Issue