Chapter 11. Wireshark’s Lua API Reference Manual

Table of Contents

11.1. Utility Functions
11.1.1. Global Functions
11.2. GUI Support
11.2.1. ProgDlg
11.2.2. TextWindow
11.2.3. Global Functions
11.3. Functions For New Protocols And Dissectors
11.3.1. Dissector
11.3.2. DissectorTable
11.3.3. Pref
11.3.4. Prefs
11.3.5. Proto
11.3.6. ProtoExpert
11.3.7. ProtoField
11.3.8. Global Functions
11.4. Obtaining Dissection Data
11.4.1. Field
11.4.2. FieldInfo
11.4.3. Global Functions
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 Handling Packet Data
11.6.1. ByteArray
11.6.2. Tvb
11.6.3. TvbRange
11.7. Adding Information To The Dissection Tree
11.7.1. TreeItem
11.7.2. Example
11.8. Post-Dissection Packet Analysis
11.8.1. Listener
11.9. Saving Capture Files
11.9.1. Dumper
11.9.2. PseudoHeader
11.10. Wtap Functions For Handling Capture File Types
11.10.1. Global Functions
11.11. Custom File Format Reading And Writing
11.11.1. CaptureInfo
11.11.2. CaptureInfoConst
11.11.3. File
11.11.4. FileHandler
11.11.5. FrameInfo
11.11.6. FrameInfoConst
11.11.7. Global Functions
11.12. Directory Handling Functions
11.12.1. Dir
11.12.2. Example
11.12.3. Example
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. PCRE2 Regular Expressions

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. Utility Functions

11.1.1. Global Functions

11.1.1.1. get_version()

Gets the Wireshark version as a string.

Returns

The version string, e.g. "3.2.5".

11.1.1.2. set_plugin_info(table)

Set a Lua table with meta-data about the plugin, such as version.

The passed-in Lua table entries need to be keyed/indexed by the following:

  • "version" with a string value identifying the plugin version (required)
  • "description" with a string value describing the plugin (optional)
  • "author" with a string value of the author’s name(s) (optional)
  • "repository" with a string value of a URL to a repository (optional)

Not all of the above key entries need to be in the table. The 'version' entry is required, however. The others are not currently used for anything, but might be in the future and thus using them might be useful. Table entries keyed by other strings are ignored, and do not cause an error.

11.1.1.3. Example

    local my_info = {
        version = "1.0.1",
        author = "Jane Doe",
        repository = "https://github.com/octocat/Spoon-Knife",
        spdx_id = "GPL-2.0-or-later",
        description = "Spoon-Knives can scoop and cut at the same time"
    }

    set_plugin_info(my_info)

Since: 1.99.8

Arguments
table
The Lua table of information.

11.1.1.4. format_date(timestamp)

Formats an absolute timestamp into a human readable date.

Arguments
timestamp
A timestamp value to convert.
Returns

A string with the formated date

11.1.1.5. format_time(timestamp)

Formats a relative timestamp in a human readable time.

Arguments
timestamp
A timestamp value to convert.
Returns

A string with the formated time

11.1.1.6. get_preference(preference)

Get a preference value. @since 3.5.0

Arguments
preference
The name of the preference.
Returns

The preference value, or nil if not found.

11.1.1.7. set_preference(preference, value)

Set a preference value. @since 3.5.0

Arguments
preference
The name of the preference.
value
The preference value to set.
Returns

true if changed, false if unchanged or nil if not found.

11.1.1.8. reset_preference(preference)

Reset a preference to default value. @since 3.5.0

Arguments
preference
The name of the preference.
Returns

true if valid preference

11.1.1.9. apply_preferences()

Write preferences to file and apply changes. @since 3.5.0

11.1.1.10. report_failure(text)

Reports a failure to the user.

Arguments
text
Message text to report.

11.1.1.11. loadfile(filename)

Loads a Lua file and compiles it into a Lua chunk, similar to the standard loadfile but searches additional directories. The search order is the current directory, followed by the user’s personal configuration directory, and finally the global configuration directory.

11.1.1.12. Example

    -- Assume foo.lua contains definition for foo(a,b). Load the chunk
    -- from the file and execute it to add foo(a,b) to the global table.
    -- These two lines are effectively the same as dofile('foo.lua').
    local loaded_chunk = assert(loadfile('foo.lua'))
    loaded_chunk()

    -- ok to call foo at this point
    foo(1,2)
Arguments
filename
Name of the file to be loaded. If the file does not exist in the current directory, the user and system directories are searched.

11.1.1.13. dofile(filename)

Loads a Lua file and executes it as a Lua chunk, similar to the standard dofile but searches additional directories. The search order is the current directory, followed by the user’s personal configuration directory, and finally the global configuration directory.

Arguments
filename
Name of the file to be run. If the file does not exist in the current directory, the user and system directories are searched.

11.1.1.14. register_stat_cmd_arg(argument, [action])

Register a function to handle a -z option

Arguments
argument
The name of the option argument.
action (optional)
The function to be called when the command is invoked.