11.6. Obtaining dissection data

11.6.1. Field

A Field extractor to to obtain field values. A Field object can only be created outside of the callback functions of dissectors, post-dissectors, heuristic-dissectors, and taps.

Once created, it is used inside the callback functions, to generate a FieldInfo object.

11.6.1.1. Field.new(fieldname)

Create a Field extractor.

11.6.1.1.1. Arguments
fieldname

The filter name of the field (e.g. ip.addr)

11.6.1.1.2. Returns

The field extractor

11.6.1.1.3. Errors
  • A Field extractor must be defined before Taps or Dissectors get called

11.6.1.2. Field.list()

Gets a Lua array table of all registered field filter names.

NOTE: this is an expensive operation, and should only be used for troubleshooting.

Since: 1.11.3

11.6.1.2.1. Returns

The array table of field filter names

11.6.1.3. field:__call()

Obtain all values (see FieldInfo) for this field.

11.6.1.3.1. Returns

All the values of this field

11.6.1.3.2. Errors
  • Fields cannot be used outside dissectors or taps

11.6.1.4. field:__tostring()

Obtain a string with the field name.

11.6.2. FieldInfo

An extracted Field from dissected packet data. A FieldInfo object can only be used within the callback functions of dissectors, post-dissectors, heuristic-dissectors, and taps.

A FieldInfo can be called on either existing Wireshark fields by using either Field.new() or Field() before-hand, or it can be called on new fields created by Lua from a ProtoField.

11.6.2.1. fieldinfo:__len()

Obtain the Length of the field

11.6.2.2. fieldinfo:__unm()

Obtain the Offset of the field

11.6.2.3. fieldinfo:__call()

Obtain the Value of the field.

Previous to 1.11.4, this function retrieved the value for most field types, but for ftypes.UINT_BYTES it retrieved the ByteArray of the field's entire TvbRange. In other words, it returned a ByteArray that included the leading length byte(s), instead of just the value bytes. That was a bug, and has been changed in 1.11.4. Furthermore, it retrieved an ftypes.GUID as a ByteArray, which is also incorrect.

If you wish to still get a ByteArray of the TvbRange, use FieldInfo:get_range() to get the TvbRange, and then use Tvb:bytes() to convert it to a ByteArray.

11.6.2.4. fieldinfo:__tostring()

The string representation of the field.

11.6.2.5. fieldinfo:__eq()

Checks whether lhs is within rhs.

11.6.2.5.1. Errors
  • Data source must be the same for both fields

11.6.2.6. fieldinfo:__le()

Checks whether the end byte of lhs is before the end of rhs.

11.6.2.6.1. Errors
  • Data source must be the same for both fields

11.6.2.7. fieldinfo:__lt()

Checks whether the end byte of rhs is before the beginning of rhs.

11.6.2.7.1. Errors
  • Data source must be the same for both fields

11.6.2.8. fieldinfo.len

Mode: Retrieve only.

The length of this field.

11.6.2.9. fieldinfo.offset

Mode: Retrieve only.

The offset of this field.

11.6.2.10. fieldinfo.value

Mode: Retrieve only.

The value of this field.

11.6.2.11. fieldinfo.label

Mode: Retrieve only.

The string representing this field

11.6.2.12. fieldinfo.display

Mode: Retrieve only.

The string display of this field as seen in GUI

11.6.2.13. fieldinfo.range

Mode: Retrieve only.

The TvbRange covering this field

11.6.2.14. fieldinfo.generated

Mode: Retrieve only.

Whether this field was marked as generated (boolean)

11.6.2.15. fieldinfo.name

Mode: Retrieve only.

The name of this field

11.6.3. Global Functions

11.6.3.1. all_field_infos()

Obtain all fields from the current tree. Note this only gets whatever fields the underlying dissectors have filled in for this packet at this time - there may be fields applicable to the packet that simply aren't being filled in because at this time they're not needed for anything. This function only gets what the C-side code has currently populated, not the full list.

11.6.3.1.1. Errors
  • Cannot be called outside a listener or dissector