10.4. Wireshark's Lua API Reference Manual

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

10.4.1.  Saving capture files

10.4.1.1. Dumper

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

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

10.4.1.1.1.2. Returns

The newly created Dumper object

10.4.1.1.1.3. Errors
  • not every filetype handles every encap

10.4.1.1.2. dumper:close()

Closes a dumper

10.4.1.1.2.1. Errors
  • Cannot operate on a closed dumper

10.4.1.1.3. dumper:flush()

Writes all unsaved data of a dumper to the disk.

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

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

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

10.4.1.1.5. dumper:new_for_current([filetype])

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

10.4.1.1.5.1. Arguments
filetype (optional)

The file type. Defaults to pcap.

10.4.1.1.5.2. Returns

The newly created Dumper Object

10.4.1.1.5.3. Errors
  • cannot be used outside a tap or a dissector

10.4.1.1.6. dumper:dump_current()

Dumps the current packet as it is.

10.4.1.1.6.1. Errors
  • cannot be used outside a tap or a dissector

10.4.1.2. PseudoHeader

A pseudoheader to be used to save captured frames.

10.4.1.2.1. PseudoHeader.none()

Creates a "no" pseudoheader.

10.4.1.2.1.1. Returns

A null pseudoheader

10.4.1.2.2. PseudoHeader.eth([fcslen])

Creates an ethernet pseudoheader

10.4.1.2.2.1. Arguments
fcslen (optional)

the fcs length

10.4.1.2.2.2. Returns

The ethernet pseudoheader

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

Creates an ATM pseudoheader

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

10.4.1.2.3.2. Returns

The ATM pseudoheader

10.4.1.2.4. PseudoHeader.mtp2()

Creates an MTP2 PseudoHeader

10.4.1.2.4.1. Returns

The MTP2 pseudoheader

10.4.2.  Obtaining dissection data

10.4.2.1. Field

A Field extractor to to obtain field values.

10.4.2.1.1. Field.new(fieldname)

Create a Field extractor

10.4.2.1.1.1. Arguments
fieldname

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

10.4.2.1.1.2. Returns

The field extractor

10.4.2.1.1.3. Errors
  • a Field extractor must be defined before Taps or Dissectors get called

10.4.2.1.2. field:__call()

obtain all values (see FieldInfo) for this field.

10.4.2.1.2.1. Returns

All the values of this field

10.4.2.1.2.2. Errors
  • fields cannot be used outside dissectors or taps

10.4.2.2. FieldInfo

An extracted Field

10.4.2.2.1. fieldinfo:__len()

Obtain the Length of the field

10.4.2.2.2. fieldinfo:__unm()

Obtain the Offset of the field

10.4.2.2.3. fieldinfo:__call()

Obtain the Value of the field

10.4.2.2.4. fieldinfo:__tostring()

the string representation of the field

10.4.2.2.5. fieldinfo:__eq()

checks whether lhs is within rhs

10.4.2.2.5.1. Errors
  • data source must be the same for both fields

10.4.2.2.6. fieldinfo:__le()

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

10.4.2.2.7. fieldinfo:__lt()

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

10.4.2.2.7.1. Errors
  • data source must be the same for both fields

10.4.2.2.8. fieldinfo.name

The name of this field

10.4.2.2.9. fieldinfo.label

The string representing this field

10.4.2.2.10. fieldinfo.value

The value of this field

10.4.2.2.11. fieldinfo.len

The length of this field

10.4.2.2.12. fieldinfo.offset

The offset of this field

10.4.2.3. Non Method Functions

10.4.2.3.1. all_field_infos()

obtain all fields from the current tree

10.4.2.3.1.1. Errors
  • Cannot be called outside a listener or dissector

10.4.3.  GUI support

10.4.3.1. TextWindow

Manages a text window.

10.4.3.1.1. TextWindow.new([title])

Creates a new TextWindow.

10.4.3.1.1.1. Arguments
title (optional)

Title of the new window.

10.4.3.1.1.2. Returns

The newly created TextWindow object.

10.4.3.1.2. textwindow:set_atclose(action)

Set the function that will be called when the window closes

10.4.3.1.2.1. Arguments
action

A function to be executed when the user closes the window

10.4.3.1.2.2. Returns

The TextWindow object.

10.4.3.1.2.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.3. textwindow:set(text)

Sets the text.

10.4.3.1.3.1. Arguments
text

The text to be used.

10.4.3.1.3.2. Returns

The TextWindow object.

10.4.3.1.3.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.4. textwindow:append(text)

Appends text

10.4.3.1.4.1. Arguments
text

The text to be appended

10.4.3.1.4.2. Returns

The TextWindow object.

10.4.3.1.4.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.5. textwindow:prepend(text)

Prepends text

10.4.3.1.5.1. Arguments
text

The text to be appended

10.4.3.1.5.2. Returns

The TextWindow object.

10.4.3.1.5.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.6. textwindow:clear()

Errases all text in the window.

10.4.3.1.6.1. Returns

The TextWindow object.

10.4.3.1.6.2. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.7. textwindow:get_text()

Get the text of the window

10.4.3.1.7.1. Returns

The TextWindow's text.

10.4.3.1.7.2. Errors
  • cannot be called for something not a TextWindow

  • cannot be called for something not a TextWindow

10.4.3.1.8. textwindow:set_editable([editable])

Make this window editable

10.4.3.1.8.1. Arguments
editable (optional)

A boolean flag, defaults to true

10.4.3.1.8.2. Returns

The TextWindow object.

10.4.3.1.8.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.1.9. textwindow:add_button(label, function)
10.4.3.1.9.1. Arguments
label

The label of the button

function

The function to be called when clicked

10.4.3.1.9.2. Returns

The TextWindow object.

10.4.3.1.9.3. Errors
  • cannot be called for something not a TextWindow

10.4.3.2. Non Method Functions

10.4.3.2.1. gui_enabled()

Checks whether the GUI facility is enabled.

10.4.3.2.1.1. Returns

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

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

Register a menu item in one of the main menus.

10.4.3.2.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 (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 (Statistics, third section), MENU_ANALYZE (Analyze), MENU_ANALYZE_CONVERSATION (Analyze/Conversation Filter), MENU_TOOLS (Tools). (number)

10.4.3.2.3. new_dialog(title, action, ...)

Pops up a new dialog

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

10.4.3.2.3.2. Errors
  • at least one field required

  • all fields must be strings

10.4.3.2.4. retap_packets()

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

10.4.3.2.5. copy_to_clipboard(text)

copy a string into the clipboard

10.4.3.2.5.1. Arguments
text

The string to be copied into the clipboard.

10.4.3.2.6. open_capture_file(filename, filter)

open and display a capture file

10.4.3.2.6.1. Arguments
filename

The name of the file to be opened.

filter

A filter to be applied as the file gets opened.

10.4.3.2.7. set_filter(text)

set the main filter text

10.4.3.2.7.1. Arguments
text

The filter's text.

10.4.3.2.8. apply_filter()

apply the filter in the main filter box

10.4.3.2.9. reload()

reload the current capture file

10.4.3.2.10. browser_open_url(url)

open an url in a browser

10.4.3.2.10.1. Arguments
url

The url.

10.4.3.2.11. browser_open_data_file(filename)

open an file in a browser

10.4.3.2.11.1. Arguments
filename

The url.

10.4.4.  Post-dissection packet analysis

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

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

Creates a new Listener listener

10.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)

10.4.4.1.1.2. Returns

The newly created Listener listener object

10.4.4.1.1.3. Errors
  • tap registration error

10.4.4.1.2. listener:remove()

Removes a tap listener

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

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

10.4.4.1.5. listener.reset

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

10.4.5.  Obtaining packet information

10.4.5.1. Address

Represents an address

10.4.5.1.1. Address.ip(hostname)

Creates an Address Object representing an IP address.

10.4.5.1.1.1. Arguments
hostname

The address or name of the IP host.

10.4.5.1.1.2. Returns

the Address object

10.4.5.1.2. address:__tostring()
10.4.5.1.2.1. Returns

The string representing the address.

10.4.5.1.3. address:__eq()

compares two Addresses

10.4.5.1.4. address:__le()

compares two Addresses

10.4.5.1.5. address:__lt()

compares two Addresses

10.4.5.2. Column

A Column in the packet list

10.4.5.2.1. column:__tostring()
10.4.5.2.1.1. Returns

A string representing the column

10.4.5.2.2. column:clear()

Clears a Column

10.4.5.2.3. column:set(text)

Sets the text of a Column

10.4.5.2.3.1. Arguments
text

The text to which to set the Column

10.4.5.2.4. column:append(text)

Appends text to a Column

10.4.5.2.4.1. Arguments
text

The text to append to the Column

10.4.5.2.5. column:preppend(text)

Prepends text to a Column

10.4.5.2.5.1. Arguments
text

The text to prepend to the Column

10.4.5.3. Columns

The Columns of the packet list.

10.4.5.3.1. columns:__tostring()
10.4.5.3.1.1. Returns

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

10.4.5.3.2. columns:__newindex(column, text)

Sets the text of a specific column

10.4.5.3.2.1. Arguments
column

the name of the column to set

text

the text for the column

10.4.5.4. Pinfo

Packet information

10.4.5.4.1. pinfo.number

The number of this packet in the current file

10.4.5.4.2. pinfo.len

The length of the frame

10.4.5.4.3. pinfo.caplen

The captured length of the frame

10.4.5.4.4. pinfo.abs_ts

When the packet was captured

10.4.5.4.5. pinfo.rel_ts

Number of seconds passed since beginning of capture

10.4.5.4.6. pinfo.delta_ts

Number of seconds passed since the last captured packet

10.4.5.4.7. pinfo.delta_dis_ts

Number of seconds passed since the last displayed packet

10.4.5.4.8. pinfo.visited

Whether this packet hass been already visited

10.4.5.4.9. pinfo.src

Source Address of this Packet

10.4.5.4.10. pinfo.dst

Destination Address of this Packet

10.4.5.4.11. pinfo.lo

lower Address of this Packet

10.4.5.4.12. pinfo.hi

higher Address of this Packet

10.4.5.4.13. pinfo.dl_src

Data Link Source Address of this Packet

10.4.5.4.14. pinfo.dl_dst

Data Link Destination Address of this Packet

10.4.5.4.15. pinfo.net_src

Network Layer Source Address of this Packet

10.4.5.4.16. pinfo.net_dst

Network Layer Destination Address of this Packet

10.4.5.4.17. pinfo.ptype

Type of Port of .src_port and .dst_port

10.4.5.4.18. pinfo.src_port

Source Port of this Packet

10.4.5.4.19. pinfo.dst_port

Source Address of this Packet

10.4.5.4.20. pinfo.ipproto

IP Protocol id

10.4.5.4.21. pinfo.circuit_id

For circuit based protocols

10.4.5.4.22. pinfo.match

Port/Data we are matching

10.4.5.4.23. pinfo.curr_proto

Which Protocol are we dissecting

10.4.5.4.24. pinfo.columns

Accesss to the packet list columns

10.4.5.4.25. pinfo.cols

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

10.4.6.  Functions for writing dissectors

10.4.6.1. Dissector

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

10.4.6.1.1. Dissector.get(name)

* Obtains a dissector reference by name

10.4.6.1.1.1. Arguments
name

The name of the dissector

10.4.6.1.1.2. Returns

The Dissector reference

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

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

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

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

10.4.6.2.1. DissectorTable.new(tablename, [uiname], [type])

Creates a new DissectorTable for your dissector's use .

10.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)

10.4.6.2.1.2. Returns

The newly created DissectorTable

10.4.6.2.2. DissectorTable.get(tablename)

Obtain a reference to an existing dissector table.

10.4.6.2.2.1. Arguments
tablename

The short name of the table.

10.4.6.2.2.2. Returns

The DissectorTable

10.4.6.2.3. dissectortable:add(pattern, dissector)

Add a dissector to a table.

10.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).

10.4.6.2.4. dissectortable:remove(pattern, dissector)

Remove a dissector from a table

10.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).

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

Try to call a dissector from a table

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

10.4.6.2.6. dissectortable:get_dissector(pattern)

Try to obtain a dissector from a table.

10.4.6.2.6.1. Arguments
pattern

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

10.4.6.2.6.2. Returns

The dissector handle if found

nil if not found

10.4.6.3. Pref

A preference of a Protocol.

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

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

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

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

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

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

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

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

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

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

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

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

enum

radio

radio_button or combobox

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

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

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

10.4.6.3.6. Pref.stext(label, text)

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

10.4.6.3.6.1. Arguments
label

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

text

The static text

10.4.6.4. Prefs

The table of preferences of a protocol

10.4.6.4.1. prefs:__newindex(name, pref)

creates a new preference

10.4.6.4.1.1. Arguments
name

The abbreviation of this preference

pref

A valid but still unassigned Pref object

10.4.6.4.1.2. Errors
  • unknow Pref type

10.4.6.4.2. prefs:__index(name)

get the value of a preference setting

10.4.6.4.2.1. Arguments
name

The abbreviation of this preference

10.4.6.4.2.2. Returns

the current value of the preference

10.4.6.4.2.3. Errors
  • unknow Pref type

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

10.4.6.5.1. Proto.new(name, desc)
10.4.6.5.1.1. Arguments
name

The name of the protocol

desc

A Long Text description of the protocol (usually lowercase)

10.4.6.5.1.2. Returns

The newly created protocol

10.4.6.5.2. proto.dissector

the protocol's dissector, a function you define

10.4.6.5.3. proto.fields

the Fields Table of this dissector

10.4.6.5.4. proto.get_prefs

the preferences of this dissector

10.4.6.5.5. proto.init

the init routine of this dissector, a function you define

10.4.6.5.6. proto.name

the name given to this dissector

10.4.6.6. ProtoField

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

10.4.6.6.1. ProtoField.new(name, abbr, type, [valuestring], [base], [mask], [descr])

Creates a new field to be used in a protocol.

10.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_*).

valuestring (optional)

a ValueString object.

base (optional)

The representation BASE_*.

mask (optional)

the bitmask to be used.

descr (optional)

The description of the field.

10.4.6.6.1.2. Returns

The newly created ProtoField object

10.4.6.6.2. ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.2.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.3. ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.3.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.4. ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.4.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.5. ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.5.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.6. ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.6.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.7. ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.7.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.8. ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.8.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.9. ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.9.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.10. ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.10.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.11. ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [desc])
10.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

10.4.6.6.11.2. Returns

a protofield item to be added to a ProtoFieldArray

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

a frame number (for hyperlinks between frames)

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

10.4.6.6.12.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.13. ProtoField.ipv4(abbr, [name], [desc])
10.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)

desc (optional)

description of the field

10.4.6.6.13.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.14. ProtoField.ipv6(abbr, [name], [desc])
10.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

10.4.6.6.14.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.15. ProtoField.ether(abbr, [name], [desc])
10.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

10.4.6.6.15.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.16. ProtoField.float(abbr, [name], [desc])
10.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

10.4.6.6.16.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.17. ProtoField.double(abbr, [name], [desc])
10.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

10.4.6.6.17.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.18. ProtoField.string(abbr, [name], [desc])
10.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

10.4.6.6.18.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.19. ProtoField.strigz(abbr, [name], [desc])
10.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

10.4.6.6.19.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.20. ProtoField.bytes(abbr, [name], [desc])
10.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

10.4.6.6.20.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.21. ProtoField.ubytes(abbr, [name], [desc])
10.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

10.4.6.6.21.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.22. ProtoField.guid(abbr, [name], [desc])
10.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

10.4.6.6.22.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.23. ProtoField.oid(abbr, [name], [desc])
10.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

10.4.6.6.23.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.6.24. ProtoField.bool(abbr, [name], [desc])
10.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

10.4.6.6.24.2. Returns

a protofield item to be added to a ProtoFieldArray

10.4.6.7. Non Method Functions

10.4.6.7.1. register_postdissector(proto)

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

10.4.6.7.1.1. Arguments
proto

the protocol to be used as postdissector

10.4.7.  Adding information to the dissection tree

10.4.7.1. TreeItem

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

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

10.4.7.1.1.1. Returns

The child item

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

10.4.7.1.2.1. Returns

The child item

10.4.7.1.3. treeitem:set_text(text)

sets the text of the label

10.4.7.1.3.1. Arguments
text

The text to be used.

10.4.7.1.4. treeitem:append_text(text)

appends text to the label

10.4.7.1.4.1. Arguments
text

The text to be appended.

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

Sets the expert flags of the item.

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

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

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

10.4.7.1.7. treeitem:set_generated()

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

10.4.7.1.8. treeitem:set_hidden()

should not be used

10.4.8.  Functions for handling packet data

10.4.8.1. ByteArray

10.4.8.1.1. ByteArray.new([hexbytes])

creates a ByteArray Object

10.4.8.1.1.1. Arguments
hexbytes (optional)

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

10.4.8.1.1.2. Returns

The new ByteArray object.

10.4.8.1.2. bytearray:__concat(first, second)

concatenate two ByteArrays

10.4.8.1.2.1. Arguments
first

first array

second

second array

10.4.8.1.2.2. Returns

The new composite ByteArray.

10.4.8.1.2.3. Errors
  • both arguments must be ByteArrays

10.4.8.1.3. bytearray:prepend(prepended)

prepend a ByteArray to this ByteArray

10.4.8.1.3.1. Arguments
prepended

array to be prepended

10.4.8.1.3.2. Errors
  • both arguments must be ByteArrays

10.4.8.1.4. bytearray:append(appended)

append a ByteArray to this ByteArray

10.4.8.1.4.1. Arguments
appended

array to be appended

10.4.8.1.4.2. Errors
  • both arguments must be ByteArrays

10.4.8.1.5. bytearray:set_size(size)

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

10.4.8.1.5.1. Arguments
size

new size of the array

10.4.8.1.6. bytearray:set_index(index, value)

sets the value of an index of a ByteArray.

10.4.8.1.6.1. Arguments
index

the position of the byte to be set

value

the char value to set [0-255]

10.4.8.1.7. bytearray:get_index(index)

get the value of a byte in a ByteArray

10.4.8.1.7.1. Arguments
index

the position of the byte to be set

10.4.8.1.7.2. Returns

The value [0-255] of the byte.

10.4.8.1.8. bytearray:len()

obtain the length of a ByteArray

10.4.8.1.8.1. Returns

The length of the ByteArray.

10.4.8.1.9. bytearray:subset(offset, length)

obtain a segment of a ByteArray

10.4.8.1.9.1. Arguments
offset

the position of the first byte

length

the length of the segment

10.4.8.1.9.2. Returns

a ByteArray contaning the requested segment.

a string contaning a representaion of the ByteArray.

10.4.8.2. 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() )

10.4.8.2.1. Tvb.new_real(bytearray, name)

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

10.4.8.2.1.1. Arguments
bytearray

The data source for this Tvb.

name

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

10.4.8.2.1.2. Returns

the created Tvb.

10.4.8.2.2. Tvb.tvb(range)

creates a (sub)Tvb from using a TvbRange

10.4.8.2.2.1. Arguments
range

the TvbRange from which to create the new Tvb.

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

10.4.8.2.3.1. Returns

the string.

10.4.8.2.4. tvb:len()

obtain the length of a TVB

10.4.8.2.4.1. Returns

the length of the Tvb.

10.4.8.2.5. tvb:offset()

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

10.4.8.2.5.1. Returns

the raw offset of the Tvb.

10.4.8.2.6. tvb:__call()

equivalent to tvb:range(...)

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

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

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

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

10.4.8.3.1.2. Returns

the TvbRange

10.4.8.3.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. There's no support yet for 64 bit integers

10.4.8.3.2.1. Returns

the unsigned integer value

10.4.8.3.3. tvbrange:le_uint()

get a Little Endian unsigned integer from a TvbRange. The range must be 1, 2, 3 or 4 octets long. There's no support yet for 64 bit integers

10.4.8.3.3.1. Returns

the unsigned integer value

10.4.8.3.4. tvbrange:float()

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

10.4.8.3.4.1. Returns

the flaoting point value

10.4.8.3.5. tvbrange:le_float()

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

10.4.8.3.5.1. Returns

the flaoting point value

10.4.8.3.6. tvbrange:ipv4()

get an IPv4 Address from a TvbRange.

10.4.8.3.6.1. Returns

the IPv4 Address

10.4.8.3.7. tvbrange:le_ipv4()

get an Little Endian IPv4 Address from a TvbRange.

10.4.8.3.7.1. Returns

the IPv4 Address

10.4.8.3.8. tvbrange:ether()

get an Ethernet Address from a TvbRange.

10.4.8.3.8.1. Returns

the Ethernet Address

10.4.8.3.8.2. Errors
  • The range must be 6 bytes long

10.4.8.3.9. tvbrange:string()

obtain a string from a TvbRange

10.4.8.3.9.1. Returns

the string

10.4.8.3.10. tvbrange:bytes()

obtain a ByteArray

10.4.8.3.10.1. Returns

the ByteArray

10.4.8.3.11. 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:...

10.4.8.3.12. tvbrange.tvb

The Tvb from which this TvbRange was generated

10.4.8.3.13. tvbrange.len

The length (in octets) of this TvbRange

10.4.8.3.14. tvbrange.offset

The offset (in octets) of this TvbRange

10.4.9.  Utility Functions

10.4.9.1. Dir

A Directory

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

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

10.4.9.1.1.1. Arguments
pathname

the pathname of the directory

extension (optional)

if given, only file with this extension will be returned

10.4.9.1.1.2. Returns

the Dir object

10.4.9.1.2. dir:__call()

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

10.4.9.1.3. dir:close()

closes the directory

10.4.9.2. Non Method Functions

10.4.9.2.1. format_date(timestamp)

Formats an absolute timestamp into a human readable date

10.4.9.2.1.1. Arguments
timestamp

A timestamp value to convert.

10.4.9.2.1.2. Returns

a string with the formated date

10.4.9.2.2. format_time(timestamp)

Formats a relative timestamp in a human readable form

10.4.9.2.2.1. Arguments
timestamp

a timestamp value to convert

10.4.9.2.2.2. Returns

a string with the formated time

10.4.9.2.3. report_failure(text)

reports a failure to the user

10.4.9.2.3.1. Arguments
text

message

10.4.9.2.4. critical(...)

Will add a log entry with critical severity

10.4.9.2.4.1. Arguments
...

objects to be printed

10.4.9.2.5. warn(...)

Will add a log entry with warn severity

10.4.9.2.5.1. Arguments
...

objects to be printed

10.4.9.2.6. message(...)

Will add a log entry with message severity

10.4.9.2.6.1. Arguments
...

objects to be printed

10.4.9.2.7. info(...)

Will add a log entry with info severity

10.4.9.2.7.1. Arguments
...

objects to be printed

10.4.9.2.8. debug(...)

Will add a log entry with debug severity

10.4.9.2.8.1. Arguments
...

objects to be printed

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

10.4.9.2.9.1. Arguments
filename

name of the file to be loaded

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

10.4.9.2.10.1. Arguments
filename

name of the file to be run

10.4.9.2.11. persconffile_path([filename])
10.4.9.2.11.1. Arguments
filename (optional)

a filename

10.4.9.2.11.2. Returns

the full pathname for a file in the personal configuration directory

10.4.9.2.12. datafile_path([filename])
10.4.9.2.12.1. Arguments
filename (optional)

a filename

10.4.9.2.12.2. Returns

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

10.4.9.2.13. register_stat_cmd_arg(argument, [action])

Register a function to handle a -z option

10.4.9.2.13.1. Arguments
argument

action (optional)