11.4. Obtaining Dissection Data
Prev Chapter 11. Wireshark’s Lua API Reference Manual Next

11.4. Obtaining Dissection Data

11.4.1. Field

A Field extractor 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.4.1.1. Field.new(fieldname)

Create a Field extractor.

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

The field extractor

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

11.4.1.2. Field.list()

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

[Note]Note

This is an expensive operation, and should only be used for troubleshooting.

Returns

The array table of field filter names

11.4.1.3. field:__call()

Obtain all values (see FieldInfo) for this field.

Returns

All the values of this field

Errors
  • Fields cannot be used outside dissectors or taps

11.4.1.4. field:__tostring()

Obtain a string with the field filter name.

11.4.1.5. field.name

Mode: Retrieve only.

The filter name of this field, or nil.

11.4.1.6. field.display

Mode: Retrieve only.

The full display name of this field, or nil.

11.4.1.7. field.type

Mode: Retrieve only.

The ftype of this field, or nil.

11.4.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.4.2.1. fieldinfo:__len()

Obtain the Length of the field

11.4.2.2. fieldinfo:__unm()

Obtain the Offset of the field

11.4.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.range to get the TvbRange, and then use tvbrange:bytes() to convert it to a ByteArray.

11.4.2.4. fieldinfo:__tostring()

The string representation of the field.

11.4.2.5. fieldinfo:__eq()

Checks whether lhs is within rhs.

11.4.2.6. fieldinfo:__le()

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

Errors
  • Data source must be the same for both fields

11.4.2.7. fieldinfo:__lt()

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

Errors
  • Data source must be the same for both fields

11.4.2.8. fieldinfo.len

Mode: Retrieve only.

The length of this field.

11.4.2.9. fieldinfo.offset

Mode: Retrieve only.

The offset of this field.

11.4.2.10. fieldinfo.value

Mode: Retrieve only.

The value of this field.

11.4.2.11. fieldinfo.label

Mode: Retrieve only.

The string representing this field.

11.4.2.12. fieldinfo.display

Mode: Retrieve only.

The string display of this field as seen in GUI.

11.4.2.13. fieldinfo.type

Mode: Retrieve only.

The internal field type, a number which matches one of the ftype values.

11.4.2.14. fieldinfo.source

Mode: Retrieve only.

The source Tvb object the FieldInfo is derived from, or nil if there is none.

11.4.2.15. fieldinfo.range

Mode: Retrieve only.

The TvbRange covering the bytes of this field in a Tvb or nil if there is none.

11.4.2.16. fieldinfo.generated

Mode: Retrieve only.

Whether this field was marked as generated (boolean).

11.4.2.17. fieldinfo.hidden

Mode: Retrieve only.

Whether this field was marked as hidden (boolean).

11.4.2.18. fieldinfo.is_url

Mode: Retrieve only.

Whether this field was marked as being a URL (boolean).

11.4.2.19. fieldinfo.little_endian

Mode: Retrieve only.

Whether this field is little-endian encoded (boolean).

11.4.2.20. fieldinfo.big_endian

Mode: Retrieve only.

Whether this field is big-endian encoded (boolean).

11.4.2.21. fieldinfo.name

Mode: Retrieve only.

The filter name of this field.

11.4.3. Global Functions

11.4.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.

Errors
  • Cannot be called outside a listener or dissector
Prev Up Next
11.3. Functions For New Protocols And Dissectors Home 11.5. Obtaining Packet Information