Chapter 13. Wireshark’s Lua API Reference Manual
Prev | Part II. Wireshark Development | Next

## Chapter 13. Wireshark’s Lua API Reference Manual

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:

- Class.function() represents a class method (named function) on class Class, taking no arguments.
- Class.function(a) represents a class method taking one argument.
- Class.function(…​) represents a class method taking a variable number of arguments.
- class:method() represents an instance method (named method) on an instance of class Class, taking no arguments. Note the lowercase notation in the documentation to clarify an instance.
- class.prop represents a property prop on the instance of class Class.

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.

## 13.1. Utility Functions

### 13.1.1. Global Functions

#### 13.1.1.1. get_version()

Gets the Wireshark version as a string.

##### Returns

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

#### 13.1.1.2. lua_release()

Gets the Lua release as a string.

##### Returns

The version string, e.g. "Lua 5.4.6 (UfW patched)".

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

#### 13.1.1.4. Example

        local my_info = {
            version = "1.0.1",
            author = "Jane Doe",
            repository = "https://github.com/octocat/Spoon-Knife"
        }

        set_plugin_info(my_info)

##### Arguments

table
  The Lua table of information.

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

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

#### 13.1.1.7. get_preference(preference)

Get a preference value.

##### Arguments

preference
  The name of the preference.

##### Returns

The preference value, or nil if not found.

#### 13.1.1.8. set_preference(preference, value)

Set a preference value.

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

#### 13.1.1.9. reset_preference(preference)

Reset a preference to default value.

##### Arguments

preference
  The name of the preference.

##### Returns

true if valid preference

#### 13.1.1.10. apply_preferences()

Write preferences to file and apply changes.

#### 13.1.1.11. report_failure(text)

Reports a failure to the user.

##### Arguments

text
  Message text to report.

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

| The configuration directories are not the plugin directories.
The configuration directories searched are not the global and personal plugin directories. All Lua files in the plugin directories are loaded at startup; `dofile` is for loading files from additional locations. The file path can be absolute or relative to one of the search directories.

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

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

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

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

Prev | Up | Next
12.5. Example: Lua scripts with shared modules | Home | 13.2. GUI Support