TreeItems represent information in the packet-details pane. A root TreeItem is passed to dissectors as the third argument.
Adds a new child tree for the given ProtoField object to this tree item, returning the new child TreeItem.
Unlike TreeItem:add() and TreeItem:add_le(), the ProtoField argument is not optional, and cannot be a Proto object. Instead, this function always uses the ProtoField to determine the type of field to extract from the passed-in TvbRange, highlighting the relevant bytes in the Packet Bytes pane of the GUI (if there is a GUI), etc. If no TvbRange is given, no bytes are highlighted and the field's value cannot be determined; the ProtoField must have been defined/created not to have a length in such a case, or an error will occur. For backwards-compatibility reasons the encoding argument, however, must still be given.
Unlike TreeItem:add() and TreeItem:add_le(), this function performs both big-endian and little-endian decoding, by setting the encoding argument to be ENC_BIG_ENDIAN or ENC_LITTLE_ENDIAN.
The signature of this function:
tree_item:add_packet_field(proto_field [,tvbrange], encoding, ...)
In Wireshark version 1.11.3, this function was changed to return more than just the new child TreeItem. The child is the first return value, so that function chaining will still work as before; but it now also returns the value of the extracted field (i.e., a number, UInt64, Address, etc.). If the value could not be extracted from the TvbRange, the child TreeItem is still returned, but the second returned value is nil.
Another new feature added to this function in Wireshark version 1.11.3 is the ability to extract native number ProtoFields from string encoding in the TvbRange, for ASCII-based and similar string encodings. For example, a ProtoField of as ftypes.UINT32 type can be extracted from a TvbRange containing the ASCII string "123", and it will correctly decode the ASCII to the number 123, both in the tree as well as for the second return value of this function. To do so, you must set the encoding argument of this function to the appropriate string ENC_* value, bitwise-or'd with the ENC_STRING value (see init.lua). ENC_STRING is guaranteed to be a unique bit flag, and thus it can added instead of bitwise-or'ed as well. Only single-byte ASCII digit string encoding types can be used for this, such as ENC_ASCII and ENC_UTF_8.
For example, assuming the Tvb named "tvb" contains the string "123":
-- this is done earlier in the script local myfield = ProtoField.new("Transaction ID", "myproto.trans_id", ftypes.UINT16) -- this is done inside a dissector, post-dissector, or heuristic function -- child will be the created child tree, and value will be the number 123 or nil on failure local child, value = tree:add_packet_field(myfield, tvb:range(0,3), ENC_UTF_8 + ENC_STRING)
The ProtoField field object to add to the tree.
The TvbRange of bytes in the packet this tree item covers/represents.
The field's encoding in the TvbRange.
One or more strings to append to the created TreeItem.
Adds a child item to this tree item, returning the new child TreeItem.
If the ProtoField represents a numeric value (int, uint or float), then it's treated as a Big Endian (network order) value.
This function has a complicated form: 'treeitem:add(protofield, [tvbrange,] [[value], label]])', such that if the second argument is a TvbRange, and a third argument is given, it's a value; but if the second argument is a non-TvbRange type, then it is the value (as opposed to filling that argument with 'nil', which is invalid for this function).
The ProtoField field or Proto protocol object to add to the tree.
The TvbRange of bytes in the packet this tree item covers/represents.
The field's value, instead of the ProtoField/Proto one.
One or more strings to use for the tree item label, instead of the ProtoField/Proto one.
Adds a child item to this tree item, returning the new child TreeItem.
If the ProtoField represents a numeric value (int, uint or float), then it's treated as a Little Endian value.
This function has a complicated form: 'treeitem:add_le(protofield, [tvbrange,] [[value], label]])', such that if the second argument is a TvbRange, and a third argument is given, it's a value; but if the second argument is a non-TvbRange type, then it is the value (as opposed to filling that argument with 'nil', which is invalid for this function).
The ProtoField field or Proto protocol object to add to the tree.
The TvbRange of bytes in the packet this tree item covers/represents.
The field's value, instead of the ProtoField/Proto one.
One or more strings to use for the tree item label, instead of the ProtoField/Proto one.
Sets the text of the label.
This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.
Appends text to the label.
This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.
Prepends text to the label.
This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.
Sets the expert flags of the item and adds expert info to the packet.
This function does not create a truly filterable expert info for a protocol. Instead you should use TreeItem.add_proto_expert_info().
![]() | Note |
---|---|
This function is provided for backwards compatibility only, and should not be used in new Lua code. It may be removed in the future. You should only use TreeItem.add_proto_expert_info(). |
One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG.
One of PI_CHAT, PI_NOTE, PI_WARN, or PI_ERROR.
The text for the expert info display.
Sets the expert flags of the tree item and adds expert info to the packet.
Since: 1.11.3
The ProtoExpert object to add to the tree.
Text for the expert info display (default is to use the registered text).
Sets the expert flags of the tree item and adds expert info to the packet associated with the Tvb or TvbRange bytes in the packet.
Since: 1.11.3
The ProtoExpert object to add to the tree.
The Tvb or TvbRange object bytes to associate the expert info with.
Text for the expert info display (default is to use the registered text).
Marks the TreeItem as a generated field (with data inferred but not contained in the packet).
This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.
This function should not be used, and is provided for backwards-compatibility only.