Chapter 11. Wireshark’s Lua API Reference Manual

Table of Contents

11.1. Saving Capture Files
11.1.1. Dumper
11.1.2. PseudoHeader
11.2. Obtaining Dissection Data
11.2.1. Field
11.2.2. FieldInfo
11.2.3. Global Functions
11.3. GUI Support
11.3.1. ProgDlg
11.3.2. TextWindow
11.3.3. Global Functions
11.4. Post-Dissection Packet Analysis
11.4.1. Listener
11.5. Obtaining Packet Information
11.5.1. Address
11.5.2. Column
11.5.3. Columns
11.5.4. NSTime
11.5.5. Pinfo
11.5.6. PrivateTable
11.6. Functions For New Protocols And Dissectors
11.6.1. Dissector
11.6.2. DissectorTable
11.6.3. Pref
11.6.4. Prefs
11.6.5. Proto
11.6.6. ProtoExpert
11.6.7. ProtoField
11.6.8. Global Functions
11.7. Adding Information To The Dissection Tree
11.7.1. TreeItem
11.7.2. Example
11.8. Functions For Handling Packet Data
11.8.1. ByteArray
11.8.2. Tvb
11.8.3. TvbRange
11.9. Custom File Format Reading And Writing
11.9.1. CaptureInfo
11.9.2. CaptureInfoConst
11.9.3. File
11.9.4. FileHandler
11.9.5. FrameInfo
11.9.6. FrameInfoConst
11.9.7. Global Functions
11.10. Directory Handling Functions
11.10.1. Dir
11.10.2. Example
11.10.3. Example
11.11. Wtap Functions For Handling Capture File Types
11.11.1. Global Functions
11.12. Utility Functions
11.12.1. Global Functions
11.13. Handling 64-bit Integers
11.13.1. Int64
11.13.2. UInt64
11.14. Binary encode/decode support
11.14.1. Struct
11.15. GLib Regular Expressions
11.15.1. GRegex

This Part of the User Guide describes the Wireshark specific functions in the embedded Lua.

Classes group certain functionality, the following notational conventions are used:

Trying to access a non-existing property, function or method currently gives an error, but do not rely on it as the behavior may change in the future.

11.1. Saving Capture Files

The classes/functions defined in this module are for using a Dumper object to make Wireshark save a capture file to disk. Dumper represents Wireshark’s built-in file format writers (see the wtap_name_to_file_type_subtype function).

(The wtap_filetypes table in init.lua is deprecated, and should only be used in code that must run on Wireshark 3.4.3 and earlier 3.4 releases or in Wireshark 3.2.11 and earlier 3.2.x releases.)

To have a Lua script create its own file format writer, see the chapter titled "Custom file format reading/writing".

11.1.1. Dumper

11.1.1.1. Dumper.new(filename, [filetype], [encap])

Creates a file to write packets. Dumper:new_for_current() will probably be a better choice.

Arguments
filename
The name of the capture file to be created.
filetype (optional)
The type of the file to be created - a number returned by wtap_name_to_file_type_subtype(). (The wtap_filetypes table in init.lua is deprecated, and should only be used in code that must run on Wireshark 3.4.3 and earlier 3.4 releases or in Wireshark 3.2.11 and earlier 3.2.x releases.)
encap (optional)
The encapsulation to be used in the file to be created - a number entry from the wtap_encaps table in init.lua.
Returns

The newly created Dumper object

11.1.1.2. dumper:close()

Closes a dumper.

Errors
  • Cannot operate on a closed dumper

11.1.1.3. dumper:flush()

Writes all unsaved data of a dumper to the disk.

11.1.1.4. dumper:dump(timestamp, pseudoheader, bytearray)

Dumps an arbitrary packet. Note: Dumper:dump_current() will fit best in most cases.

Arguments
timestamp
The absolute timestamp the packet will have.
pseudoheader
The PseudoHeader to use.
bytearray
The data to be saved

11.1.1.5. dumper:new_for_current([filetype])

Creates a capture file using the same encapsulation as the one of the current packet.

Arguments
filetype (optional)
The file type. Defaults to pcap.
Returns

The newly created Dumper Object

Errors
  • Cannot be used outside a tap or a dissector

11.1.1.6. dumper:dump_current()

Dumps the current packet as it is.

Errors
  • Cannot be used outside a tap or a dissector

11.1.2. PseudoHeader

A pseudoheader to be used to save captured frames.

11.1.2.1. PseudoHeader.none()

Creates a "no" pseudoheader.

Returns

A null pseudoheader

11.1.2.2. PseudoHeader.eth([fcslen])

Creates an ethernet pseudoheader.

Arguments
fcslen (optional)
The fcs length
Returns

The ethernet pseudoheader

11.1.2.3. PseudoHeader.atm([aal], [vpi], [vci], [channel], [cells], [aal5u2u], [aal5len])

Creates an ATM pseudoheader.

Arguments
aal (optional)
AAL number
vpi (optional)
VPI
vci (optional)
VCI
channel (optional)
Channel
cells (optional)
Number of cells in the PDU
aal5u2u (optional)
AAL5 User to User indicator
aal5len (optional)
AAL5 Len
Returns

The ATM pseudoheader

11.1.2.4. PseudoHeader.mtp2([sent], [annexa], [linknum])

Creates an MTP2 PseudoHeader.

Arguments
sent (optional)
True if the packet is sent, False if received.
annexa (optional)
True if annex A is used.
linknum (optional)
Link Number.
Returns

The MTP2 pseudoheader