[Wireshark] 11.7. Add information to the parse tree

11.7.1. TreeItem

>s represents the information displayed on the Packet Details pane. On Tshark, there is the Packet Details View. A TreeItem represents a node in the tree, and it can also be used as a subtree containing a list of children. Children of a subtree can have zero or more sister nodes, which are other children of the subtree.
,treeitem>

In the process of parsing, heuristic parsing, and post-parsing, A root (root)

> is passed to the parser as the third argument to the function callback (e.g., myproto.dissector(tvbuf,pktinfo,root);
,treeitem>

To improve performance, in some cases items are not actually added to the tree. For example, when the packet is not currently displayed/retrieved in the Visible Window pane of Wireshark, or the -V switch is not enabled in Tshark. However, the “Add” TreeItem method can still be called and return a TreeItem object – but the info is not actually added to the tree;

Therefore, you usually don’t need to care if there is a real tree, but if you need to know for some reason, you can use the TreeItem.visible property getter to retrieve the state;

Treeitem :add_packet_field(protofield, [tvbrange], encoding, [label])

Adds a new subtree of a given ProtoField object to the TreeItem, returning a new subtreeitem;

Unlike TreeItem:add() and TreeItem:add_le(), the ProtoField argument in this method is non-optional, that is, required, and cannot be a Proto object. Instead, the first argument to the method can only use a ProtoField to determine the extracted field type from the incoming TvbRange, highlight the relevant Bytes (if there is a GUI) in the Packet Bytes Pane,, and so on;

If TvbRange is not specified, no bytes will be highlighted and the value of the field will not be determined. In this case, a ProtoField must be defined/created as a type with no length, otherwise an error will occur. However, the Encoding parameter must still be specified for backward compatibility reasons;

Instead of TreeItem:add() and TreeItem:add_le(), this method can be set to ENC_BIG_ENDIAN or enc_little_endia.encoding, To decide whether to perform big-Endian or little-Endian decoding;

The method is signed as follows:

     tree_item:add_packet_field(proto_field [,tvbrange], encoding, ...)
Copy the code

In version 1.11.3 of Wireshark, this method was changed to return more than just a child TreeItem.

A child TreeItem is the first value returned by this method, and it will also return the extracted field value (that is, a number, UInt64, Address, and so on). If it can’t extract a value from TvbRange, it still returns a child TreeItem, and the second returns nil;

Another new feature of this method in Version 1.11.3 of Wireshark is the ability to extract native number ProtoFields from TvbRange’s string encodings for ASCII and similar string encodings. For example, a ProtoField of type ftypes.uint32 can be extracted from a TvbRange containing the ASCII string “123 “, which will correctly decode ASCII to the number 123, either in the tree or in the second return value of this function. To do this, you must set the encoding parameter of this function to the appropriate ENC_ * value of the string and compare it with the ENC_STRING value (see init.lua). ENC_STRING is guaranteed to be a unique bit flag, so it can also be added directly rather than bitwise-or’ed. Only single-byte ASCII numeric string encoding types can be used for this, such as ENC_ASCII and ENC_UTF_8;

For example, a TVB called “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)
Copy the code

parameter
- protofield
  
  The ProtoField field object to add to the tree;
- Tvbrange (optional)
  
  The number of TvbRange bytes in the packet covered by/represented by the tree item;
- encoding
  
  The encoding mode of the field in TvbRange;
- Label (optional)
  
  One or more strings to append to the TreeItem being created;

The return value
- A new child TreeItem, whose extracted value is nil if there is none, and an offset, nil if there is none;

Treeitem :add([protofield], [tvBrange], [value], [label])

Add a new child to the TreeItem, returning a new TreeItem;

If a Protofield represents a numeric value (int, uint, or float), it is treated as a big-endian ordinal (network order) value;

This method has a complicated form. ‘TreeItem :add([Protofield,] [tvBrange,] value], label)’, so that if the first argument is protofield or Proto, the second argument is tvBrange, and the third argument is given, So the third argument is value; But if the second argument is not a TvbRange, then it is value (instead of filling the second argument with ‘nil’, which is invalid for this method). If the first argument is a non-protofield and a non-proto, then this argument can be either TvbRange or a label, and value is not used;

11.7.2. Sample

    local proto_foo = Proto("foo"."Foo Protocol")
    proto_foo.fields.bytes = ProtoField.bytes("foo.bytes"."Byte array")
    proto_foo.fields.u16 = ProtoField.uint16("foo.u16"."Unsigned short", base.HEX)

    function proto_foo.dissector(buf, pinfo, tree)
            -- ignore packets less than 4 bytes long
            if buf:len()"4 then return end

            - # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
            -- # Assume buf(0,4) == {0x00, 0x01, 0x00, 0x02}
            - # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

            local t = tree:add( proto_foo, buf() )

            -- Adds a byte array that shows as: "Byte array: 00010002"
            t:add( proto_foo.fields.bytes, buf(0.4))-- Adds a byte array that shows as "Byte array: 313233"
            -- (the ASCII char code of each character in "123")
            t:add( proto_foo.fields.bytes, buf(0.4), "123" )

            -- Adds a tree item that shows as: "Unsigned short: 0x0001"
            t:add( proto_foo.fields.u16, buf(0.2))-- Adds a tree item that shows as: "Unsigned short: 0x0064"
            t:add( proto_foo.fields.u16, buf(0.2), 100 )

            -- Adds a tree item that shows as: "Unsigned short: 0x0064 ( big endian )"
            t:add( proto_foo.fields.u16, buf(1.2), 100.nil."(".nil."big".999.nil."endian".nil.")" )

            -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x0100"
            t:add_le( proto_foo.fields.u16, buf(0.2))-- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400"
            t:add_le( proto_foo.fields.u16, buf(0.2), 100 )

            -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400 ( little endian )"
            t:add_le( proto_foo.fields.u16, buf(1.2), 100.nil."(".nil."little".999.nil."endian".nil.")" )
    end

    udp_table = DissectorTable.get("udp.port")
    udp_table:add(7777, proto_foo)
Copy the code

parameter
- Protofield (optional)
  
  A ProtoField or a Proto protocol object to add to the tree;
- Tvbrange (optional)
  
  The number of TvbRange bytes in the packet covered by/represented by the tree item;
- Value (Optional)
  
  Field value instead of field value in ProtoField/Proto;
- Label (optional)
  
  One or more strings for tree item labels instead of ProtoField/Proto labels;

The return value
- A new child TreeItem;

Treeitem :add_le([protofield], [tvbrange], [value], [label])

Add a new child to the TreeItem, returning a new TreeItem;

If a Protofield represents a numeric value (int, uint, or float), it is treated as a small-endian value;

parameter
- Protofield (optional)
  
  A ProtoField or a Proto protocol object to add to the tree;
- Tvbrange (optional)
  
  The number of TvbRange bytes in the packet covered by/represented by the tree item;
- Value (Optional)
  
  Field value, replacing the field value in ProtoField/Proto;
- Label (optional)
  
  One or more strings for tree item labels instead of ProtoField/Proto labels;

The return value
- A new child TreeItem;

11.7.2.2. Treeitem: set_text (text)

Set the text of the label;

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- text
  
  The text to use;

The return value
- An identical tree item;

11.7.2.3. Treeitem: append_text (text)

Add text to the tag;

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- text
  
  Text to add;

The return value
- An identical tree item;

11.7.2.4. Treeitem: prepend_text (text)

Add text to the front of the label.

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- text
  
  Text to add;

The return value
- An identical tree item;

11.7.2.5. Treeitem: add_expert_info ([group], [severity], [text])

Set the expert mark of the project, and add the expert information to the packet;

This function does not create a true filterable expert information for a protocol. Instead, you should use treeitem.add_proto_expert_info () for this purpose;

Ps: This function is provided for backward compatibility only and should not be used in new Lua code. It may be removed in the future. You should only useTreeItem.add_proto_expert_info() ；

parameter
- Group (optional)
  
  The value can be PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG.
- Severity (optional)
  
  These can be: PI_CHAT, PI_NOTE, PI_WARN, or PI_ERROR.
- Text (optional)
  
  Text for expert information to be displayed;

The return value
- An identical tree item;

11.7.2.6. Treeitem: add_proto_expert_info (expert, [text])

Set the expert mark of the tree item, and add the expert information to the packet;

parameter
- expert
  
  ProtoExpert objects that need to be added to the tree;
- Text (optional)
  
  Text to display expert information (default registration text);

The return value
- An identical tree item;

11.7.2.7. Treeitem: add_tvb_expert_info (expert, TVB, [text])

Set the expert flag of the tree item and add bytes related to Tvb or TvbRange in the packet;

parameter
- expert
  
  ProtoExpert objects that need to be added to the tree;
- tvb
  
  Tvb or TvbRange object bytes associated with expert information;
- Text (optional)
  
  Text to display expert information (default registration text);

The return value
- An identical tree item;

11.7.2.8. Treeitem: set_generated ([bool])

Tag the TreeItem as a generated field (with data inferred but not included in the packet);

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- bool (optional)
  
  A Lua Boolean that marks the TreeItem as a generated field if true, and clears it otherwise (default true)

The return value
- An identical tree item;

11.7.2.9. Treeitem: set_hidden ([bool])

Mark the TreeItem as a hidden field (neither displayed nor used in the filter); Have been abandoned

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- bool (optional)
  
  A Lua Boolean that marks the TreeItem as a generated field if true, and clears it otherwise (default true)

The return value
- An identical tree item;

11.7.2.10. Treeitem: set_len (len)

After the TreeItem has been created, set its length inside the TVB.

Previously, this method did not return anything, but since version 1.11.3, it returns the same tree item to allow chained calls;

parameter
- len
  
  Length to be used;

The return value
- An identical tree item;

11.7.2.11. Treeitem: referenced (protofield)

Check whether a ProtoField or Dissector is referenced by a filter /Tap/UI;

If the method returns False, this means that the field (or Dissector) does not need to be resolved and can be safely skipped. By skipping a field rather than parsing it, the parser usually runs faster, because Wireshark does no extra parsing when the field is not needed;

You can use this in combination with the TreeItem.visible property. This method will always return TRUE when the TreeItem is visible. When it is not visible and the field is not referenced, you can speed up parsing by not parsing the field because it will not be needed for display or filtering;

This method requires a single parameter, which can be a ProtoField or Dissector;

The Dissector form is useful when you need to decide whether to call a child Dissector.

parameter
- protofield
  
  Protofields or dissectors that need to be checked for reference;

The return value
- Boolean value indicating whether the ProtoField/Dissector is referenced or not;

11.7.2.12. Treeitem: __tostring ()

Returns a TreeItem debug string;

11.7.2.13. Treeitem. Text

Mode: only for retrieval or assignment (Mode: Retrieve or assign);

Sets or gets the display string (string) for the TreeItem;

When used as a getter, returns nil if the TreeItem does not display a string;

11.7.2.14. Treeitem. Visible

Mode: for retrieval only (Mode: Retrieve only)

Gets the state of the subtree of the TreeItem (Boolean);

11.7.2.15. Treeitem. Generated

Mode: only for retrieval or assignment (Mode: Retrieve or assign);

Sets or gets the build state of this TreeItem (Boolean);

11.7.2.16. Treeitem. Hidden

Mode: only for retrieval or assignment (Mode: Retrieve or assign);

Sets/Gets the hidden state of the TreeItem (Boolean).

11.7.2.17. Treeitem. Len

Mode: only for retrieval or assignment (Mode: Retrieve or assign);

Sets/gets the length of the TreeItem within TVB after the TreeItem is created and after the TreeItem is created.

[Wireshark] 11.7. Add information to the parse tree

11.7.1. TreeItem

Treeitem :add_packet_field(protofield, [tvbrange], encoding, [label])

Treeitem :add([protofield], [tvBrange], [value], [label])

11.7.2. Sample

Treeitem :add_le([protofield], [tvbrange], [value], [label])

11.7.2.2. Treeitem: set_text (text)

11.7.2.3. Treeitem: append_text (text)

11.7.2.4. Treeitem: prepend_text (text)

11.7.2.5. Treeitem: add_expert_info ([group], [severity], [text])

11.7.2.6. Treeitem: add_proto_expert_info (expert, [text])

11.7.2.7. Treeitem: add_tvb_expert_info (expert, TVB, [text])

11.7.2.8. Treeitem: set_generated ([bool])

11.7.2.9. Treeitem: set_hidden ([bool])

11.7.2.10. Treeitem: set_len (len)

11.7.2.11. Treeitem: referenced (protofield)

11.7.2.12. Treeitem: __tostring ()

11.7.2.13. Treeitem. Text

11.7.2.14. Treeitem. Visible

11.7.2.15. Treeitem. Generated

11.7.2.16. Treeitem. Hidden

11.7.2.17. Treeitem. Len

Related Posts

Copycat: Quick access to the full palette without logging in

SETUP AND CONFIGURATION OF FREERADIUS + MYSQL ON UBUNTU 14.04 64BIT

System Architecture Design Notes (88) — Authentication and access control