13.4. Obtaining Dissection Data
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.4. Obtaining Dissection Data

### 13.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.

#### 13.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

#### 13.4.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.

##### Returns

The array table of field filter names

#### 13.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

#### 13.4.1.4. field:__tostring()

Obtain a string with the field filter name.

#### 13.4.1.5. field.name

Mode: Retrieve only.

The filter name of this field, or nil.

#### 13.4.1.6. field.display

Mode: Retrieve only.

The full display name of this field, or nil.

#### 13.4.1.7. field.type

Mode: Retrieve only.

The `ftype` of this field, or nil.

### 13.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`.

#### 13.4.2.1. fieldinfo:__len()

Obtain the Length of the field

#### 13.4.2.2. fieldinfo:__unm()

Obtain the Offset of the field

#### 13.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`.

#### 13.4.2.4. fieldinfo:__tostring()

The string representation of the field.

#### 13.4.2.5. fieldinfo:__eq()

Checks whether lhs is within rhs.

#### 13.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

#### 13.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

#### 13.4.2.8. fieldinfo.len

Mode: Retrieve only.

The length of this field.

#### 13.4.2.9. fieldinfo.offset

Mode: Retrieve only.

The offset of this field.

#### 13.4.2.10. fieldinfo.value

Mode: Retrieve only.

The value of this field.

#### 13.4.2.11. fieldinfo.label

Mode: Retrieve only.

The string representing this field.

#### 13.4.2.12. fieldinfo.display

Mode: Retrieve only.

The string display of this field as seen in GUI.

#### 13.4.2.13. fieldinfo.type

Mode: Retrieve only.

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

#### 13.4.2.14. fieldinfo.source

Mode: Retrieve only.

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

#### 13.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.

#### 13.4.2.16. fieldinfo.generated

Mode: Retrieve only.

Whether this field was marked as generated (boolean).

#### 13.4.2.17. fieldinfo.hidden

Mode: Retrieve only.

Whether this field was marked as hidden (boolean).

#### 13.4.2.18. fieldinfo.is_url

Mode: Retrieve only.

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

#### 13.4.2.19. fieldinfo.little_endian

Mode: Retrieve only.

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

#### 13.4.2.20. fieldinfo.big_endian

Mode: Retrieve only.

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

#### 13.4.2.21. fieldinfo.name

Mode: Retrieve only.

The filter name of this field.

### 13.4.3. Global Functions

#### 13.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

#### 13.4.3.2. request_fields(fieldnames)

Request one or multiple fields by their filter names.

This function tells Wireshark to populate the specified fields during dissection. For performance reasons, Wireshark dissectors don’t add all possible fields to the dissection tree by default - they only add fields that are explicitly requested (e.g., via display filters, taps, or this function). This significantly reduces memory usage and improves dissection speed, especially for fields that are expensive to compute or rarely needed.

Without calling this function (or Field.new()), fields may exist in the protocol but won’t be available in the dissection tree when you try to access them via all_field_infos() or other field extraction methods.

This function must be called outside of callback functions (dissectors, taps, etc.).

###### Example

           -- Request a single field
           request_fields("ip.src")

           -- Request multiple fields
           request_fields({"ip.src", "ip.dst", "tcp.port"})

@param fieldnames A string or table (array) of field filter names to request (e.g. "ip.src" or {"ip.src", "tcp.port"}) Since: 4.7.0

##### Arguments

fieldnames
  String or table of field filter names

#### 13.4.3.3. request_protocol_fields(protocols)

Request all fields from one or more specified protocols.

This function tells Wireshark to populate all fields from the specified protocol(s) during dissection. Normally, Wireshark dissectors use a "lazy" approach and only add fields to the dissection tree when they are actually needed (e.g., when a display filter references them, or when Field.new() explicitly requests them). This optimization dramatically improves performance and reduces memory consumption, especially for protocols with many fields or computationally expensive field values.

By calling this function, you’re telling Wireshark: "I need ALL fields from protocol X, so please populate them all during dissection, even if they’re not otherwise needed."

Use this function carefully with protocols that have many fields, as it can impact performance. For better performance, prefer request_fields() to request only specific fields you actually need.

This function must be called outside of callback functions (dissectors, taps, etc.).

Returns a table (array) of protocol names that were successfully requested. Unknown protocol names are ignored.

###### Example

           -- Request all fields from a single protocol
           request_protocol_fields("http")

           -- Request all fields from multiple protocols
           request_protocol_fields({"ip", "tcp", "udp"})

@param protocols A string or table (array) of protocol names (e.g. "ip" or {"ip", "tcp", "http"}) Since: 4.7.0

##### Arguments

protocols
  String or table of protocol names

Prev | Up | Next
13.3. Functions For New Protocols And Dissectors | Home | 13.5. Obtaining Packet Information