11.2. Obtaining Dissection Data

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

11.2.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.2.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.2.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

Returns

The array table of field filter names

11.2.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.2.1.4. field:__tostring()

Obtain a string with the field filter name.

11.2.1.5. field.name

Mode: Retrieve only.

The filter name of this field, or nil.

Since: 1.99.8

11.2.1.6. field.display

Mode: Retrieve only.

The full display name of this field, or nil.

Since: 1.99.8

11.2.1.7. field.type

Mode: Retrieve only.

The ftype of this field, or nil.

Since: 1.99.8

11.2.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.2.2.1. fieldinfo:__len()

Obtain the Length of the field

11.2.2.2. fieldinfo:__unm()

Obtain the Offset of the field

11.2.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.2.2.4. fieldinfo:__tostring()

The string representation of the field.

11.2.2.5. fieldinfo:__eq()

Checks whether lhs is within rhs.

11.2.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.2.2.7. fieldinfo:__lt()

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

Errors

Data source must be the same for both fields

11.2.2.8. fieldinfo.len

Mode: Retrieve only.

The length of this field.

11.2.2.9. fieldinfo.offset

Mode: Retrieve only.

The offset of this field.

11.2.2.10. fieldinfo.value

Mode: Retrieve only.

The value of this field.

11.2.2.11. fieldinfo.label

Mode: Retrieve only.

The string representing this field.

11.2.2.12. fieldinfo.display

Mode: Retrieve only.

The string display of this field as seen in GUI.

11.2.2.13. fieldinfo.type

Mode: Retrieve only.

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

Since: 1.99.8

11.2.2.14. fieldinfo.source

Mode: Retrieve only.

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

Since: 1.99.8

11.2.2.15. fieldinfo.range

Mode: Retrieve only.

The TvbRange covering the bytes of this field in a Tvb.

11.2.2.16. fieldinfo.generated

Mode: Retrieve only.

Whether this field was marked as generated (boolean).

11.2.2.17. fieldinfo.hidden

Mode: Retrieve only.

Whether this field was marked as hidden (boolean).

Since: 1.99.8

11.2.2.18. fieldinfo.is_url

Mode: Retrieve only.

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

Since: 1.99.8

11.2.2.19. fieldinfo.little_endian

Mode: Retrieve only.

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

Since: 1.99.8

11.2.2.20. fieldinfo.big_endian

Mode: Retrieve only.

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

Since: 1.99.8

11.2.2.21. fieldinfo.name

Mode: Retrieve only.

The filter name of this field.

Since: 1.99.8

11.2.3. Global Functions

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