From 23f5b1336974850de62a8a10be46b4fbd5869d0b Mon Sep 17 00:00:00 2001 From: Guy Harris Date: Tue, 10 Apr 2018 11:01:11 -0700 Subject: [PATCH] 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 --- doc/README.dissector | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/doc/README.dissector b/doc/README.dissector index 778ef0775f..70a6875d1b 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -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 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_remaining(tvb, offset) + 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 -- 2.34.1