Wireshark's LUA API Reference Manual


Table of Contents

1. saving capture files
Dumper
Dumper.new(filename, [filetype], [encap])
dumper:close()
dumper:flush()
dumper:dump(timestamp, pseudoheader, bytearray)
dumper:new_for_current([filetype])
dumper:dump_current()
PseudoHeader
PseudoHeader.none()
PseudoHeader.eth([fcslen])
PseudoHeader.atm([aal], [vpi], [vci], [channel], [cells], [aal5u2u], [aal5len])
PseudoHeader.mtp2()
2. obtaining dissection data
Field
Field.new(fieldname)
field:__call()
FieldInfo
fieldinfo:__len()
fieldinfo:__unm()
fieldinfo:__call()
fieldinfo:__tostring()
fieldinfo:__eq()
fieldinfo:__le()
fieldinfo:__lt()
Non Method Functions
all_field_infos()
3. GUI support
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, ...)
retap_packets()
copy_to_clipboard(text)
open_capture_file(filename, filter)
set_filter(text)
apply_filter()
reload()
browser_open_url(url)
browser_open_data_file(filename)
4. post-dissection packet analysis
Listener
Listener.new([tap], [filter])
listener:remove()
listener.packet
listener.draw
listener.reset
5. obtaining packet information
Address
Address.ip(hostname)
address:__tostring()
address:__eq()
address:__le()
address:__lt()
Column
column:__tostring()
column:clear()
column:set(text)
column:append(text)
column:preppend(text)
Columns
columns:__tostring()
columns:__newindex(column, text)
Pinfo
pinfo.number
pinfo.len
pinfo.caplen
pinfo.abs_ts
pinfo.rel_ts
pinfo.delta_ts
pinfo.visited
pinfo.src
pinfo.dst
pinfo.lo
pinfo.hi
pinfo.dl_src
pinfo.dl_dst
pinfo.net_src
pinfo.net_dst
pinfo.ptype
pinfo.src_port
pinfo.dst_port
pinfo.ipproto
pinfo.circuit_id
pinfo.match
pinfo.curr_proto
pinfo.columns
pinfo.cols
6. functions for writing dissectors
Dissector
Dissector.get(name)
dissector:call(tvb, pinfo, tree)
DissectorTable
DissectorTable.new(tablename, [uiname], [type])
DissectorTable.get(tablename)
dissectortable:add(pattern, dissector)
dissectortable:remove(pattern, dissector)
dissectortable:try(pattern, tvb, pinfo, tree)
dissectortable:get_dissector(pattern)
Pref
Pref.bool(label, default, descr)
Pref.uint(label, default, descr)
Pref.string(label, default, descr)
Prefs
prefs:__newindex(name, pref)
prefs:__index(name)
Proto
Proto.new(name, desc)
proto.dissector
proto.fields
proto.get_prefs
proto.init
proto.name
ProtoField
ProtoField.new(name, abbr, type, [valuestring], [base], [mask], [descr])
ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.framenum(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.ipv4(abbr, [name], [desc])
ProtoField.ipv6(abbr, [name], [desc])
ProtoField.ether(abbr, [name], [desc])
ProtoField.float(abbr, [name], [desc])
ProtoField.double(abbr, [name], [desc])
ProtoField.string(abbr, [name], [desc])
ProtoField.strigz(abbr, [name], [desc])
ProtoField.bytes(abbr, [name], [desc])
ProtoField.ubytes(abbr, [name], [desc])
ProtoField.guid(abbr, [name], [desc])
ProtoField.oid(abbr, [name], [desc])
ProtoField.bool(abbr, [name], [desc])
Non Method Functions
register_postdissector(proto)
7. adding information to the dissection tree
TreeItem
treeitem:add()
treeitem:add_le()
treeitem:set_text(text)
treeitem:append_text(text)
treeitem:set_expert_flags([group], [severity])
treeitem:add_expert_info([group], [severity], [text])
treeitem:set_generated()
treeitem:set_hidden()
8. functions for handling packet data
ByteArray
ByteArray.new([hexbytes])
bytearray:__concat(first, second)
bytearray:prepend(prepended)
bytearray:append(appended)
bytearray:set_size(size)
bytearray:set_index(index, value)
bytearray:get_index(index)
bytearray:len()
bytearray:subset(offset, length)
Tvb
Tvb.new_real(bytearray, name)
Tvb.new_subset(range)
tvb:__tostring()
tvb:len()
tvb:offset()
tvb:__call()
TvbRange
tvb:range([offset], [length])
tvbrange:get_uint()
tvbrange:get_le_uint()
tvbrange:get_float()
tvbrange:get_le_float()
tvbrange:get_ipv4()
tvbrange:get_ether()
tvbrange:get_string()
tvbrange:get_bytes()
tvbrange:__tostring()
tvbrange.tvb
tvbrange.len
tvbrange.offset
9. Utility Functions
Dir
Dir.open(pathname, [extension])
dir:__call()
dir:close()
Non Method Functions
format_date(timestamp)
format_time(timestamp)
report_failure(text)
critical(...)
warn(...)
message(...)
info(...)
debug(...)
loadfile(filename)
dofile(filename)
persconffile_path([filename])
datafile_path([filename])
register_stat_cmd_arg(argument, [action])

Chapter 1.  saving capture files

Dumper

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

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

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

Returns

The newly created Dumper object

Errors

  • not every filetype handles every encap

dumper:close()

Closes a dumper

Errors

  • Cannot operate on a closed dumper

dumper:flush()

Writes all unsaved data of a dumper to the disk.

dumper:dump(timestamp, pseudoheader, bytearray)

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

Arguments

timestamp

The absolute timestamp the packet will have

pseudoheader

The Pseudoheader to use.

bytearray

the data to be saved

dumper:new_for_current([filetype])

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

Arguments

filetype (optional)

The file type. Defaults to pcap.

Returns

The newly created Dumper Object

Errors

  • cannot be used outside a tap or a dissector

dumper:dump_current()

Dumps the current packet as it is.

Errors

  • cannot be used outside a tap or a dissector

PseudoHeader

A pseudoheader to be used to save captured frames.

PseudoHeader.none()

Creates a "no" pseudoheader.

Returns

A null pseudoheader

PseudoHeader.eth([fcslen])

Creates an ethernet pseudoheader

Arguments

fcslen (optional)

the fcs lenght

Returns

The ethernet pseudoheader

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

Creates an ATM pseudoheader

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

Returns

The ATM pseudoheader

PseudoHeader.mtp2()

Creates an MTP2 PseudoHeader

Returns

The MTP2 pseudoheader

Chapter 2.  obtaining dissection data

Field

A Field extractor to to obtain field values.

Field.new(fieldname)

Create a Field extractor

Arguments

fieldname

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

Returns

The field extractor

Errors

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

field:__call()

obtain all values (see FieldInfo) for this field.

Returns

All the values of this field

Errors

  • fields cannot be used outside dissectors or taps

FieldInfo

An extracted Field

fieldinfo:__len()

Obtain the Length of the field

fieldinfo:__unm()

Obtain the Offset of the field

fieldinfo:__call()

Obtain the Value of the field

fieldinfo:__tostring()

the string representation of the field

fieldinfo:__eq()

checks whether lhs is within rhs

Errors

  • data source must be the same for both fields

fieldinfo:__le()

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

fieldinfo:__lt()

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

Errors

  • data source must be the same for both fields

Non Method Functions

all_field_infos()

obtain all fields from the current tree

Chapter 3.  GUI support

TextWindow

Manages a text window.

TextWindow.new([title])

Creates a new TextWindow.

Arguments

title (optional)

Title of the new window.

Returns

The newly created TextWindow object.

textwindow:set_atclose(action)

Set the function that will be called when the window closes

Arguments

action

A function to be executed when the user closes the window

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:set(text)

Sets the text.

Arguments

text

The text to be used.

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:append(text)

Appends text

Arguments

text

The text to be appended

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:prepend(text)

Prepends text

Arguments

text

The text to be appended

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:clear()

Errases all text in the window.

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:get_text()

Get the text of the window

Returns

The TextWindow's text.

Errors

  • cannot be called for something not a TextWindow

  • cannot be called for something not a TextWindow

textwindow:set_editable([editable])

Make this window editable

Arguments

editable (optional)

A boolean flag, defaults to true

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

textwindow:add_button(label, function)

Arguments

label

The label of the button

function

The function to be called when clicked

Returns

The TextWindow object.

Errors

  • cannot be called for something not a TextWindow

Non Method Functions

gui_enabled()

Checks whether the GUI facility is enabled.

Returns

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

register_menu(name, action, group)

Register a menu item in the Statistics menu.

Arguments

name

The name of the menu item.

action

The function to be called when the menu item is invoked.

group

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

new_dialog(title, action, ...)

Pops up a new dialog

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

Errors

  • at least one field required

  • all fields must be strings

retap_packets()

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

copy_to_clipboard(text)

copy a string into the clipboard

Arguments

text

The string to be copied into the clipboard.

open_capture_file(filename, filter)

open and display a capture file

Arguments

filename

The name of the file to be opened.

filter

A filter tgo be applied as the file gets opened.

set_filter(text)

set the main filter text

Arguments

text

The filter's text.

apply_filter()

apply the filter in the main filter box

reload()

reload the current capture file

browser_open_url(url)

open an url in a browser

Arguments

url

The url.

browser_open_data_file(filename)

open an file in a browser

Arguments

filename

The url.

Chapter 4.  post-dissection packet analysis

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.

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

Creates a new Listener listener

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)

Returns

The newly created Listener listener object

Errors

  • tap registration error

listener:remove()

Removes a tap listener

listener.packet

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

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

listener.reset

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

Chapter 5.  obtaining packet information

Address

Represents an address

Address.ip(hostname)

Creates an Address Object representing an IP address.

Arguments

hostname

The address or name of the IP host.

Returns

the Address object

address:__tostring()

Returns

The string representing the address.

address:__eq()

compares two Addresses

address:__le()

compares two Addresses

address:__lt()

compares two Addresses

Column

A Column in the packet list

column:__tostring()

Returns

A string representing the column

column:clear()

Clears a Column

column:set(text)

Sets the text of a Column

Arguments

text

The text to which to set the Column

column:append(text)

Appends text to a Column

Arguments

text

The text to append to the Column

column:preppend(text)

Prepends text to a Column

Arguments

text

The text to prepend to the Column

Columns

The Columns of the packet list.

columns:__tostring()

Returns

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

columns:__newindex(column, text)

Sets the text of a specific column

Arguments

column

the name of the column to set

text

the text for the column

Pinfo

Packet information

pinfo.number

The number of this packet in the current file

pinfo.len

The length of the frame

pinfo.caplen

The captured length of the frame

pinfo.abs_ts

When the packet was captured

pinfo.rel_ts

Number of seconds passed since beginning of capture

pinfo.delta_ts

Number of seconds passed since the last packet

pinfo.visited

Whether this packet hass been already visited

pinfo.src

Source Address of this Packet

pinfo.dst

Destination Address of this Packet

pinfo.lo

lower Address of this Packet

pinfo.hi

higher Address of this Packet

pinfo.dl_src

Data Link Source Address of this Packet

pinfo.dl_dst

Data Link Destination Address of this Packet

pinfo.net_src

Network Layer Source Address of this Packet

pinfo.net_dst

Network Layer Destination Address of this Packet

pinfo.ptype

Type of Port of .src_port and .dst_port

pinfo.src_port

Source Port of this Packet

pinfo.dst_port

Source Address of this Packet

pinfo.ipproto

IP Protocol id

pinfo.circuit_id

For circuit based protocols

pinfo.match

Port/Data we are matching

pinfo.curr_proto

Which Protocol are we dissecting

pinfo.columns

Accesss to the packet list columns

pinfo.cols

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

Chapter 6.  functions for writing dissectors

Table of Contents

Dissector
Dissector.get(name)
dissector:call(tvb, pinfo, tree)
DissectorTable
DissectorTable.new(tablename, [uiname], [type])
DissectorTable.get(tablename)
dissectortable:add(pattern, dissector)
dissectortable:remove(pattern, dissector)
dissectortable:try(pattern, tvb, pinfo, tree)
dissectortable:get_dissector(pattern)
Pref
Pref.bool(label, default, descr)
Pref.uint(label, default, descr)
Pref.string(label, default, descr)
Prefs
prefs:__newindex(name, pref)
prefs:__index(name)
Proto
Proto.new(name, desc)
proto.dissector
proto.fields
proto.get_prefs
proto.init
proto.name
ProtoField
ProtoField.new(name, abbr, type, [valuestring], [base], [mask], [descr])
ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.framenum(abbr, [name], [base], [valuestring], [mask], [desc])
ProtoField.ipv4(abbr, [name], [desc])
ProtoField.ipv6(abbr, [name], [desc])
ProtoField.ether(abbr, [name], [desc])
ProtoField.float(abbr, [name], [desc])
ProtoField.double(abbr, [name], [desc])
ProtoField.string(abbr, [name], [desc])
ProtoField.strigz(abbr, [name], [desc])
ProtoField.bytes(abbr, [name], [desc])
ProtoField.ubytes(abbr, [name], [desc])
ProtoField.guid(abbr, [name], [desc])
ProtoField.oid(abbr, [name], [desc])
ProtoField.bool(abbr, [name], [desc])
Non Method Functions
register_postdissector(proto)

Dissector

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

Dissector.get(name)

* Obtains a dissector reference by name

Arguments

name

The name of the dissector

Returns

The Dissector reference

dissector:call(tvb, pinfo, tree)

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

Arguments

tvb

The buffer to dissect

pinfo

The packet info

tree

The tree on which to add the protocol items

Errors

  • malformed frame

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.

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

Creates a new DissectorTable for your dissector's use .

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)

Returns

The newly created DissectorTable

DissectorTable.get(tablename)

Obtain a reference to an existing dissector table.

Arguments

tablename

The short name of the table.

Returns

The DissectorTable

dissectortable:add(pattern, dissector)

Add a dissector to a table.

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

dissectortable:remove(pattern, dissector)

Remove a dissector from a table

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

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

Try to call a dissector from a table

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

Errors

  • malformed frame

dissectortable:get_dissector(pattern)

Try to obtain a dissector from a table.

Arguments

pattern

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

Returns

The dissector handle if found

nil if not found

Pref

A preference of a Protocol.

Pref.bool(label, default, descr)

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

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

Pref.uint(label, default, descr)

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

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

Pref.string(label, default, descr)

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

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

Prefs

The table of preferences of a protocol

prefs:__newindex(name, pref)

creates a new preference

Arguments

name

The abbreviation of this preference

pref

A valid but still unassigned Pref object

Errors

  • unknow Pref type

prefs:__index(name)

get the value of a preference setting

Arguments

name

The abbreviation of this preference

Returns

the current value of the preference

Errors

  • unknow Pref type

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.

Proto.new(name, desc)

Arguments

name

The name of the protocol

desc

A Long Text description of the protocol (usually lowercase)

Returns

The newly created protocol

proto.dissector

the protocol's dissector, a function you define

proto.fields

the Fields Table of this dissector

proto.get_prefs

the preferences of this dissector

proto.init

the init routine of this dissector, a function you define

proto.name

the name given to this dissector

ProtoField

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

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

Creates a new field to be used in a protocol.

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.

Returns

The newly created ProtoField object

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

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

Returns

a protofield item to be added to a ProtoFieldArray

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

a frame number (for hyperlinks between frames)

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.ipv4(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.ipv6(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.ether(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.float(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.double(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.string(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.strigz(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.bytes(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.ubytes(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.guid(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.oid(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

ProtoField.bool(abbr, [name], [desc])

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

Returns

a protofield item to be added to a ProtoFieldArray

Non Method Functions

register_postdissector(proto)

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

Arguments

proto

the protocol to be used as postdissector

Chapter 7.  adding information to the dissection tree

TreeItem

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

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.

Returns

The child item

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.

Returns

The child item

treeitem:set_text(text)

sets the text of the label

Arguments

text

The text to be used.

treeitem:append_text(text)

appends text to the label

Arguments

text

The text to be appended.

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

Sets the expert flags of the item.

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

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

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

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

treeitem:set_generated()

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

treeitem:set_hidden()

should not be used

Chapter 8.  functions for handling packet data

ByteArray

ByteArray.new([hexbytes])

creates a ByteArray Object

Arguments

hexbytes (optional)

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

Returns

The new ByteArray object.

bytearray:__concat(first, second)

concatenate two ByteArrays

Arguments

first

first array

second

second array

Returns

The new composite ByteArray.

Errors

  • both arguments must be ByteArrays

bytearray:prepend(prepended)

prepend a ByteArray to this ByteArray

Arguments

prepended

array to be prepended

Errors

  • both arguments must be ByteArrays

bytearray:append(appended)

append a ByteArray to this ByteArray

Arguments

appended

array to be appended

Errors

  • both arguments must be ByteArrays

bytearray:set_size(size)

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

Arguments

size

new size of the array

bytearray:set_index(index, value)

sets the value of an index of a ByteArray.

Arguments

index

the position of the byte to be set

value

the char value to set [0-255]

bytearray:get_index(index)

get the value of a byte in a ByteArray

Arguments

index

the position of the byte to be set

Returns

The value [0-255] of the byte.

bytearray:len()

obtain the length of a ByteArray

Returns

The length of the ByteArray.

bytearray:subset(offset, length)

obtain a segment of a ByteArray

Arguments

offset

the position of the first byte

length

the lenght of the segment

Returns

a ByteArray contaning the requested segment.

a string contaning a representaion of the ByteArray.

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

Tvb.new_real(bytearray, name)

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

Arguments

bytearray

The data source for this Tvb.

name

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

Returns

the created Tvb.

Tvb.new_subset(range)

creates a (sub)Tvb from using a TvbRange

Arguments

range

the TvbRange from which to create the new Tvb.

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.

Returns

the string.

tvb:len()

obtain the length of a TVB

Returns

the lenght of the Tvb.

tvb:offset()

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

Returns

the raw offset of the Tvb.

tvb:__call()

equivalent to tvb:range(...)

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,lenght)). If the TvbRange span is outside the Tvb's range the creation will cause a runtime error.

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

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

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.

Returns

the TvbRange

tvbrange:get_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

Returns

the unsigned integer value

tvbrange:get_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

Returns

the unsigned integer value

tvbrange:get_float()

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

Returns

the flaoting point value

tvbrange:get_le_float()

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

Returns

the flaoting point value

tvbrange:get_ipv4()

get an IPv4 Address from a TvbRange.

Returns

the IPv4 Address

tvbrange:get_ether()

get an Ethernet Address from a TvbRange.

Returns

the Ethernet Address

Errors

  • The range must be 6 bytes long

tvbrange:get_string()

obtain a string from a TvbRange

Returns

the string

tvbrange:get_bytes()

obtain a ByteArray

Returns

the ByteArray

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

tvbrange.tvb

The Tvb from which this TvbRange was generated

tvbrange.len

The lenght (in octets) of this TvbRange

tvbrange.offset

The offset (in octets) of this TvbRange

Chapter 9.  Utility Functions

Dir

A Directory

Dir.open(pathname, [extension])

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

Arguments

pathname

the pathname of the directory

extension (optional)

if given, only file with this extension will be returned

Returns

the Dir object

dir:__call()

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

dir:close()

closes the directory

Non Method Functions

format_date(timestamp)

Formats an absolute timestamp into a human readable date

Arguments

timestamp

A timestamp value to convert.

Returns

a string with the formated date

format_time(timestamp)

Formats a relative timestamp in a human readable form

Arguments

timestamp

a timestamp value to convert

Returns

a string with the formated time

report_failure(text)

reports a failure to the user

Arguments

text

message

critical(...)

Will add a log entry with critical severity

Arguments

...

objects to be printed

warn(...)

Will add a log entry with warn severity

Arguments

...

objects to be printed

message(...)

Will add a log entry with message severity

Arguments

...

objects to be printed

info(...)

Will add a log entry with info severity

Arguments

...

objects to be printed

debug(...)

Will add a log entry with debug severity

Arguments

...

objects to be printed

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

Arguments

filename

name of the file to be loaded

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

Arguments

filename

name of the file to be run

persconffile_path([filename])

Arguments

filename (optional)

a filename

Returns

the full pathname for a file in the personal configuration directory

datafile_path([filename])

Arguments

filename (optional)

a filename

Returns

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

register_stat_cmd_arg(argument, [action])

Register a function to handle a -z option

Arguments

argument

action (optional)