TreeItem

A specialized node of the tree view in the Packet Details pane. (Reference)

treeitem:add(proto_field [,tvbrange] [,value [,text1 [,text2] ...] ])

• Description

  • Adds a ProtoField, containing the specified packet detail, as a new TreeItem child to the current TreeItem

  Parameters

  • proto_field : ProtoField

    • A previously created ProtoField to parse the tvbrange. If it represents a numeric value (e.g., ProtoField.uint32, ProtoField.float), the value is parsed Big Endian (MSB first).

    tvbrange (optional) : TvbRange

    • The TvbRange buffer that contains the data to be parsed by the proto_field. This is typically based off the TvbRange passed to the dissector. The buffer length can be zero, in which case the value text is set to "<MISSING>". For positive-length buffers, the specified bytes are highlighted in the Packet Bytes pane upon selecting the tree item from the Packet Details pane.

      If this optional field is omitted, then value is required.

    value (optional if tvbrange present) : string, number

    • The desired value, which overrides the actual value text that was set by the proto_field. The value is coerced into a string or number based on the ProtoField type (see table below for coercion results). For example, if proto_field set the TreeItem's text to "Message: foo bar", a value of "hello world" would yield "Message: hello world".

    • ProtoField type	value type	coercion result
      string	string	string
      string	number	string conversion of number (e.g., 765 results in "765")
      number	numeric string (e.g., "45" or "13.2")	number conversion of string; for uint fields, the integer portion of the number (e.g., "1.98" results in integer 1)
      number	non-numeric string (e.g., "blah")	<ERROR>
      bytes	string	ASCII of each character in string
      bytes	number	ASCII of each character in the string conversion of the number (e.g., 123 results in {0x31, 0x32, 0x33})

    text... (optional) : string, number

    • Additional strings (or numbers) to be appended to the value text. If multiple text arguments are provided, they are all concatenated with a space delimiter to form a single string. Any text arguments that are not strings or numbers are ignored (including nil).

      If text1 is a string type, all text arguments (including text1) overwrite the full text of the TreeItem rather than appending to the existing text. So, use nil for text1 to append the remaining arguments to the value text. (By design? A bug turned feature?)

  Returns

  • userdata : The newly created TreeItem child

  Errors

  • The tvbrange buffer length is shorter than expected by proto_field.

  • The value type is unexpected for the given proto_field.

  Example

  •    1 local proto_foo = Proto("foo", "Foo Protocol")
       2 proto_foo.fields.bytes = ProtoField.bytes("foo.bytes", "Byte array")
       3 proto_foo.fields.u16 = ProtoField.uint16("foo.u16", "Unsigned short", base.HEX)
       4 
       5 function proto_foo.dissector(buf, pinfo, tree)
       6         -- ignore packets less than 4 bytes long
       7         if buf:len() < 4 then return end
       8 
       9         -- ##############################################
      10         -- # Assume buf(0,4) == {0x00, 0x01, 0x00, 0x02}        
      11         -- ##############################################
      12         
      13         local t = tree:add( proto_foo, buf() )
      14         
      15         -- Adds a byte array that shows as: "Byte array: 00010002" 
      16         t:add( proto_foo.fields.bytes, buf(0,4) )
      17         
      18         -- Adds a byte array that shows as "Byte array: 313233"
      19         -- (the ASCII char code of each character in "123")
      20         t:add( proto_foo.fields.bytes, buf(0,4), "123" )
      21         
      22         -- Adds a tree item that shows as: "Unsigned short: 0x0001"
      23         t:add( proto_foo.fields.u16, buf(0,2) )
      24         
      25         -- Adds a tree item that shows as: "Unsigned short: 0x0064"
      26         t:add( proto_foo.fields.u16, buf(0,2), 100 )
      27         
      28         -- Adds a tree item that shows as: "Unsigned short: 0x0064 ( big endian )"
      29         t:add( proto_foo.fields.u16, buf(1,2), 100, nil, "(", nil, "big", 999, nil, "endian", nil, ")" )
      30         
      31         -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x0100"
      32         t:add_le( proto_foo.fields.u16, buf(0,2) )
      33 
      34         -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400"
      35         t:add_le( proto_foo.fields.u16, buf(0,2), 100 )
      36         
      37         -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400 ( little endian )"
      38         t:add_le( proto_foo.fields.u16, buf(1,2), 100, nil, "(", nil, "little", 999, nil, "endian", nil, ")" )
      39 end
      40 
      41 udp_table = DissectorTable.get("udp.port")
      42 udp_table:add(7777, proto_foo)
    

treeitem:add(proto [,tvbrange] [,value [,text1 [,text2] ...] ])

• Description

  • Same as treeitem:add(proto_field [,tvbrange] [,value [,text1 [,text2] ...] ]) except:

    • tree text is initially set to Proto's description

    • there is no default value text and thus no colon (must be supplied by value and text arguments)

treeitem:add(tvbrange ,label [,text1 [,text2] ...])

• Description

  • Same as treeitem:add(proto_field [,tvbrange] [,value [,text1 [,text2] ...] ]) except:

    • the tvbrange is not parsed; it is simply associated with the TreeItem, such that selecting the TreeItem in the Packet Details pane causes it to be highlighted in the Packet Bytes pane.

    • there is no default value text and thus no colon (must be supplied by label and text arguments)

    • display filtering cannot be used on this TreeItem (because there is no ProtoField)

    This is useful when you want to add a TreeItem without associating it with a ProtoField.

treeitem:add_le(proto_field [,tvbrange] [,value [,text1 [,text2] ...] ])

• Description

  • Same as treeitem:add(proto_field [,tvbrange] [,value [,text1 [,text2] ...] ]) except the proto_field uses Little Endian (LSB first) to parse numeric fields

treeitem:set_text(text)

• Description

  • Sets the full text (including the label and value text) of the TreeItem

  Parameters

  • text : string

    • The desired text

treeitem:append_text(text)

• Description

  • Appends text to the TreeItem's current text

  Parameters

  • text : string

    • The text to be appended

treeitem:set_expert_flags([group [,severity] ])

• Description

  • Sets the expert flags of the TreeItem

    See treeitem:add_expert_info([group [,severity [,text] ] ]) for information on group and severity

treeitem:add_expert_info([group [,severity [,text] ] ])

• Description

  • Sets the expert flags of the item and adds an Expert Info TreeItem to the packet details.

    Even though all all arguments are optional, it would be more useful to provide them.

  Parameters

  • group (optional) : GroupLevel

    • An expert group level. Defaults to PI_DEBUG.

      • group level	meaning	typical severity
        PI_CHECKSUM	The protocol field has a bad checksum	PI_WARN
        PI_SEQUENCE	The protocol field indicates a sequence problem (e.g. TCP window is zero)	PI_WARN
        PI_RESPONSE_CODE	The protocol field indicates a bad application response code (e.g. HTTP 404)	PI_NOTE
        PI_REQUEST_CODE	The protocol field indicates an application request (e.g. File Handle == xxxx)	PI_CHAT
        PI_UNDECODED	The data is undecoded, the protocol dissection is incomplete or data can't be decoded for other reasons	PI_WARN
        PI_REASSEMBLE	The protocol field indicates a reassembly (e.g. DCE/RPC defragmentation)	PI_CHAT or PI_ERROR
        PI_MALFORMED	The packet data is malformed, the dissector has "given up"	PI_ERROR
        PI_DEBUG	A generic debugging message (shouldn't remain in production code!)	PI_ERROR
        PI_PROTOCOL	The protocol field violates a protocol specification	PI_WARN
        PI_SECURITY	The protocol field indicates a security problem (e.g. unsecure implementation, such as plaintext passwords)	PI_WARN

    severity (optional) : SeverityLevel

    • An expert severity level; changes the background color of the TreeItem and its root node. Defaults to PI_CHAT.

      • severity level	meaning	TreeItem background color
        PI_CHAT	Usual workflow, e.g. TCP connection establishing	light blue
        PI_NOTE	Notable messages, e.g. an application returned a "usual" error code like HTTP 404	cyan
        PI_WARN	Warning, e.g. application returned an "unusual" error code	yellow
        PI_ERROR	Serious problems, e.g. [Malformed Packet]	red

    text (optional) : string

    • The text message to display in the expert info. Defaults to "Expert Info".

treeitem:set_generated()

• Description

  • Marks the TreeItem as a generated field (data inferred but not contained in the packet). The TreeItem's text becomes surrounded by square brackets (e.g., [Field: 1234]).

treeitem:set_hidden() (DEPRECATED)

• Description

  • Marks the TreeItem as hidden so that it is not shown in the Packet Details pane but can still be used for filtering.

    DEPRECATED

    Note that creating hidden fields is actually quite a bad idea from a UI design perspective because the user (someone who did not write nor has ever seen the code) has no way of knowing that hidden fields are there to be filtered on thus defeating the whole purpose of putting them there. A better way might be to add the fields (that might otherwise be hidden) to a subtree where they won't be seen unless the user opens the subtree--but they can be found if the user wants.

treeitem:set_len(len)

• Description

  • Set TreeItem's length inside its associated Tvb, after it has already been created. This only changes the highlighted bytes in the Packet Bytes pane. The TreeItem's value text remains the same.

  Parameters

  • len : number

    • The desired length >= 0. A zero length disables byte highlighting upon selection of the TreeItem. The length is automatically reduced to the Tvb's maximum length if necessary.

  Errors

  • len is negative