Differences between revisions 13 and 14
Revision 13 as of 2019-04-28 18:16:44
Size: 9739
Comment: Add print() and notes to critical(), warn(), message(), info() and debug() that they are no longer available as of Wireshark 3.0.
Revision 14 as of 2019-04-28 18:19:17
Size: 10079
Comment: Might as well add the "No longer available" notes to the "Non Method Functions" table as well.
Deletions are marked like this. Additions are marked like this.
Line 70: Line 70:
 ||[[#critical.28text.29|critical(text)]]||Writes a log message with critical severity to the Lua console and stdout||
 ||[[#warn.28text.29|warn(text)]]||Writes a log message with warning severity to the Lua console and stdout||
 ||[[#message.28text.29|message(text)]]||Writes a log message with normal severity to the Lua console and stdout||
 ||[[#info.28text.29|info(text)]]||Writes a log message with informational severity to the Lua console and stdout||
 ||[[#debug.28text.29|debug(text)]]||Writes a log message with debug severity to the Lua console and stdout||
 ||[[#critical.28text.29|critical(text)]]||Writes a log message with critical severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.||
 ||[[#warn.28text.29|warn(text)]]||Writes a log message with warning severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.||
 ||[[#message.28text.29|message(text)]]||Writes a log message with normal severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.||
 ||[[#info.28text.29|info(text)]]||Writes a log message with informational severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.||
 ||[[#debug.28text.29|debug(text)]]||Writes a log message with debug severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.||

Utility Functions


Dir

A directory object that iterates over its files and subdirectories (non-recursive)


Dir.open(pathname [,extension])

  • Description

    • Creates a directory object; opens a directory, returning an iterator over the directory's files and subdirectories (non-recursive)

    Parameters

    • pathname : string

      • The pathname of the directory

      extension (optional) : string

      • If given, only file with this extension will be returned

    Returns

    • userdata : the directory object

    Example

    •    1 for filename in Dir.open('/path/to/dir') do 
         2   print(filename)
         3 end
      


dir:__call()

  • Description

    • Gets the next file/subdirectory within the directory

    Returns

    • string : a filename of the next file/subdirectory within the directory; returns nil if all files iterated

    Example

    •    1 -- open a directory and print the name of the first file/subdir
         2 local dir = Dir.open('/path/to/dir')
         3 local first = dir()
         4 print( tostring(file) )
      


dir:close()

  • Description

    • Closes the directory. Called automatically on garbage collection of dir.


Non Method Functions

  • function

    description

    get_version()

    Gets the version of Wireshark

    format_date(timestamp)

    Formats an absolute timestamp into a human-readable date

    format_time(timestamp)

    Formats a relative timestamp into a human-readable form

    report_failure(text)

    Reports a failure to the user, shown in a message box with an error icon

    print(text)

    Writes a log message to the Lua console and stdout

    critical(text)

    Writes a log message with critical severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    warn(text)

    Writes a log message with warning severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    message(text)

    Writes a log message with normal severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    info(text)

    Writes a log message with informational severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    debug(text)

    Writes a log message with debug severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    loadfile(filename)

    Loads a Lua file and compiles it into a Lua chunk

    dofile(filename)

    Opens the named file and executes its contents as a Lua chunk

    persconffile_path([filename])

    Gets the personal configuration directory

    datafile_path([filename])

    Gets the global configuration directory

    register_stat_cmd_arg(argument, action)

    Registers a tshark statistics function, called with the -z option


get_version()

  • Description

    • Gets the version of Wireshark

    Returns

    • string : the version number (e.g., "1.6.0")


format_date(timestamp)

  • Description

    • Formats an absolute timestamp into a human-readable date

    Parameters

    • timestamp : string

      • A timestamp value to convert.

    Returns

    • string : The formatted date


format_time(timestamp)

  • Description

    • Formats a relative timestamp into a human-readable form

    Parameters

    • timestamp : string

      • A timestamp value to convert

    Returns

    • string : The formatted time


report_failure(text)

  • Description

    • Reports a failure to the user, shown in a message box with an error icon

    Parameters

    • text : string

      • the text to display in the message box


print(text)

  • Description

    • Writes a log message to the Lua console and stdout. This is the only Lua debug statement available as of Wireshark 3.0.

    Parameters

    • text : string

      • the text message to be logged


critical(text)

  • Description

    • Writes a log message with critical severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    Parameters

    • text : string

      • the text message to be logged


warn(text)

  • Description

    • Writes a log message with warning severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    Parameters

    • text : string

      • the text message to be logged


message(text)

  • Description

    • Writes a log message with normal severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    Parameters

    • text : string

      • the text message to be logged


info(text)

  • Description

    • Writes a log message with informational severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

    Parameters

    • text : string

      • the text message to be logged


debug(text)

  • Description

    • Writes a log message with debug severity to the Lua console and stdout. No longer available as of Wireshark 3.0; use print(text) instead.

      /!\ See Bug 5976. This function hides Lua's debug table.

    Parameters

    • text : string

      • the text message to be logged


loadfile(filename)

  • Description

    • Loads a Lua file and compiles it into a Lua chunk, similar to the standard loadfile but searches additional directories. The search order is: current directory, user's personal configuration directory (persconffile_path), and then the global configuration directory (datafile_path).

    Parameters

    • filename : string

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

    Returns

    • function : The compiled chunk as a function; otherwise returns nil plus the error message.

    Errors

    • File not found or file contains invalid Lua

    Example

    •    1 -- Assume foo.lua contains definition for foo(a,b). Load the chunk
         2 -- from the file and execute it to add foo(a,b) to the global table.
         3 -- These two lines are effectively the same as dofile('foo.lua').
         4 local loaded_chunk = assert(loadfile('foo.lua'))
         5 loaded_chunk()
         6 
         7 -- ok to call foo at this point
         8 foo(1,2)
      


dofile(filename)

  • Description

    • Opens the named file and executes its contents as a Lua chunk, similar to the standard dofile but searches additional directories. The search order is: current directory, user's personal configuration directory (persconffile_path), and then the global configuration directory (datafile_path).

    Parameter

    • filename : string

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

    Returns

    • all values returned by the Lua chunk

    Errors

    • File not found or file contains invalid Lua


persconffile_path([filename])

  • Description

    • Gets the personal configuration directory

    Parameters

    • filename (optional) : string

      • A filename (or directory name) that is appended to the path with the appropriate path separator

    Returns

    • string : The full pathname for a file in the personal configuration directory

    Example

    •    1 local path = persconffile_path('plugins')
         2 
         3 -- on Mac OS X, prints: /Users/tony/.wireshark/plugins
         4 print(path)
      


datafile_path([filename])

  • Description

    • Gets the global configuration directory

    Parameters

    • filename (optional)

      • A filename (or directory name) that is appended to the path with the appropriate path separator

    Returns

    • string : The full pathname for a file in Wireshark's global configuration directory

    Example

    •    1 local path = datafile_path('init.lua')
         2 
         3 -- on Mac OS X, prints: /Applications/Wireshark.app/Contents/Resources/share/wireshark/init.lua
         4 print(path)
      


register_stat_cmd_arg(argument, action)

  • Description

    • Registers a tshark statistics function, called with the -z option

    Parameters

    • argument : string

      • name of option argument

      action : function

      • function to be called when the command is invoked

LuaAPI/Utils (last edited 2019-04-28 18:19:17 by ChristopherMaynard)