11.4. Wireshark's Lua API Reference Manual
Prev Chapter 11. Lua Support in Wireshark Next

11.4. Wireshark's Lua API Reference Manual

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

11.4.1.  Saving capture files

11.4.1.1. Dumper

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

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

11.4.1.1.1.1. Arguments
filename

The name of the capture file to be created

filetype (optional)

The type of the file to be created

encap (optional)

The encapsulation to be used in the file to be created

11.4.1.1.1.2. Returns

The newly created Dumper object

11.4.1.1.1.3. Errors

  • Not every filetype handles every encap

11.4.1.1.2. dumper:close()

Closes a dumper

11.4.1.1.2.1. Errors

  • Cannot operate on a closed dumper

11.4.1.1.3. dumper:flush()

Writes all unsaved data of a dumper to the disk.

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

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

11.4.1.1.4.1. Arguments
timestamp

The absolute timestamp the packet will have

pseudoheader

The Pseudoheader to use.

bytearray

the data to be saved

11.4.1.1.5. dumper:new_for_current([filetype])

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

11.4.1.1.5.1. Arguments
filetype (optional)

The file type. Defaults to pcap.

11.4.1.1.5.2. Returns

The newly created Dumper Object

11.4.1.1.5.3. Errors

  • Cannot be used outside a tap or a dissector

11.4.1.1.6. dumper:dump_current()

Dumps the current packet as it is.

11.4.1.1.6.1. Errors

  • Cannot be used outside a tap or a dissector

11.4.1.2. PseudoHeader

A pseudoheader to be used to save captured frames.

11.4.1.2.1. PseudoHeader.none()

Creates a "no" pseudoheader.

11.4.1.2.1.1. Returns

A null pseudoheader

11.4.1.2.2. PseudoHeader.eth([fcslen])

Creates an ethernet pseudoheader

11.4.1.2.2.1. Arguments
fcslen (optional)

The fcs length

11.4.1.2.2.2. Returns

The ethernet pseudoheader

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

Creates an ATM pseudoheader

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

11.4.1.2.3.2. Returns

The ATM pseudoheader

11.4.1.2.4. PseudoHeader.mtp2()

Creates an MTP2 PseudoHeader

11.4.1.2.4.1. Returns

The MTP2 pseudoheader

11.4.2.  Obtaining dissection data

11.4.2.1. Field

A Field extractor to to obtain field values.

11.4.2.1.1. Field.new(fieldname)

Create a Field extractor

11.4.2.1.1.1. Arguments
fieldname

The filter name of the field (e.g. ip.addr)

11.4.2.1.1.2. Returns

The field extractor

11.4.2.1.1.3. Errors

  • A Field extractor must be defined before Taps or Dissectors get called

11.4.2.1.2. field:__call()

Obtain all values (see FieldInfo) for this field.

11.4.2.1.2.1. Returns

All the values of this field

11.4.2.1.2.2. Errors

  • Fields cannot be used outside dissectors or taps

11.4.2.2. FieldInfo

An extracted Field

11.4.2.2.1. fieldinfo:__len()

Obtain the Length of the field

11.4.2.2.2. fieldinfo:__unm()

Obtain the Offset of the field

11.4.2.2.3. fieldinfo:__call()

Obtain the Value of the field

11.4.2.2.4. fieldinfo:__tostring()

The string representation of the field

11.4.2.2.5. fieldinfo:__eq()

Checks whether lhs is within rhs

11.4.2.2.5.1. Errors

  • Data source must be the same for both fields

11.4.2.2.6. fieldinfo:__le()

Checks whether the end byte of lhs is before the end of rhs

11.4.2.2.7. fieldinfo:__lt()

Checks whether the end byte of rhs is before the beginning of rhs

11.4.2.2.7.1. Errors

  • Data source must be the same for both fields

11.4.2.2.8. fieldinfo.name

The name of this field

11.4.2.2.9. fieldinfo.label

The string representing this field

11.4.2.2.10. fieldinfo.value

The value of this field

11.4.2.2.11. fieldinfo.len

The length of this field

11.4.2.2.12. fieldinfo.offset

The offset of this field

11.4.2.3. Non Method Functions

11.4.2.3.1. all_field_infos()

Obtain all fields from the current tree

11.4.2.3.1.1. Errors

  • Cannot be called outside a listener or dissector

11.4.3.  GUI support

11.4.3.1. ProgDlg

Manages a progress bar dialog.

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

Creates a new TextWindow.

11.4.3.1.1.1. Arguments
title (optional)

Title of the new window, defaults to "Progress".

task (optional)

Current task, defaults to "".

11.4.3.1.1.2. Returns

The newly created TextWindow object.

11.4.3.1.2. progdlg:update(progress, [task])

Appends text

11.4.3.1.2.1. Arguments
progress

Part done ( e.g. 0.75 ).

task (optional)

Current task, defaults to "".

11.4.3.1.2.2. Errors

  • Cannot be called for something not a ProgDlg

  • Progress value out of range (must be between 0.0 and 1.0)

11.4.3.1.3. progdlg:stopped()

Checks wheher the user has pressed the stop button.

11.4.3.1.3.1. Returns

true if the user has asked to stop the progress.

11.4.3.1.3.2. Errors

  • Cannot be called for something not a ProgDlg

11.4.3.1.4. progdlg:close()

Appends text

11.4.3.1.4.1. Errors

  • Cannot be called for something not a ProgDlg

11.4.3.2. TextWindow

Manages a text window.

11.4.3.2.1. TextWindow.new([title])

Creates a new TextWindow.

11.4.3.2.1.1. Arguments
title (optional)

Title of the new window.

11.4.3.2.1.2. Returns

The newly created TextWindow object.

11.4.3.2.2. textwindow:set_atclose(action)

Set the function that will be called when the window closes

11.4.3.2.2.1. Arguments
action

A function to be executed when the user closes the window

11.4.3.2.2.2. Returns

The TextWindow object.

11.4.3.2.2.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.3. textwindow:set(text)

Sets the text.

11.4.3.2.3.1. Arguments
text

The text to be used.

11.4.3.2.3.2. Returns

The TextWindow object.

11.4.3.2.3.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.4. textwindow:append(text)

Appends text

11.4.3.2.4.1. Arguments
text

The text to be appended

11.4.3.2.4.2. Returns

The TextWindow object.

11.4.3.2.4.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.5. textwindow:prepend(text)

Prepends text

11.4.3.2.5.1. Arguments
text

The text to be appended

11.4.3.2.5.2. Returns

The TextWindow object.

11.4.3.2.5.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.6. textwindow:clear()

Erases all text in the window.

11.4.3.2.6.1. Returns

The TextWindow object.

11.4.3.2.6.2. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.7. textwindow:get_text()

Get the text of the window

11.4.3.2.7.1. Returns

The TextWindow's text.

11.4.3.2.7.2. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.8. textwindow:set_editable([editable])

Make this window editable

11.4.3.2.8.1. Arguments
editable (optional)

A boolean flag, defaults to true

11.4.3.2.8.2. Returns

The TextWindow object.

11.4.3.2.8.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.2.9. textwindow:add_button(label, function)
11.4.3.2.9.1. Arguments
label

The label of the button

function

The function to be called when clicked

11.4.3.2.9.2. Returns

The TextWindow object.

11.4.3.2.9.3. Errors

  • Cannot be called for something not a TextWindow

11.4.3.3. Non Method Functions

11.4.3.3.1. gui_enabled()

Checks whether the GUI facility is enabled.

11.4.3.3.1.1. Returns

A boolean: true if it is enabled, false if it isn't.

11.4.3.3.2. register_menu(name, action, [group])

Register a menu item in one of the main menus.

11.4.3.3.2.1. Arguments
name

The name of the menu item. The submenus are to be separated by '/'s. (string)

action

The function to be called when the menu item is invoked. (function taking no arguments and returning nothing)

group (optional)

The menu group into which the menu item is to be inserted. If omitted, defaults to MENU_STAT_GENERIC. One of 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). (number)

11.4.3.3.3. new_dialog(title, action, ...)

Pops up a new dialog

11.4.3.3.3.1. Arguments
title

Title of the dialog's window.

action

Action to be performed when OKd.

...

A series of strings to be used as labels of the dialog's fields

11.4.3.3.3.2. Errors

  • At least one field required

  • All fields must be strings

11.4.3.3.4. retap_packets()

Rescan all packets and just run taps - don't reconstruct the display.

11.4.3.3.5. copy_to_clipboard(text)

Copy a string into the clipboard

11.4.3.3.5.1. Arguments
text

The string to be copied into the clipboard.

11.4.3.3.6. open_capture_file(filename, filter)

Open and display a capture file

11.4.3.3.6.1. Arguments
filename

The name of the file to be opened.

filter

A filter to be applied as the file gets opened.

11.4.3.3.7. set_filter(text)

Set the main filter text

11.4.3.3.7.1. Arguments
text

The filter's text.

11.4.3.3.8. apply_filter()

Apply the filter in the main filter box

11.4.3.3.9. reload()

Reload the current capture file

11.4.3.3.10. browser_open_url(url)

Open an url in a browser

11.4.3.3.10.1. Arguments
url

The url.

11.4.3.3.11. browser_open_data_file(filename)

Open an file in a browser

11.4.3.3.11.1. Arguments
filename

The url.

11.4.4.  Post-dissection packet analysis

11.4.4.1. Listener

A Listener, is called once for every packet that matches a certain filter or has a certain tap. It can read the tree, the packet's Tvb eventually the tapped data but it cannot add elements to the tree.

11.4.4.1.1. Listener.new([tap], [filter])

Creates a new Listener listener

11.4.4.1.1.1. Arguments
tap (optional)

The name of this tap

filter (optional)

A filter that when matches the tap.packet function gets called (use nil to be called for every packet)

11.4.4.1.1.2. Returns

The newly created Listener listener object

11.4.4.1.1.3. Errors

  • tap registration error

11.4.4.1.2. listener:remove()

Removes a tap listener

11.4.4.1.3. listener.packet

A function that will be called once every packet matches the Listener listener filter. function tap.packet(pinfo,tvb,userdata) ... end

11.4.4.1.4. listener.draw

A function that will be called once every few seconds to redraw the gui objects in tshark this funtion is called oly at the very end of the capture file. function tap.draw(userdata) ... end

11.4.4.1.5. listener.reset

A function that will be called at the end of the capture run. function tap.reset(userdata) ... end

11.4.5.  Obtaining packet information

11.4.5.1. Address

Represents an address

11.4.5.1.1. Address.ip(hostname)

Creates an Address Object representing an IP address.

11.4.5.1.1.1. Arguments
hostname

The address or name of the IP host.

11.4.5.1.1.2. Returns

The Address object

11.4.5.1.2. address:__tostring()
11.4.5.1.2.1. Returns

The string representing the address.

11.4.5.1.3. address:__eq()

Compares two Addresses

11.4.5.1.4. address:__le()

Compares two Addresses

11.4.5.1.5. address:__lt()

Compares two Addresses

11.4.5.2. Column

A Column in the packet list

11.4.5.2.1. column:__tostring()
11.4.5.2.1.1. Returns

A string representing the column

11.4.5.2.2. column:clear()

Clears a Column

11.4.5.2.3. column:set(text)

Sets the text of a Column

11.4.5.2.3.1. Arguments
text

The text to which to set the Column

11.4.5.2.4. column:append(text)

Appends text to a Column

11.4.5.2.4.1. Arguments
text

The text to append to the Column

11.4.5.2.5. column:preppend(text)

Prepends text to a Column

11.4.5.2.5.1. Arguments
text

The text to prepend to the Column

11.4.5.3. Columns

The Columns of the packet list.

11.4.5.3.1. columns:__tostring()
11.4.5.3.1.1. Returns

The string "Columns", no real use, just for debugging purposes.

11.4.5.3.2. columns:__newindex(column, text)

Sets the text of a specific column

11.4.5.3.2.1. Arguments
column

The name of the column to set

text

The text for the column

11.4.5.4. Pinfo

Packet information

11.4.5.4.1. pinfo.number

The number of this packet in the current file

11.4.5.4.2. pinfo.len

The length of the frame

11.4.5.4.3. pinfo.caplen

The captured length of the frame

11.4.5.4.4. pinfo.abs_ts

When the packet was captured

11.4.5.4.5. pinfo.rel_ts

Number of seconds passed since beginning of capture

11.4.5.4.6. pinfo.delta_ts

Number of seconds passed since the last captured packet

11.4.5.4.7. pinfo.delta_dis_ts

Number of seconds passed since the last displayed packet

11.4.5.4.8. pinfo.visited

Whether this packet hass been already visited

11.4.5.4.9. pinfo.src

Source Address of this Packet

11.4.5.4.10. pinfo.dst

Destination Address of this Packet

11.4.5.4.11. pinfo.lo

lower Address of this Packet

11.4.5.4.12. pinfo.hi

higher Address of this Packet

11.4.5.4.13. pinfo.dl_src

Data Link Source Address of this Packet

11.4.5.4.14. pinfo.dl_dst

Data Link Destination Address of this Packet

11.4.5.4.15. pinfo.net_src

Network Layer Source Address of this Packet

11.4.5.4.16. pinfo.net_dst

Network Layer Destination Address of this Packet

11.4.5.4.17. pinfo.ptype

Type of Port of .src_port and .dst_port

11.4.5.4.18. pinfo.src_port

Source Port of this Packet

11.4.5.4.19. pinfo.dst_port

Source Address of this Packet

11.4.5.4.20. pinfo.ipproto

IP Protocol id

11.4.5.4.21. pinfo.circuit_id

For circuit based protocols

11.4.5.4.22. pinfo.match

Port/Data we are matching

11.4.5.4.23. pinfo.curr_proto

Which Protocol are we dissecting

11.4.5.4.24. pinfo.columns

Accesss to the packet list columns

11.4.5.4.25. pinfo.cols

Accesss to the packet list columns (equivalent to pinfo.columns)

11.4.5.4.26. pinfo.desegment_len

Estimated number of additional bytes required for completing the PDU

11.4.5.4.27. pinfo.desegment_offset

Offset in the tvbuff at which the dissector will continue processing when next called

11.4.5.4.28. pinfo.private_data

Access to private data

11.4.6.  Functions for writing dissectors

11.4.6.1. Dissector

A refererence to a dissector, used to call a dissector against a packet or a part of it.

11.4.6.1.1. Dissector.get(name)

Obtains a dissector reference by name

11.4.6.1.1.1. Arguments
name

The name of the dissector

11.4.6.1.1.2. Returns

The Dissector reference

11.4.6.1.2. dissector:call(tvb, pinfo, tree)

Calls a dissector against a given packet (or part of it)

11.4.6.1.2.1. Arguments
tvb

The buffer to dissect

pinfo

The packet info

tree

The tree on which to add the protocol items

11.4.6.2. DissectorTable

A table of subdissectors of a particular protocol (e.g. TCP subdissectors like http, smtp, sip are added to table "tcp.port"). Useful to add more dissectors to a table so that they appear in the Decode As... dialog.

11.4.6.2.1. DissectorTable.new(tablename, [uiname], [type], [base])

Creates a new DissectorTable for your dissector's use.

11.4.6.2.1.1. Arguments
tablename

The short name of the table.

uiname (optional)

The name of the table in the User Interface (defaults to the name given).

type (optional)

Either FT_UINT* or FT_STRING (defaults to FT_UINT32)

base (optional)

Either BASE_NONE, BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX or BASE_HEX_DEC (defaults to BASE_DEC)

11.4.6.2.1.2. Returns

The newly created DissectorTable

11.4.6.2.2. DissectorTable.get(tablename)

Obtain a reference to an existing dissector table.

11.4.6.2.2.1. Arguments
tablename

The short name of the table.

11.4.6.2.2.2. Returns

The DissectorTable

11.4.6.2.3. dissectortable:add(pattern, dissector)

Add a dissector to a table.

11.4.6.2.3.1. Arguments
pattern

The pattern to match (either an integer or a string depending on the table's type).

dissector

The dissector to add (either an Proto or a Dissector).

11.4.6.2.4. dissectortable:remove(pattern, dissector)

Remove a dissector from a table

11.4.6.2.4.1. Arguments
pattern

The pattern to match (either an integer or a string depending on the table's type).

dissector

The dissector to add (either an Proto or a Dissector).

11.4.6.2.5. dissectortable:try(pattern, tvb, pinfo, tree)

Try to call a dissector from a table

11.4.6.2.5.1. Arguments
pattern

The pattern to be matched (either an integer or a string depending on the table's type).

tvb

The buffer to dissect

pinfo

The packet info

tree

The tree on which to add the protocol items

11.4.6.2.6. dissectortable:get_dissector(pattern)

Try to obtain a dissector from a table.

11.4.6.2.6.1. Arguments
pattern

The pattern to be matched (either an integer or a string depending on the table's type).

11.4.6.2.6.2. Returns

The dissector handle if found

nil if not found

11.4.6.3. Pref

A preference of a Protocol.

11.4.6.3.1. Pref.bool(label, default, descr)

Creates a boolean preference to be added to a Protocol's prefs table.

11.4.6.3.1.1. Arguments
label

The Label (text in the right side of the preference input) for this preference

default

The default value for this preference

descr

A description of what this preference is

11.4.6.3.2. Pref.uint(label, default, descr)

Creates an (unsigned) integer preference to be added to a Protocol's prefs table.

11.4.6.3.2.1. Arguments
label

The Label (text in the right side of the preference input) for this preference

default

The default value for this preference

descr

A description of what this preference is

11.4.6.3.3. Pref.string(label, default, descr)

Creates a string preference to be added to a Protocol's prefs table.

11.4.6.3.3.1. Arguments
label

The Label (text in the right side of the preference input) for this preference

default

The default value for this preference

descr

A description of what this preference is

11.4.6.3.4. Pref.enum(label, default, descr, enum, radio)

Creates an enum preference to be added to a Protocol's prefs table.

11.4.6.3.4.1. Arguments
label

The Label (text in the right side of the preference input) for this preference

default

The default value for this preference

descr

A description of what this preference is

enum

A enum table

radio

Radio button (true) or Combobox (false)

11.4.6.3.5. Pref.range(label, default, descr, range, max)

Creates a range preference to be added to a Protocol's prefs table.

11.4.6.3.5.1. Arguments
label

The Label (text in the right side of the preference input) for this preference

default

The default value for this preference

descr

A description of what this preference is

range

The range

max

The maximum value

11.4.6.3.6. Pref.statictext(label, descr)

Creates a static text preference to be added to a Protocol's prefs table.

11.4.6.3.6.1. Arguments
label

The static text

descr

The static text description

11.4.6.4. Prefs

The table of preferences of a protocol

11.4.6.4.1. prefs:__newindex(name, pref)

Creates a new preference

11.4.6.4.1.1. Arguments
name

The abbreviation of this preference

pref

A valid but still unassigned Pref object

11.4.6.4.1.2. Errors

  • Unknow Pref type

11.4.6.4.2. prefs:__index(name)

Get the value of a preference setting

11.4.6.4.2.1. Arguments
name

The abbreviation of this preference

11.4.6.4.2.2. Returns

The current value of the preference

11.4.6.4.2.3. Errors

  • Unknow Pref type

11.4.6.5. Proto

A new protocol in wireshark. Protocols have more uses, the main one is to dissect a protocol. But they can be just dummies used to register preferences for other purposes.

11.4.6.5.1. Proto.new(name, desc)
11.4.6.5.1.1. Arguments
name

The name of the protocol

desc

A Long Text description of the protocol (usually lowercase)

11.4.6.5.1.2. Returns

The newly created protocol

11.4.6.5.2. proto.dissector

The protocol's dissector, a function you define

11.4.6.5.3. proto.fields

The Fields Table of this dissector

11.4.6.5.4. proto.prefs

The preferences of this dissector

11.4.6.5.5. proto.init

The init routine of this dissector, a function you define

11.4.6.5.6. proto.name

The name given to this dissector

11.4.6.6. ProtoField

A Protocol field (to be used when adding items to the dissection tree)

11.4.6.6.1. ProtoField.new(name, abbr, type, [voidstring], [base], [mask], [descr])

Creates a new field to be used in a protocol.

11.4.6.6.1.1. Arguments
name

Actual name of the field (the string that appears in the tree).

abbr

Filter name of the field (the string that is used in filters).

type

Field Type (FT_*).

voidstring (optional)

A VoidString object.

base (optional)

The representation BASE_*.

mask (optional)

The bitmask to be used.

descr (optional)

The description of the field.

11.4.6.6.1.2. Returns

The newly created ProtoField object

11.4.6.6.2. ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.2.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.2.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.3. ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.3.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.3.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.4. ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.4.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.4.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.5. ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.5.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.5.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.6. ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.6.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.6.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.7. ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.7.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.7.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.8. ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.8.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.8.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.9. ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.9.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.9.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.10. ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.10.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.10.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.11. ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [desc])
11.4.6.6.11.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.11.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.12. ProtoField.framenum(abbr, [name], [base], [valuestring], [mask], [desc])

A frame number (for hyperlinks between frames)

11.4.6.6.12.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

base (optional)

One of base.DEC, base.HEX or base.OCT

valuestring (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.12.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.13. ProtoField.bool(abbr, [name], [display], [string], [mask], [desc])
11.4.6.6.13.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

display (optional)

how wide the parent bitfield is (BASE_NONE is used for NULL-value)

string (optional)

A table containing the text that corresponds to the values

mask (optional)

Integer mask of this field

desc (optional)

Description of the field

11.4.6.6.13.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.14. ProtoField.ipv4(abbr, [name], [desc])
11.4.6.6.14.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.14.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.15. ProtoField.ipv6(abbr, [name], [desc])
11.4.6.6.15.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.15.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.16. ProtoField.ether(abbr, [name], [desc])
11.4.6.6.16.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.16.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.17. ProtoField.float(abbr, [name], [desc])
11.4.6.6.17.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.17.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.18. ProtoField.double(abbr, [name], [desc])
11.4.6.6.18.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.18.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.19. ProtoField.string(abbr, [name], [desc])
11.4.6.6.19.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.19.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.20. ProtoField.stringz(abbr, [name], [desc])
11.4.6.6.20.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.20.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.21. ProtoField.bytes(abbr, [name], [desc])
11.4.6.6.21.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.21.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.22. ProtoField.ubytes(abbr, [name], [desc])
11.4.6.6.22.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.22.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.23. ProtoField.guid(abbr, [name], [desc])
11.4.6.6.23.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.23.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.24. ProtoField.oid(abbr, [name], [desc])
11.4.6.6.24.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.24.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.25. ProtoField.bool(abbr, [name], [desc])
11.4.6.6.25.1. Arguments
abbr

Abbreviated name of the field (the string used in filters)

name (optional)

Actual name of the field (the string that appears in the tree)

desc (optional)

Description of the field

11.4.6.6.25.2. Returns

A protofield item to be added to a ProtoFieldArray

11.4.6.6.26. protofield:__tostring()

Returns a string with info about a protofield (for debugging purposes)

11.4.6.7. Non Method Functions

11.4.6.7.1. register_postdissector(proto)

Make a protocol (with a dissector) a postdissector. It will be called for every frame after dissection

11.4.6.7.1.1. Arguments
proto

the protocol to be used as postdissector

11.4.7.  Adding information to the dissection tree

11.4.7.1. TreeItem

TreeItems represent information in the packet-details pane. A root TreeItem is passed to dissectors as first argument.

11.4.7.1.1. treeitem:add()

Adds an child item to a given item, returning the child. tree_item:add([proto_field | proto], [tvbrange], [label], ...) if the proto_field represents a numeric value (int, uint or float) is to be treated as a Big Endian (network order) Value.

11.4.7.1.1.1. Returns

The child item

11.4.7.1.2. treeitem:add_le()

Adds (and returns) an child item to a given item, returning the child. tree_item:add([proto_field | proto], [tvbrange], [label], ...) if the proto_field represents a numeric value (int, uint or float) is to be treated as a Little Endian Value.

11.4.7.1.2.1. Returns

The child item

11.4.7.1.3. treeitem:set_text(text)

Sets the text of the label

11.4.7.1.3.1. Arguments
text

The text to be used.

11.4.7.1.4. treeitem:append_text(text)

Appends text to the label

11.4.7.1.4.1. Arguments
text

The text to be appended.

11.4.7.1.5. treeitem:set_expert_flags([group], [severity])

Sets the expert flags of the item.

11.4.7.1.5.1. Arguments
group (optional)

One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG

severity (optional)

One of PI_CHAT, PI_NOTE, PI_WARN, PI_ERROR

11.4.7.1.6. treeitem:add_expert_info([group], [severity], [text])

Sets the expert flags of the item and adds expert info to the packet.

11.4.7.1.6.1. Arguments
group (optional)

One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG

severity (optional)

One of PI_CHAT, PI_NOTE, PI_WARN, PI_ERROR

text (optional)

The text for the expert info

11.4.7.1.7. treeitem:set_generated()

Marks the TreeItem as a generated field (with data infered but not contained in the packet).

11.4.7.1.8. treeitem:set_hidden()

Should not be used

11.4.7.1.9. treeitem:set_len(len)

Set TreeItem's length inside tvb, after it has already been created.

11.4.7.1.9.1. Arguments
len

The length to be used.

11.4.8.  Functions for handling packet data

11.4.8.1. ByteArray

11.4.8.1.1. ByteArray.new([hexbytes])

Creates a ByteArray Object

11.4.8.1.1.1. Arguments
hexbytes (optional)

A string consisting of hexadecimal bytes like "00 B1 A2" or "1a2b3c4d"

11.4.8.1.1.2. Returns

The new ByteArray object.

11.4.8.1.2. bytearray:__concat(first, second)

Concatenate two ByteArrays

11.4.8.1.2.1. Arguments
first

First array

second

Second array

11.4.8.1.2.2. Returns

The new composite ByteArray.

11.4.8.1.2.3. Errors

  • Both arguments must be ByteArrays

11.4.8.1.3. bytearray:prepend(prepended)

Prepend a ByteArray to this ByteArray

11.4.8.1.3.1. Arguments
prepended

Array to be prepended

11.4.8.1.3.2. Errors

  • Both arguments must be ByteArrays

11.4.8.1.4. bytearray:append(appended)

Append a ByteArray to this ByteArray

11.4.8.1.4.1. Arguments
appended

Array to be appended

11.4.8.1.4.2. Errors

  • Both arguments must be ByteArrays

11.4.8.1.5. bytearray:set_size(size)

Sets the size of a ByteArray, either truncating it or filling it with zeros.

11.4.8.1.5.1. Arguments
size

New size of the array

11.4.8.1.5.2. Errors

  • ByteArray size must be non-negative

11.4.8.1.6. bytearray:set_index(index, value)

Sets the value of an index of a ByteArray.

11.4.8.1.6.1. Arguments
index

The position of the byte to be set

value

The char value to set [0-255]

11.4.8.1.7. bytearray:get_index(index)

Get the value of a byte in a ByteArray

11.4.8.1.7.1. Arguments
index

The position of the byte to get

11.4.8.1.7.2. Returns

The value [0-255] of the byte.

11.4.8.1.8. bytearray:len()

Obtain the length of a ByteArray

11.4.8.1.8.1. Returns

The length of the ByteArray.

11.4.8.1.9. bytearray:subset(offset, length)

Obtain a segment of a ByteArray

11.4.8.1.9.1. Arguments
offset

The position of the first byte

length

The length of the segment

11.4.8.1.9.2. Returns

A ByteArray contaning the requested segment.

A string contaning a representaion of the ByteArray.

11.4.8.2. Int

Int64 represents a 64 bit integer. Lua uses one single number representation which can be chosen at compile time and since it is often set to IEEE 754 double precision floating point, we cannot store a 64 bit integer with full precision. For details, see: http://lua-users.org/wiki/FloatingPoint

11.4.8.3. Tvb

A Tvb represents the packet's buffer. It is passed as an argument to listeners and dissectors, and can be used to extract information (via TvbRange) from the packet's data. Beware that Tvbs are usable only by the current listener or dissector call and are destroyed as soon as the listener/dissector returns, so references to them are unusable once the function has returned. To create a tvbrange the tvb must be called with offset and length as optional arguments ( the offset defaults to 0 and the length to tvb:len() )

11.4.8.3.1. Tvb.new_real(bytearray, name)

Creates a new Tvb from a bytearray (it gets added to the current frame too)

11.4.8.3.1.1. Arguments
bytearray

The data source for this Tvb.

name

The name to be given to the new data-source.

11.4.8.3.1.2. Returns

The created Tvb.

11.4.8.3.2. Tvb.tvb(range)

Creates a (sub)Tvb from using a TvbRange

11.4.8.3.2.1. Arguments
range

The TvbRange from which to create the new Tvb.

11.4.8.3.3. tvb:__tostring()

Convert the bytes of a Tvb into a string, to be used for debugging purposes as '...' will be appended in case the string is too long.

11.4.8.3.3.1. Returns

The string.

11.4.8.3.4. tvb:len()

Obtain the length of a TVB

11.4.8.3.4.1. Returns

The length of the Tvb.

11.4.8.3.5. tvb:offset()

Returns the raw offset (from the beginning of the source Tvb) of a sub Tvb.

11.4.8.3.5.1. Returns

The raw offset of the Tvb.

11.4.8.3.6. tvb:__call()

Equivalent to tvb:range(...)

11.4.8.3.7. wslua:__concat()

Concatenate two objects to a string

11.4.8.4. TvbRange

A TvbRange represents an usable range of a Tvb and is used to extract data from the Tvb that generated it TvbRanges are created by calling a tvb (e.g. tvb(offset,length)). If the TvbRange span is outside the Tvb's range the creation will cause a runtime error.

11.4.8.4.1. tvb:range([offset], [length])

Creates a tvbr from this Tvb. This is used also as the Tvb:__call() metamethod.

11.4.8.4.1.1. Arguments
offset (optional)

The offset (in octets) from the begining of the Tvb. Defaults to 0.

length (optional)

The length (in octets) of the range. Defaults to until the end of the Tvb.

11.4.8.4.1.2. Returns

The TvbRange

11.4.8.4.2. tvbrange:uint()

Get a Big Endian (network order) unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long.

11.4.8.4.2.1. Returns

The unsigned integer value

11.4.8.4.3. tvbrange:le_uint()

Get a Little Endian unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long.

11.4.8.4.3.1. Returns

The unsigned integer value

11.4.8.4.4. tvbrange:uint64()

Get a Big Endian (network order) unsigned 64 bit integer from a TvbRange. The range must be 1-8 octets long.

11.4.8.4.5. tvbrange:le_uint64()

Get a Little Endian unsigned 64 bit integer from a TvbRange. The range must be 1-8 octets long.

11.4.8.4.6. tvbrange:int()

Get a Big Endian (network order) signed integer from a TvbRange. The range must be 1, 2 or 4 octets long.

11.4.8.4.6.1. Returns

The signed integer value

11.4.8.4.7. tvbrange:le_int()

Get a Little Endian signed integer from a TvbRange. The range must be 1, 2 or 4 octets long.

11.4.8.4.7.1. Returns

The signed integer value

11.4.8.4.8. tvbrange:int64()

Get a Big Endian (network order) signed 64 bit integer from a TvbRange. The range must be 1-8 octets long.

11.4.8.4.9. tvbrange:le_int64()

Get a Little Endian signed 64 bit integer from a TvbRange. The range must be 1-8 octets long.

11.4.8.4.10. tvbrange:float()

Get a Big Endian (network order) floating point number from a TvbRange. The range must be 4 or 8 octets long.

11.4.8.4.10.1. Returns

The floating point value

11.4.8.4.11. tvbrange:le_float()

Get a Little Endian floating point number from a TvbRange. The range must be 4 or 8 octets long.

11.4.8.4.11.1. Returns

The floating point value

11.4.8.4.12. tvbrange:ipv4()

Get an IPv4 Address from a TvbRange.

11.4.8.4.12.1. Returns

The IPv4 Address

11.4.8.4.13. tvbrange:le_ipv4()

Get an Little Endian IPv4 Address from a TvbRange.

11.4.8.4.13.1. Returns

The IPv4 Address

11.4.8.4.14. tvbrange:ether()

Get an Ethernet Address from a TvbRange.

11.4.8.4.14.1. Returns

The Ethernet Address

11.4.8.4.14.2. Errors

  • The range must be 6 bytes long

11.4.8.4.15. tvbrange:string()

Obtain a string from a TvbRange

11.4.8.4.15.1. Returns

The string

11.4.8.4.16. tvbrange:stringz()

Obtain a zero terminated string from a TvbRange

11.4.8.4.16.1. Returns

The zero terminated string

11.4.8.4.17. tvbrange:bytes()

Obtain a ByteArray

11.4.8.4.17.1. Returns

The ByteArray

11.4.8.4.18. tvbrange:bitfield([position], [length])

Get a bitfield from a TvbRange.

11.4.8.4.18.1. Arguments
position (optional)

The bit offset from the begining of the TvbRange. Defaults to 0.

length (optional)

The length (in bits) of the field. Defaults to 1.

11.4.8.4.18.2. Returns

The bitfield value

11.4.8.4.19. tvbrange:range([offset], [length])

Creates a sub-TvbRange from this TvbRange. This is used also as the TvbRange:__call() metamethod.

11.4.8.4.19.1. Arguments
offset (optional)

The offset (in octets) from the begining of the TvbRange. Defaults to 0.

length (optional)

The length (in octets) of the range. Defaults to until the end of the TvbRange.

11.4.8.4.19.2. Returns

The TvbRange

11.4.8.4.20. tvbrange:len()

Obtain the length of a TvbRange

11.4.8.4.21. tvbrange:offset()

Obtain the offset in a TvbRange

11.4.8.4.22. tvbrange:__tostring()

Converts the TvbRange into a string. As the string gets truncated you should use this only for debugging purposes or if what you want is to have a truncated string in the format 67:89:AB:...

11.4.8.5. UInt

UInt64 represents a 64 bit unsigned integer.

11.4.9.  Utility Functions

11.4.9.1. Dir

A Directory

11.4.9.1.1. Dir.open(pathname, [extension])

Usage: for filename in Dir.open(path) do ... end

11.4.9.1.1.1. Arguments
pathname

The pathname of the directory

extension (optional)

If given, only file with this extension will be returned

11.4.9.1.1.2. Returns

the Dir object

11.4.9.1.2. dir:__call()

At every invocation will return one file (nil when done)

11.4.9.1.3. dir:close()

Closes the directory

11.4.9.2. Non Method Functions

11.4.9.2.1. get_version()

Get Wireshark version

11.4.9.2.1.1. Returns

version string

11.4.9.2.2. format_date(timestamp)

Formats an absolute timestamp into a human readable date

11.4.9.2.2.1. Arguments
timestamp

A timestamp value to convert.

11.4.9.2.2.2. Returns

A string with the formated date

11.4.9.2.3. format_time(timestamp)

Formats a relative timestamp in a human readable form

11.4.9.2.3.1. Arguments
timestamp

A timestamp value to convert

11.4.9.2.3.2. Returns

A string with the formated time

11.4.9.2.4. report_failure(text)

Reports a failure to the user

11.4.9.2.4.1. Arguments
text

Message

11.4.9.2.5. critical(...)

Will add a log entry with critical severity

11.4.9.2.5.1. Arguments
...

objects to be printed

11.4.9.2.6. warn(...)

Will add a log entry with warn severity

11.4.9.2.6.1. Arguments
...

objects to be printed

11.4.9.2.7. message(...)

Will add a log entry with message severity

11.4.9.2.7.1. Arguments
...

objects to be printed

11.4.9.2.8. info(...)

Will add a log entry with info severity

11.4.9.2.8.1. Arguments
...

objects to be printed

11.4.9.2.9. debug(...)

Will add a log entry with debug severity

11.4.9.2.9.1. Arguments
...

objects to be printed

11.4.9.2.10. loadfile(filename)

Lua's loadfile() has been modified so that if a file does not exist in the current directory it will look for it in wireshark's user and system directories

11.4.9.2.10.1. Arguments
filename

Name of the file to be loaded

11.4.9.2.11. dofile(filename)

Lua's dofile() has been modified so that if a file does not exist in the current directory it will look for it in wireshark's user and system directories

11.4.9.2.11.1. Arguments
filename

Name of the file to be run

11.4.9.2.12. persconffile_path([filename])
11.4.9.2.12.1. Arguments
filename (optional)

A filename

11.4.9.2.12.2. Returns

The full pathname for a file in the personal configuration directory

11.4.9.2.13. datafile_path([filename])
11.4.9.2.13.1. Arguments
filename (optional)

A filename

11.4.9.2.13.2. Returns

The full pathname for a file in wireshark's configuration directory

11.4.9.2.14. register_stat_cmd_arg(argument, [action])

Register a function to handle a -z option

11.4.9.2.14.1. Arguments
argument

Argument

action (optional)

Action

Prev Up Next
11.3. Example of Listener written in Lua Home Appendix A. Files and Folders