GUI support

It is highly recommended to make GUI code conditional on gui_enabled(). Otherwise, scripts containing GUI code will cause an error in tshark (or cause tshark to crash Bug 6018).

ProgDlg

A modal progress bar dialog. Intended to be used with coroutines, where a main UI thread controls the progress bar dialog while a background coroutine (worker thread) yields to the main thread between steps. The main thread checks the status of the STOP button and if it's not set, returns control to the coroutine.

function	description
ProgDlg.new([title] [,task])	Creates a new progress dialog and displays it
progdlg:update(progress [,task])	Sets the progress dialog's progress bar position based on percentage done
progdlg:stopped()	Checks whether the user has pressed the Stop button
progdlg:close()	Closes the progress dialog

ProgDlg.new([title] [,task])

Description

Creates a new progress dialog (with a STOP button) and displays it. It is highly recommended to wrap the code that uses the ProgDlg instance because it does not automatically close itself upon encountering an error. Since the dialog is modal, it prevents access to any other Wireshark window. See the example. Cannot be run from tshark.

Parameters

title (optional) : string
- Text to display in title of the dialog window. Defaults to "Progress".
task (optional) : string
- Current task. Defaults to empty string ("").

Returns

userdata : The newly created ProgDlg object

Example

   1 if not gui_enabled() then return end
   2 
   3 local p = ProgDlg.new()
   4 
   5 -- we have to wrap the ProgDlg code in a pcall, in case some unexpected
   6 -- error occurs, preventing us from closing the modal dialog
   7 local ok, errmsg = pcall(function()
   8         local co = coroutine.create(
   9                 function()
  10                         local limit = 100000
  11                         for i=1,limit do
  12                                 print("co", i)
  13                                 coroutine.yield(i/limit, "step "..i.." of "..limit)
  14                         end
  15                 end
  16         )
  17 
  18         -- Whenever coroutine yields, check the status of the STOP button to determine
  19         -- when to break. Wait up to 20 sec for coroutine to finish.
  20         local start_time = os.time()
  21         while coroutine.status(co) ~= 'dead' do
  22                 local elapsed = os.time() - start_time
  23 
  24                 -- quit if STOP button pressed or 20 seconds elapsed
  25                 if p:stopped() or elapsed > 20 then
  26                         break
  27                 end
  28 
  29                 local res, val, val2 = coroutine.resume(co)
  30                 if not res or res == false then
  31                         if val then
  32                                 debug(val)
  33                         end
  34                         print('coroutine error')
  35                         break
  36                 end
  37 
  38                 -- show progress in progress dialog
  39                 p:update(val, val2)
  40         end
  41 end)
  42 
  43 p:close()
  44 
  45 if not ok and errmsg then
  46         report_failure(errmsg)
  47 end

progdlg:update(progress [,task])

Description
- Sets the progress dialog's progress bar position based on percentage done. Cannot be run from tshark.
Parameters
- progress : number
  - Percentage done. Value must be between 0.0 and 1.0.
  task (optional) : string
  - Current task. Defaults to empty string ("").
Errors
- progress value out of range

progdlg:stopped()

Description
- Checks whether the user has pressed the STOP button. Cannot be run from tshark.
Returns
- boolean : true if the user has pressed STOP; false otherwise

progdlg:close()

Description
- Closes the progress dialog

TextWindow

A text window

function	description
TextWindow.new([title])	Creates a new text window and displays it
textwindow:set_atclose(action)	Sets the function that is called when the window closes
textwindow:set(text)	Sets the text of the dialog
textwindow:append(text)	Appends text to the current text of the dialog window
textwindow:prepend(text)	Prepends text to the current text of the dialog window
textwindow:clear()	Clears the text of the dialog window
textwindow:get_text()	Gets the current text of the dialog window
textwindow:set_editable([editable])	Sets the enabled status of the text window's edit area
textwindow:add_button(label, function)	Adds a button with an action handler to the text window

TextWindow.new([title])

Description

Creates a new text window and displays it

Parameters

title (optional) : string
- Text to display in title of the dialog window. Defaults to "Untitled Window".

Returns

userdata : The newly created TextWindow object

Example

   1 if not gui_enabled() then return end
   2 
   3 -- create new text window and initialize its text
   4 local win = TextWindow.new("Log")
   5 win:set("Hello world!")
   6 
   7 -- add buttons to clear text window and to enable editing
   8 win:add_button("Clear", function() win:clear() end)
   9 win:add_button("Enable edit", function() win:set_editable(true) end)
  10 
  11 -- add button to change text to uppercase
  12 win:add_button("Uppercase", function()
  13         local text = win:get_text()
  14         if text ~= "" then
  15                 win:set(string.upper(text))
  16         end
  17 end)
  18 
  19 -- print "closing" to stdout when the user closes the text windw
  20 win:set_atclose(function() print("closing") end)

textwindow:set_atclose(action)

Description
- Sets the function that is called when the window closes. Cannot be run from tshark.
Parameters
- action : function
  - The function to be called when the window closes
Returns
- userdata: the TextWindow object

textwindow:set(text)

Description
- Sets the text of the dialog. Cannot be run from tshark.
Parameters
- text : string
  - The desired text
Returns
- string: the same value as text

textwindow:append(text)

Description
- Appends text to the current text of the dialog window. Cannot be run from tshark.
Parameters
- text : string
  - The text to append
Returns
- string: the same value as text

textwindow:prepend(text)

Description
- Prepends text to the current text of the dialog window. Cannot be run from tshark.
Parameters
- text : string
  - The text to prepend
Returns
- string: the same value as text

textwindow:clear()

Description
- Clears the text of the dialog window. Cannot be run from tshark.
Returns
- userdata: the TextWindow object

textwindow:get_text()

Description
- Gets the current text of the dialog window. Cannot be run from tshark.
Returns
- string: the text window's text

textwindow:set_editable([editable])

Description
- Sets the enabled status of the text window's edit area. Cannot be run from tshark.
Parameters
- editable (optional) : boolean
  - true to make the text window editable; false otherwise. Defaults to true.
Returns
- boolean: the same value as editable

textwindow:add_button(label, function)

Description
- Adds a button with an action handler to the text window. Cannot be run from tshark.
Parameters
- label : string
  - The label of the button
  function : function
  - The handler function to be called when the button is pressed
Returns
- userdata: the TextWindow object

Non Method Functions

function	description
gui_enabled()	Checks whether the GUI facility is enabled (always false from tshark)
register_menu(name, action [,group])	Register a menu item in one of the main menus
new_dialog(title, action, field1 [,field2 ...])	Displays a dialog, prompting for input. The dialog includes an OK button and Cancel button.
retap_packets()	Rescans all packets and runs taps (aka listener) without reconstructing the display
copy_to_clipboard(text)	Copies a string into the clipboard
open_capture_file(filename, filter)	Opens and displays a capture file
set_color_filter_slot(index, dfilter)	Sets a packet-coloring rule (by index) for the current session
set_filter(dfilter)	Sets the text of the display filter textbox in the GUI (does not apply the filter)
apply_filter()	Applies the current text in the display filter textbox to the current capture
reload()	Reloads the current capture file
browser_open_url(url)	Opens an URL in a web browser
browser_open_data_file(filepath)	Opens a file (located in the data directory) in a web browser

gui_enabled()

Description
- Checks whether the GUI facility is enabled (always false from tshark)
Returns
- boolean: true if enabled; false otherwise

register_menu(name, action [,group])

Description

Parameters

name : string

The label of the menu item. Use slashes to separate submenus. (e.g., "menu/submenu1")

action : function

The function to be called when the menu item is invoked

group (optional) : MenuGroup

The menu group into which the menu item is to be inserted. Defaults to MENU_STAT_GENERIC.

menu group	destination menu
`MENU_STAT_UNSORTED`	Statistics
`MENU_STAT_GENERIC`	Statistics (first section)
`MENU_STAT_CONVERSATION`	Statistics/Conversation List
`MENU_STAT_ENDPOINT`	Statistics/Endpoint List
`MENU_STAT_RESPONSE`	Statistics/Service Response Time
`MENU_STAT_TELEPHONY`	Telephony
`MENU_ANALYZE`	Analyze
`MENU_ANALYZE_CONVERSATION`	Analyze/Conversation Filter
`MENU_TOOLS_UNSORTED`	Tools

new_dialog(title, action, field1 [,field2 ...])

Description

Displays a dialog, prompting for input. The dialog includes an OK button and Cancel button. Cannot be run from tshark.

Parameters

title : string
- Text to display in the title of the dialog
action : function
- The function to be called when the OK button is pressed. The function's arguments will contain
  value1 [,value2 ...], which are string values corresponding to field1 [,field2 ...].
field1 [,field2 ...] : string
- Strings to be used a labels of the dialog's fields. Each string creates a new labeled field. The first field is required.

Errors

No fields specified

Example

   1 if not gui_enabled() then return end
   2 
   3 -- prompt for IP and port and then print them to stdout
   4 local label_ip = "IP address"
   5 local label_port = "Port"
   6 local function print_ip(ip, port)
   7         print(label_ip, ip)
   8         print(label_port, port)
   9 end
  10 new_dialog("Enter IP address", print_ip, label_ip, label_port)
  11 
  12 -- prompt for 4 numbers and then print their product to stdout
  13 new_dialog(
  14         "Enter 4 numbers",
  15         function (a, b, c, d) print(a * b * c * d) end,
  16         "a", "b", "c", "d"
  17         )

retap_packets()

Description
- Rescans all packets and runs taps (aka listeners) without reconstructing the display. Cannot be run from tshark.

copy_to_clipboard(text)

Description
- Copies a string into the clipboard. Cannot be run from tshark.
Parameters
- text : string
  - The string to be copied

open_capture_file(filename, filter)

Description
- Opens and displays a capture file. Cannot be run from tshark.
Parameters
- filename : string
  - The name fo the file to open
  filter : string
  - The display filter to be applied once the file is opened

set_color_filter_slot(index, dfilter)

Description

Sets a packet-coloring rule (by index) for the current session. Wireshark reserves 10 slots for these coloring rules. Cannot be run from tshark.

Parameters

index : number

The index (0-9) of the desired color in the temporary coloring rules list. The default foreground is black and the default backgrounds are listed below.

Default background colors

index	rgb (hex)	color
`0`	`ffc0c0`	pink 1
`1`	`ffc0ff`	pink 2
`2`	`e0c0e0`	purple 1
`3`	`c0c0ff`	purple 2
`4`	`c0e0e0`	green 1
`5`	`c0ffff`	green 2
`6`	`c0ffc0`	green 3
`7`	`ffffc0`	yellow 1
`8`	`e0e0c0`	yellow 2
`9`	`e0e0e0`	gray

The color list can be set from the command line using two "unofficial" preferences: the gui.colorized_frame.bg and gui.colorized_frame.fg preferences, which require 10 hex RGB codes (6 hex digits each).

wireshark -o gui.colorized_frame.bg:${RGB0},${RGB1},${RGB2},${RGB3},${RGB4},${RGB5},${RGB6},${RGB7},${RGB8},${RGB9}

For example, this command yields the same results as the table above (and with all foregrounds set to black):

wireshark -o gui.colorized_frame.bg:ffc0c0,ffc0ff,e0c0e0,c0c0ff,c0e0e0,c0ffff,c0ffc0,ffffc0,e0e0c0,e0e0e0 -o gui.colorized_frame.fg:000000,000000,000000,000000,000000,000000,000000,000000

dfilter : string

The display filter for selecting packets to be colorized

set_filter(dfilter)

Description
- Sets the text of the display filter textbox in the GUI (does not apply the filter). Cannot be run from tshark.
Parameters
- dfilter : string
  - A display filter string

apply_filter()

Description
- Applies the current text in the display filter textbox to the current capture. Cannot be run from tshark.
- $/!\$ Avoid calling this from within a dissector function or else an infinite loop can occur if it causes the dissector to be called again. This function is best used in a button callback (from a dialog or text window) or menu callback.

reload()

Description
- Reloads the current capture file. Cannot be run from tshark.
- $/!\$ Avoid calling this from within a dissector function or else an infinite loop can occur if it causes the dissector to be called again. This function is best used in a button callback (from a dialog or text window) or menu callback.

browser_open_url(url)

Description
- Opens an URL in a web browser. Cannot be run from tshark.
Parameters
- url : string
  - The URL to open

browser_open_data_file(filepath)

Description
- Opens a file (located in the data directory) in the web browser specified in Wireshark preferences. Cannot be run from tshark. If the file does not exist, the function silently ignores the request.
Parameters
- filepath : string
  - The file's path relative to the data directory.

LuaAPI/GUI

GUI support

ProgDlg

ProgDlg.new([title] [,task])

progdlg:update(progress [,task])

progdlg:stopped()

progdlg:close()

TextWindow

TextWindow.new([title])

textwindow:set_atclose(action)

textwindow:set(text)

textwindow:append(text)

textwindow:prepend(text)

textwindow:clear()

textwindow:get_text()

textwindow:set_editable([editable])

textwindow:add_button(label, function)

Non Method Functions

gui_enabled()

register_menu(name, action [,group])

new_dialog(title, action, field1 [,field2 ...])

retap_packets()

copy_to_clipboard(text)

open_capture_file(filename, filter)

set_color_filter_slot(index, dfilter)

set_filter(dfilter)

apply_filter()

reload()

browser_open_url(url)

browser_open_data_file(filepath)