osmith
/
wireshark
forked from osmocom/wireshark
1
0
Fork 0
Code Pull Requests Releases Wiki Activity

Improve the documentation of tvb_new_subset_ routines. 

First mention tvbuff_new_subset_remaining(), as that's good enough for
most uses.

Then mention tvb_new_subset_length(), which is what most of the
remaining cases should use; we weren't even documenting it.

Then mention tvb_new_subset_length_caplen(); we want that to be used
only when *absolutely* necessary.

Change-Id: I57a6c202d4a68b001ddca8bd4c7e1d271eb52ef9
Reviewed-on: https://code.wireshark.org/review/26864
Reviewed-by: Guy Harris <guy@alum.mit.edu>
This commit is contained in:
Guy Harris 2018-04-10 11:01:11 -07:00
parent b3c51deb24
commit 23f5b13369
1 changed files with 36 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/README.dissector
View File

@ -2301,13 +2301,45 @@ is expected to create a new tvbuff of type TVBUFF_SUBSET which
contains the payload portion of the protocol (that is, the bytes
that are relevant to the next dissector).
The syntax for creating a new TVBUFF_SUBSET is:
To create a new TVBUFF_SUBSET that begins at a specified offset in a
parent tvbuff, and runs to the end of the parent tvbuff, the routine
tvbuff_new_subset_remaining() is used:
next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length)
next_tvb = tvb_new_subset_remaining(tvb, offset);
or, in the common case where it should just run to the end of the packet,
Where:
tvb is the tvbuff that the dissector has been working on. It
can be a tvbuff of any type.
next_tvb = tvb_new_subset_remaining(tvb, offset)
next_tvb is the new TVBUFF_SUBSET.
offset is the byte offset of 'tvb' at which the new tvbuff
should start. The first byte is the 0th byte.
To create a new TVBUFF_SUBSET that begins at a specified offset in a
parent tvbuff, with a specified number of bytes in the payload, the
routine tvbuff_new_subset_length() is used:
next_tvb = tvb_new_subset_length(tvb, offset, reported_length);
Where:
tvb is the tvbuff that the dissector has been working on. It
can be a tvbuff of any type.
next_tvb is the new TVBUFF_SUBSET.
offset is the byte offset of 'tvb' at which the new tvbuff
should start. The first byte is the 0th byte.
reported_length is the number of bytes that the current protocol
says should be in the payload.
In the few cases where the number of bytes available in the new subset
must be explicitly specified, rather than being calculated based on the
number of bytes in the payload, the routine tvb_new_subset_length_caplen()
is used:
next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length);
Where:
tvb is the tvbuff that the dissector has been working on. It