13.5. Obtaining Packet Information
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.5. Obtaining Packet Information

### 13.5.1. Address

Represents an address.

#### 13.5.1.1. Address.ip(hostname)

Creates an Address Object representing an IPv4 address.

##### Arguments

hostname
  The address or name of the IP host.

##### Returns

The Address object.

#### 13.5.1.2. Address.ipv6(hostname)

Creates an Address Object representing an IPv6 address.

##### Arguments

hostname
  The address or name of the IP host.

##### Returns

The Address object

#### 13.5.1.3. Address.ether(eth)

Creates an Address Object representing an Ethernet address.

##### Arguments

eth
  The Ethernet address.

##### Returns

The Address object.

#### 13.5.1.4. address:__tostring()

##### Returns

The string representing the address.

#### 13.5.1.5. address:__eq()

Compares two Addresses.

#### 13.5.1.6. address:__le()

Compares two Addresses.

#### 13.5.1.7. address:__lt()

Compares two Addresses.

### 13.5.2. Column

A Column in the packet list.

#### 13.5.2.1. column:__tostring()

##### Returns

The column’s string text (in parenthesis if not available).

#### 13.5.2.2. column:clear()

Clears a Column.

#### 13.5.2.3. column:set(text)

Sets the text of a Column.

##### Arguments

text
  The text to which to set the Column.

#### 13.5.2.4. column:append(text, [sep])

Appends text to a Column.

##### Arguments

text
  The text to append to the Column.

sep (optional)
  An optional separator to use as prefix if the column is not empty.

#### 13.5.2.5. column:prepend(text)

Prepends text to a Column.

##### Arguments

text
  The text to prepend to the Column.

#### 13.5.2.6. column:fence()

Sets Column text fence, to prevent overwriting.

#### 13.5.2.7. column:clear_fence()

Clear Column text fence.

### 13.5.3. Columns

The `Column`s of the packet list.

#### 13.5.3.1. columns:__tostring()

##### Returns

The string "Columns". This has no real use aside from debugging.

#### 13.5.3.2. columns:__newindex(column, text)

Sets the text of a specific column. Some columns cannot be modified, and no error is raised if attempted. The columns that are known to allow modification are "info" and "protocol".

##### Arguments

column
  The name of the column to set. Valid values are:

Name | Description
--- | ---
number | Frame number
abs_time | Absolute timestamp
utc_time | UTC timestamp
cls_time | CLS timestamp
rel_time | Relative timestamp
date | Absolute date and time
date_doy | Absolute year, day of year, and time
utc_date | UTC date and time
utc_date_doy | UTC year, day of year, and time
delta_time | Delta time from previous packet
delta_time_displayed | Delta time from previous displayed packet
src | Source address
src_res | Resolved source address
src_unres | Numeric source address
dl_src | Source data link address
dl_src_res | Resolved source data link address
dl_src_unres | Numeric source data link address
net_src | Source network address
net_src_res | Resolved source network address
net_src_unres | Numeric source network address
dst | Destination address
dst_res | Resolve destination address
dst_unres | Numeric destination address
dl_dst | Destination data link address
dl_dst_res | Resolved destination data link address
dl_dst_unres | Numeric destination data link address
net_dst | Destination network address
net_dst_res | Resolved destination network address
net_dst_unres | Numeric destination network address
src_port | Source port
src_port_res | Resolved source port
src_port_unres | Numeric source port
dst_port | Destination port
dst_port_res | Resolved destination port
dst_port_unres | Numeric destination port
protocol | Protocol name
info | General packet information
packet_len | Packet length
cumulative_bytes | Cumulative bytes in the capture
direction | Packet direction
vsan | Virtual SAN
tx_rate | Transmit rate
rssi | RSSI value
dce_call | DCE call

#### 13.5.3.3. Example

pinfo.cols['info'] = 'foo bar'

— syntactic sugar (equivalent to above) pinfo.cols.info = 'foo bar'

text
  The text for the column.

#### 13.5.3.4. columns:__index()

Get a specific `Column`.

### 13.5.4. Conversation

Conversation object, used to attach conversation data or a conversation dissector

#### 13.5.4.1. Conversation.find(framenum, ctype, addr1, [addr2], [port1], [port2], [create])

Searches for a `Conversation` instance matching criteria. If one does not exist and 'create' is true, one will be created, otherwise `nil` will be returned. Note that, although there are 'first' and 'second' addresses and ports, a conversation does not distinguish between source or destination. These are effectively matching criteria that wireshark uses to flag a packet as belonging to the conversation.

##### Arguments

framenum
  The number of a frame within the conversation. If a new conversation is created, this will be used as the first frame of the conversation.

ctype
  Conversation Type. One of: `convtypes.NONE`, `convtypes.SCTP`, `convtypes.TCP`, `convtypes.UDP`, `convtypes.DCCP`, `convtypes.IPX`, `convtypes.NCP`, `convtypes.EXCHG`, `convtypes.DDP`, `convtypes.SBCCS`, `convtypes.IDP`, `convtypes.TIPC`, `convtypes.USB`, `convtypes.I2C`, `convtypes.IBQP`, `convtypes.BLUETOOTH`, `convtypes.TDMOP`, `convtypes.DVBCI`, `convtypes.ISO14443`, `convtypes.ISDN`, `convtypes.H223`, `convtypes.X25`, `convtypes.IAX2`, `convtypes.DLCI`, `convtypes.ISUP`, `convtypes.BICC`, `convtypes.GSMTAP`, `convtypes.IUUP`, `convtypes.DVBBBF`, `convtypes.IWARP_MPA`, `convtypes.BT_UTP`, `convtypes.LOG`, `convtypes.LTP`, `convtypes.MCTP`, `convtypes.NVME_MI`, `convtypes.BP`, `convtypes.SNMP`, `convtypes.QUIC`, `convtypes.IDN`, `convtypes.IP`, `convtypes.IPV6`, `convtypes.ETH`, `convtypes.ETH_NN`, `convtypes.ETH_NV`, `convtypes.ETH_IN`, `convtypes.ETH_IV`, `convtypes.VSPC_VMOTION`, `convtypes.OPENVPN`, `convtypes.PROXY`, `convtypes.DNP3`

addr1
  First `Address` of the conversation.

addr2 (optional)
  Second `Address` of theconversation. (defaults to nil)

port1 (optional)
  First port. A value of `nil` or `0` is treated as 'ignore' (default)

port2 (optional)
  Second port. A value of `nil` or `0` is treated as 'ignore' (default)

create (optional)
  Boolean. If conversation doesn’t exist, create it (default true)

##### Returns

The found or created `Conversation` instance.

#### 13.5.4.2. Conversation.find_by_id(framenum, ctype, id, [create])

Searches for a `Conversation` object by id. If one does not exist and 'create' is true, one will be created, otherwise `nil` will be returned. This is typically used if a protocol encapsulates multiple 'sessions' or 'channels' in a single connection, and denotes this with a 'channel id' or equivalent.

##### Arguments

framenum
  The number of a frame within the conversation. If a new conversation is created, this will be used as the first frame of the conversation.

ctype
  Conversation Type. One of: `convtypes.NONE`, `convtypes.SCTP`, `convtypes.TCP`, `convtypes.UDP`, `convtypes.DCCP`, `convtypes.IPX`, `convtypes.NCP`, `convtypes.EXCHG`, `convtypes.DDP`, `convtypes.SBCCS`, `convtypes.IDP`, `convtypes.TIPC`, `convtypes.USB`, `convtypes.I2C`, `convtypes.IBQP`, `convtypes.BLUETOOTH`, `convtypes.TDMOP`, `convtypes.DVBCI`, `convtypes.ISO14443`, `convtypes.ISDN`, `convtypes.H223`, `convtypes.X25`, `convtypes.IAX2`, `convtypes.DLCI`, `convtypes.ISUP`, `convtypes.BICC`, `convtypes.GSMTAP`, `convtypes.IUUP`, `convtypes.DVBBBF`, `convtypes.IWARP_MPA`, `convtypes.BT_UTP`, `convtypes.LOG`, `convtypes.LTP`, `convtypes.MCTP`, `convtypes.NVME_MI`, `convtypes.BP`, `convtypes.SNMP`, `convtypes.QUIC`, `convtypes.IDN`, `convtypes.IP`, `convtypes.IPV6`, `convtypes.ETH`, `convtypes.ETH_NN`, `convtypes.ETH_NV`, `convtypes.ETH_IN`, `convtypes.ETH_IV`, `convtypes.VSPC_VMOTION`, `convtypes.OPENVPN`, `convtypes.PROXY`, `convtypes.DNP3`

id
  Conversation or session specific ID

create (optional)
  Boolean. If conversation doesn’t exist, create it (default true)

##### Returns

The found or created `Conversation` instance.

#### 13.5.4.3. Conversation.find_from_pinfo(pinfo, [create])

Searches for a `Conversation` object matching a pinfo. If one does not exist and 'create' is true, one will be created, otherwise `nil` will be returned. Note that this is a shortcut for `Conversation.find()`, where a pinfo structure is conveniently decomposed into individual components for you. If you’re not sure which `Conversation.find` method to use, most of the time this will the the correct choice.

##### Arguments

pinfo
  A `Pinfo` object.

create (optional)
  Boolean. If conversation doesn’t exist, create it (default true)

##### Returns

The found or created `Conversation` instance.

#### 13.5.4.4. conversation:__eq()

Compares two Conversation objects.

##### Returns

True if both objects refer to the same underlying conversation structure. False otherwise.

#### 13.5.4.5. conversation:__tostring()

##### Returns

A string representation of the object.

#### 13.5.4.6. conversation:__newindex(index, value)

Sets protocol data for a specific protocol

##### Arguments

index
  The protocol index to set. Must be a `Proto`

value
  The protocol data to set (any valid lua object)

#### 13.5.4.7. conversation:__index(index)

Get protocol data for a specific protocol

##### Arguments

index
  The protocol index to get. Must be a `Proto`

##### Returns

Previously assigned conversation data, or `nil`.

#### 13.5.4.8. conversation.dissector

Mode: Assign only.

Sets the dissector to be used for the conversation. Accepted types are either a `Proto` with assigned dissector, or a `Dissector`.

### 13.5.5. NSTime

NSTime represents a nstime_t. This is an object with seconds and nanoseconds.

#### 13.5.5.1. NSTime.new([seconds], [nseconds])

Creates a new NSTime object.

##### Arguments

seconds (optional)
  Seconds.

nseconds (optional)
  Nano seconds.

##### Returns

The new NSTime object.

#### 13.5.5.2. nstime:__call([seconds], [nseconds])

Creates a NSTime object.

##### Arguments

seconds (optional)
  Seconds.

nseconds (optional)
  Nanoseconds.

##### Returns

The new NSTime object.

#### 13.5.5.3. nstime:tonumber()

Returns a Lua number of the `NSTime` representing seconds from epoch.

##### Returns

The Lua number.

#### 13.5.5.4. nstime:__tostring()

##### Returns

The string representing the nstime.

#### 13.5.5.5. nstime:__add()

Calculates the sum of two NSTimes.

#### 13.5.5.6. nstime:__sub()

Calculates the diff of two NSTimes.

#### 13.5.5.7. nstime:__unm()

Calculates the negative NSTime.

#### 13.5.5.8. nstime:__eq()

Compares two NSTimes.

#### 13.5.5.9. nstime:__le()

Compares two NSTimes.

#### 13.5.5.10. nstime:__lt()

Compares two NSTimes.

#### 13.5.5.11. nstime.secs

Mode: Retrieve or assign.

The NSTime seconds.

#### 13.5.5.12. nstime.nsecs

Mode: Retrieve or assign.

The NSTime nano seconds.

### 13.5.6. Pinfo

Packet information.

#### 13.5.6.1. pinfo.visited

Mode: Retrieve only.

Whether this packet has been already visited.

#### 13.5.6.2. pinfo.number

Mode: Retrieve only.

The number of this packet in the current file.

#### 13.5.6.3. pinfo.len

Mode: Retrieve only.

The length of the frame.

#### 13.5.6.4. pinfo.caplen

Mode: Retrieve only.

The captured length of the frame.

#### 13.5.6.5. pinfo.abs_ts

Mode: Retrieve only.

When the packet was captured.

#### 13.5.6.6. pinfo.rel_ts

Mode: Retrieve only.

Number of seconds passed since beginning of capture.

#### 13.5.6.7. pinfo.delta_ts

Mode: Retrieve only.

Number of seconds passed since the last captured packet.

#### 13.5.6.8. pinfo.delta_dis_ts

Mode: Retrieve only.

Number of seconds passed since the last displayed packet.

#### 13.5.6.9. pinfo.curr_proto

Mode: Retrieve only.

Which Protocol are we dissecting.

#### 13.5.6.10. pinfo.can_desegment

Mode: Retrieve or assign.

Set if this segment could be desegmented.

#### 13.5.6.11. pinfo.saved_can_desegment

Mode: Retrieve only.

Value of can_desegment before the current dissector was called. Supplied so that proxy protocols like SOCKS can restore it to whatever the previous dissector (e.g. TCP) set it, so that the dissectors they call are desegmented via the previous dissector. Since: 4.3.1

#### 13.5.6.12. pinfo.desegment_len

Mode: Retrieve or assign.

Estimated number of additional bytes required for completing the PDU.

#### 13.5.6.13. pinfo.desegment_offset

Mode: Retrieve or assign.

Offset in the tvbuff at which the dissector will continue processing when next called.

#### 13.5.6.14. pinfo.fragmented

Mode: Retrieve only.

If the protocol is only a fragment.

#### 13.5.6.15. pinfo.in_error_pkt

Mode: Retrieve or assign.

If we’re inside an error packet.

#### 13.5.6.16. pinfo.match_uint

Mode: Retrieve only.

Matched uint for calling subdissector from table.

#### 13.5.6.17. pinfo.match_string

Mode: Retrieve only.

Matched string for calling subdissector from table.

#### 13.5.6.18. pinfo.port_type

Mode: Retrieve or assign.

Type of Port of .src_port and .dst_port.

#### 13.5.6.19. pinfo.src_port

Mode: Retrieve or assign.

Source Port of this Packet.

#### 13.5.6.20. pinfo.dst_port

Mode: Retrieve or assign.

Destination Port of this Packet.

#### 13.5.6.21. pinfo.dl_src

Mode: Retrieve or assign.

Data Link Source Address of this Packet.

#### 13.5.6.22. pinfo.dl_dst

Mode: Retrieve or assign.

Data Link Destination Address of this Packet.

#### 13.5.6.23. pinfo.net_src

Mode: Retrieve or assign.

Network Layer Source Address of this Packet.

#### 13.5.6.24. pinfo.net_dst

Mode: Retrieve or assign.

Network Layer Destination Address of this Packet.

#### 13.5.6.25. pinfo.src

Mode: Retrieve or assign.

Source Address of this Packet.

#### 13.5.6.26. pinfo.dst

Mode: Retrieve or assign.

Destination Address of this Packet.

#### 13.5.6.27. pinfo.p2p_dir

Mode: Retrieve or assign.

Direction of this Packet. (incoming / outgoing)

#### 13.5.6.28. pinfo.match

Mode: Retrieve only.

Port/Data we are matching.

#### 13.5.6.29. pinfo.columns

Mode: Retrieve only.

Access to the packet list columns.

#### 13.5.6.30. pinfo.cols

Mode: Retrieve only.

Access to the packet list columns (equivalent to pinfo.columns).

#### 13.5.6.31. pinfo.private

Mode: Retrieve only.

Access to the private table entries.

#### 13.5.6.32. pinfo.hi

Mode: Retrieve or assign.

Higher Address of this Packet.

#### 13.5.6.33. pinfo.lo

Mode: Retrieve only.

Lower Address of this Packet.

#### 13.5.6.34. pinfo.conversation

Mode: Retrieve or assign.

On read, returns a `Conversation` object (equivalent to `Conversation.find_from_pinfo(pinfo, 0, True)`)

On write, sets the `Dissector` for the current conversation (shortcut for `pinfo.conversation.dissector = dissector`). Accepts either a `Dissector` object or a `Proto` object with an assigned dissector

### 13.5.7. PrivateTable

PrivateTable represents the pinfo→private_table.

#### 13.5.7.1. privatetable:__tostring()

Gets debugging type information about the private table.

##### Returns

A string with all keys in the table, mostly for debugging.

Prev | Up | Next
13.4. Obtaining Dissection Data | Home | 13.6. Functions For Handling Packet Data