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>

2 files changed, 84 insertions, 36 deletions

diff --git a/epan/reassemble.c b/epan/reassemble.c
index bd785c6ead..745b585ddb 100644
--- a/epan/reassemble.c
+++ b/epan/reassemble.c
@@ -1960,11 +1960,11 @@ fragment_add_seq(reassembly_table *table, tvbuff_t *tvb, const int offset,
  * This function assumes frag_number being a block sequence number.
  * The bsn for the first block is 0.
  *
- * If "no_frag_number" is TRUE, it uses the next expected fragment number
+ * If REASSEMBLE_FLAGS_NO_FRAG_NUMBER, it uses the next expected fragment number
  * as the fragment number if there is a reassembly in progress, otherwise
  * it uses 0.
  *
- * If "no_frag_number" is FALSE, it uses the "frag_number" argument as
+ * If not REASSEMBLE_FLAGS_NO_FRAG_NUMBER, it uses the "frag_number" argument as
  * the fragment number.
  *
  * If this is the first fragment seen for this datagram, a new
@@ -2077,6 +2077,8 @@ fragment_add_seq_next(reassembly_table *table, tvbuff_t *tvb, const int offset,
 		      const void *data, const guint32 frag_data_len,
 		      const gboolean more_frags)
 {
+	/* Use a dummy frag_number (0), it is ignored since
+	 * REASSEMBLE_FLAGS_NO_FRAG_NUMBER is set. */
 	return fragment_add_seq_check_work(table, tvb, offset, pinfo, id, data,
 					   0, frag_data_len, more_frags,
 					   REASSEMBLE_FLAGS_NO_FRAG_NUMBER);
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);