Wireshark · Wireshark-dev: [Wireshark-dev] Question on reported length

["Richard Achmatowicz" <richard.achmatowicz@xxxxxxxxxxxxxx>]

Hello

I'm writing a dissector to handle a protocol whose PDUs are such that you need to dissect the entire PDU to find its length.
I've got a version working for the case of transport= UDP and i'm trying to get a version working for transport=TCP.

I've read section 2.7 of README.developer which discusses reassembly / defragmentation for protocols running atop TCP,
and as I have no fixed prefix of my PDUs which allows me to compute the length of the PDU, it appears I need to 

use the method of modifying the pinfo struct to tell wireshark that I am still waiting for fragments of a fragmented PDU.

Before I can ask my real question, a few words.

My understanding is this: when running a protocol on top of TCP two things can happen:

(i) a large PDU can be fragmented by TCP, so that a dissector can be handed a tvb which does not contain a complete PDU
(ii) several small PDUs may end up in the same tvb

There is an example of how to deal with this in README.developer, section 2.7.2, where the PDU consists of an unknown number 

of C strings. The example dissector does two things to solve problems (i) and (ii):
- to solve (i), it adjusts the pinfo structure elements desegment offset=offset and desegment_len=DESEGMENT_ONE

_MORE_SEGMENT
and returns, in order to tell Wireshark that it needs another fragment in order to continue processing ;
- to solve (ii), it operates in a loop, so that if a C string is dissected and there is still more data in the buffer, it will start the search for
another C string which may be present in the remaining part of the buffer.

This example closely mirrors my situation, and I believe I understand how the example works in general.

Now to my question. Instead of using a call to tvb_length() to get the length of the tvb which is passed to the dissector, the example uses
tvb_reported_length(). I have looked for documentation on this and was unable to find any, save for comments in the tvbuff.h file:

/** Set the reported length of a tvbuff to a given value; used for protocols
   whose headers contain an explicit length and where the calling
   dissector's payload may include padding as well as the packet for
   this protocol.
   Also adjusts the data length. */
extern void tvb_set_reported_length(tvbuff_t*, guint);

So:
1. When do I know to use tvb_length() versus tvb_reported_length() in general? Who sets the reported length? Is there a simple example
of when the two lengths will need to be different? If the calling dissector's payload may also include padding why wouldn't it create a new tvb
which does not include the padding to pass to the called dissector?

2. Is there an explanation for why it is used in the context of this simple example? (does the fact that TCP calls the dissector in the example
have anything to do with the fact that tvb_get_reported_length() is used?)
 
Any guidance appreciated

Richard