diff options
author | Peter Wu <peter@lekensteyn.nl> | 2016-02-22 00:54:50 +0100 |
---|---|---|
committer | Anders Broman <a.broman58@gmail.com> | 2016-02-24 06:18:47 +0000 |
commit | c2f85b6925365365926d3654e01dc53a95c80d37 (patch) | |
tree | 6f00d862039e6210d6703de3f4785f8df503f840 /epan/reassemble.h | |
parent | 9ff932bf5ea554f9e94ee1364284aff9eb3fd619 (diff) | |
download | wireshark-c2f85b6925365365926d3654e01dc53a95c80d37.tar.gz |
Extend reassembly documentation
Documentation changes only (comments and docbook).
Update WSDG with the fragment_add_seq_check API that was introduced in
Wireshark 1.10.
Fix typos and clarify the many functions we have for adding reassembling
fragments.
Change-Id: I38715a8f58e9cf1fe3e34ee4b1a4ae339630282b
Reviewed-on: https://code.wireshark.org/review/14066
Petri-Dish: Peter Wu <peter@lekensteyn.nl>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Anders Broman <a.broman58@gmail.com>
Diffstat (limited to 'epan/reassemble.h')
-rw-r--r-- | epan/reassemble.h | 114 |
1 files changed, 80 insertions, 34 deletions
diff --git a/epan/reassemble.h b/epan/reassemble.h index f2980573dc..ab7b576358 100644 --- a/epan/reassemble.h +++ b/epan/reassemble.h @@ -1,5 +1,5 @@ /* reassemble.h - * Declarations of outines for {fragment,segment} reassembly + * Declarations of routines for {fragment,segment} reassembly * * Wireshark - Network traffic analyzer * By Gerald Combs <gerald@wireshark.org> @@ -77,10 +77,12 @@ typedef struct _fragment_item { * provided fragment number of the first fragment does * not start with 0 * XXX - does this apply only to reassembly heads? */ - guint32 datalen; /**< Only valid in first item of list and when - * flags&FD_DATALEN_SET is set; - * number of bytes or (if flags&FD_BLOCKSEQUENCE set) - * segments in the datagram */ + guint32 datalen; /**< When flags&FD_BLOCKSEQUENCE is set, the + index of the last block (segments in + datagram + 1); otherwise the number of + bytes of the full datagram. Only valid in + the first item of the fragments list when + flags&FD_DATALEN is set.*/ guint32 reassembled_in; /**< frame where this PDU was reassembled, only valid in the first item of the list and when FD_DEFRAGMENTED is set*/ @@ -119,11 +121,20 @@ typedef struct _fragment_item { * in the tvb, and if not, do something a bit odd. */ #define REASSEMBLE_FLAGS_CHECK_DATA_PRESENT 0x0004 -/* a function for creating temporary hash keys */ +/* + * Generates a fragment identifier based on the given parameters. "data" is an + * opaque type whose interpretation is up to the caller of fragment_add* + * functions and the fragment key function (possibly NULL if you do not care). + * + * Keys returned by this function are only used within this packet scope. + */ typedef gpointer (*fragment_temporary_key)(const packet_info *pinfo, const guint32 id, const void *data); -/* a function for creating persistent hash keys */ +/* + * Like fragment_temporary_key, but used for identifying reassembled fragments + * which may persist through multiple packets. + */ typedef gpointer (*fragment_persistent_key)(const packet_info *pinfo, const guint32 id, const void *data); @@ -181,14 +192,27 @@ reassembly_table_destroy(reassembly_table *table); * The list of fragments for a specific datagram is kept sorted for * easier handling. * + * Datagrams (messages) are identified by a key generated by + * fragment_temporary_key or fragment_persistent_key, based on the "pinfo", "id" + * and "data" pairs. (This is the sole purpose of "data".) + * + * Fragments are identified by "frag_offset". + * * Returns a pointer to the head of the fragment data list if we have all the - * fragments, NULL otherwise. + * fragments, NULL otherwise. Note that the reassembled fragments list may have + * a non-zero fragment offset, the only guarantee is that no gaps exist within + * the list. */ WS_DLL_PUBLIC fragment_head * fragment_add(reassembly_table *table, tvbuff_t *tvb, const int offset, const packet_info *pinfo, const guint32 id, const void *data, const guint32 frag_offset, const guint32 frag_data_len, const gboolean more_frags); +/* + * Like fragment_add, except that the fragment may be added to multiple + * reassembly tables. This is needed when multiple protocol layers try + * to add the same packet to the reassembly table. + */ WS_DLL_PUBLIC fragment_head * fragment_add_multiple_ok(reassembly_table *table, tvbuff_t *tvb, const int offset, const packet_info *pinfo, @@ -198,13 +222,18 @@ fragment_add_multiple_ok(reassembly_table *table, tvbuff_t *tvb, const gboolean more_frags); /* - * This routine extends fragment_add to use a "reassembled_table" - * included in the reassembly table. + * Like fragment_add, but maintains a table for completed reassemblies. + * + * If the packet was seen before, return the head of the fully reassembled + * fragments list (NULL if there was none). * - * If, after processing this fragment, we have all the fragments, they - * remove that from the fragment hash table if necessary and add it - * to the table of reassembled fragments, and return a pointer to the - * head of the fragment list. + * Otherwise (if reassembly was not possible before), try to to add the new + * fragment to the fragments table. If reassembly is now possible, remove all + * (reassembled) fragments from the fragments table and store it as a completed + * reassembly. The head of this reassembled fragments list is returned. + * + * Otherwise (if reassembly is still not possible after adding this fragment), + * return NULL. */ WS_DLL_PUBLIC fragment_head * fragment_add_check(reassembly_table *table, tvbuff_t *tvb, const int offset, @@ -212,22 +241,19 @@ fragment_add_check(reassembly_table *table, tvbuff_t *tvb, const int offset, const void *data, const guint32 frag_offset, const guint32 frag_data_len, const gboolean more_frags); -/* same as fragment_add() but this one assumes frag_number is a block - sequence number. note that frag_number is 0 for the first fragment. */ - /* - * These functions add a new fragment to the fragment hash table, - * assuming that frag_number is a block sequence number (starting from zero for - * the first fragment of each datagram). + * Like fragment_add, but fragments have a block sequence number starting from + * zero (for the first fragment of each datagram). This differs from + * fragment_add for which the fragment may start at any offset. * * If this is the first fragment seen for this datagram, a new * "fragment_head" structure is allocated to refer to the reassembled * packet, and: * * if "more_frags" is false, and either we have no sequence numbers, or - * are using the 802.11 hack, it is assumed that this is the only fragment - * in the datagram. The structure is not added to the hash - * table, and not given any fragments to refer to, but is just returned. + * are using the 802.11 hack (via fragment_add_seq_802_11), it is assumed that + * this is the only fragment in the datagram. The structure is not added to the + * hash table, and not given any fragments to refer to, but is just returned. * * In this latter case reassembly wasn't done (since there was only one * fragment in the packet); dissectors can check the 'next' pointer on the @@ -247,12 +273,8 @@ fragment_add_seq(reassembly_table *table, tvbuff_t *tvb, const int offset, const gboolean more_frags, const guint32 flags); /* - * These routines extend fragment_add_seq to use the "reassembled_table". - * - * If, after processing this fragment, we have all the fragments, they - * remove that from the fragment hash table if necessary and add it - * to the table of reassembled fragments, and return a pointer to the - * head of the fragment list. + * Like fragment_add_seq, but maintains a table for completed reassemblies + * just like fragment_add_check. */ WS_DLL_PUBLIC fragment_head * fragment_add_seq_check(reassembly_table *table, tvbuff_t *tvb, const int offset, @@ -261,6 +283,11 @@ fragment_add_seq_check(reassembly_table *table, tvbuff_t *tvb, const int offset, const guint32 frag_number, const guint32 frag_data_len, const gboolean more_frags); +/* + * Like fragment_add_seq_check, but immediately returns a fragment list for a + * new fragment. This is a workaround specific for the 802.11 dissector, do not + * use it elsewhere. + */ WS_DLL_PUBLIC fragment_head * fragment_add_seq_802_11(reassembly_table *table, tvbuff_t *tvb, const int offset, const packet_info *pinfo, @@ -268,17 +295,31 @@ fragment_add_seq_802_11(reassembly_table *table, tvbuff_t *tvb, const guint32 frag_number, const guint32 frag_data_len, const gboolean more_frags); +/* + * Like fragment_add_seq_check, but without explicit fragment number. Fragments + * are simply appended until no "more_frags" is false. + */ WS_DLL_PUBLIC fragment_head * fragment_add_seq_next(reassembly_table *table, tvbuff_t *tvb, const int offset, const packet_info *pinfo, const guint32 id, const void *data, const guint32 frag_data_len, const gboolean more_frags); +/* + * Start a reassembly, expecting "tot_len" as the number of given fragments (not + * the number of bytes). Data can be added later using fragment_add_seq_check. + */ WS_DLL_PUBLIC void fragment_start_seq_check(reassembly_table *table, const packet_info *pinfo, const guint32 id, const void *data, const guint32 tot_len); +/* + * Mark end of reassembly and returns the reassembled fragment (if completed). + * Use it when fragments were added with "more_flags" set while you discovered + * that no more fragments have to be added. + * XXX rename to fragment_finish as it works also for fragment_add? + */ WS_DLL_PUBLIC fragment_head * fragment_end_seq_next(reassembly_table *table, const packet_info *pinfo, const guint32 id, const void *data); @@ -290,18 +331,23 @@ WS_DLL_PUBLIC void fragment_add_seq_offset(reassembly_table *table, const packet_info *pinfo, const guint32 id, const void *data, const guint32 fragment_offset); -/* to specify how much to reassemble, for fragmentation where last fragment can not be - * identified by flags or such. - * note that for FD_BLOCKSEQUENCE tot_len is the index for the tail fragment. +/* + * Sets the expected index for the last block (for fragment_add_seq functions) + * or the expected number of bytes (for fragment_add functions). A reassembly + * must already have started. + * + * Note that for FD_BLOCKSEQUENCE tot_len is the index for the tail fragment. * i.e. since the block numbers start at 0, if we specify tot_len==2, that * actually means we want to defragment 3 blocks, block 0, 1 and 2. - * */ WS_DLL_PUBLIC void fragment_set_tot_len(reassembly_table *table, const packet_info *pinfo, const guint32 id, const void *data, const guint32 tot_len); -/* to resad whatever totlen previously set */ +/* + * Return the expected index for the last block (for fragment_add_seq functions) + * or the expected number of bytes (for fragment_add functions). + */ WS_DLL_PUBLIC guint32 fragment_get_tot_len(reassembly_table *table, const packet_info *pinfo, const guint32 id, const void *data); |