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 TvbRangeis 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, ...)

This function returns more than just the new child TreeItem. The child is the first return value, so that function chaining will still work; but it also returns more information. The second return is the value of the extracted field (i.e., a number, UInt64, Address, etc.). The third return is is the offset where data should be read next. This is useful when the length of the field is not known in advance. The additional return values may be null if the field type is not well supported in the Lua API.

This function can extract a ProtoField of type ftypes.BYTES or ftypes.ABSOLUTE_TIME from a string in the TvbRange in ASCII-based and similar encodings. For example, a ProtoField of ftypes.BYTES can be extracted from a TvbRange containing the ASCII string "a1b2c3d4e5f6", and it will correctly decode the ASCII both in the tree as well as for the second return value, which will be a ByteArray. To do so, you must set the encoding argument of this function to the appropriate string ENC_* value, bitwise-or’d (or added) with the ENC_STR_HEX value and one or more ENC_SEP_XXX values indicating which encodings are allowed. For ftypes.ABSOLUTE_TIME, one of the ENC_ISO_8601_* encodings or ENC_IMF_DATE_TIME must be used, and the second return value is a NSTime. Only single-byte ASCII digit string encodings such as ENC_ASCII and ENC_UTF_8 can be used for this.

For example, assuming the Tvb named “tvb” contains the string "abcdef" (61 62 63 64 65 66 in hex):

     -- this is done earlier in the script
     local myfield = ProtoField.new("Transaction ID", "myproto.trans_id", ftypes.BYTES)
     myproto.fields = { myfield }

     -- this is done inside a dissector, post-dissector, or heuristic function
     -- child will be the created child tree, and value will be the ByteArray "abcdef" or nil on failure
     local child, value = tree:add_packet_field(myfield, tvb:range(0,6), ENC_UTF_8 + ENC_STR_HEX + ENC_SEP_NONE)

Arguments

Returns

The new child TreeItem, the field’s extracted value or nil, and offset or nil.

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 first argument is a ProtoField or a Proto, 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, then it’s the value (as opposed to filling that argument with 'nil', which is invalid for this function). If the first argument is a non-ProtoField and a non-Proto then this argument can be either a TvbRange or a label, and the value is not in use.

Example

    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)

Arguments

Returns

The new child 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 Little Endian value.

This function has a complicated form: 'treeitem:add_le([protofield,] [tvbrange,] value], label)', such that if the first argument is a ProtoField or a Proto, 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, then it’s the value (as opposed to filling that argument with 'nil', which is invalid for this function). If the first argument is a non-ProtoField and a non-Proto then this argument can be either a TvbRange or a label, and the value is not in use.

Arguments

Returns

The new child TreeItem.

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.

Arguments

Returns

The same TreeItem.

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.

Arguments

Returns

The same TreeItem.

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.

Arguments

Returns

The same TreeItem.

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().

Arguments

Returns

The same TreeItem.

Sets the expert flags of the tree item and adds expert info to the packet.

Arguments

Returns

The same TreeItem.

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.

Arguments

Returns

The same TreeItem.

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.

Arguments

Returns

The same TreeItem.

Marks the TreeItem as a hidden field (neither displayed nor used in filters). Deprecated

This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.

Arguments

Returns

The same TreeItem.

Set TreeItem's length inside tvb, after it has already been created.

This used to return nothing, but as of 1.11.3 it returns the same tree item to allow chained calls.

Arguments

Returns

The same TreeItem.

Checks if a ProtoField or Dissector is referenced by a filter/tap/UI.

If this function returns false, it means that the field (or dissector) does not need to be dissected and can be safely skipped. By skipping a field rather than dissecting it, the dissector will usually run faster since Wireshark will not do extra dissection work when it doesn’t need the field.

You can use this in conjunction with the TreeItem.visible attribute. This function will always return true when the TreeItem is visible. When it is not visible and the field is not referenced, you can speed up the dissection by not dissecting the field as it is not needed for display or filtering.

This function takes one parameter that can be a ProtoField or Dissector. The Dissector form is useful when you need to decide whether to call a sub-dissector.

Arguments

Returns

A boolean indicating if the ProtoField/Dissector is referenced

Returns string debug information about the TreeItem.

Mode: Retrieve or assign.

Set/get the TreeItem's display string (string).

For the getter, if the TreeItem has no display string, then nil is returned.

Mode: Retrieve only.

Get the TreeItem's subtree visibility status (boolean).

Mode: Retrieve or assign.

Set/get the TreeItem's generated state (boolean).

Mode: Retrieve or assign.

Set/get TreeItem's hidden state (boolean).

Mode: Retrieve or assign.

Set/get TreeItem's length inside tvb, after it has already been created.