10.4. Wireshark's Lua API Reference Manual
Prev | Chapter 10. Lua Support in Wireshark | Next

## 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. ProgDlg

Manages a progress bar dialog.

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

Creates a new TextWindow.

###### 10.4.3.1.1.1. Arguments

title (optional)

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

task (optional)

  Current task, defaults to "".

###### 10.4.3.1.1.2. Returns

The newly created TextWindow object.

##### 10.4.3.1.2. progdlg:update(progress, [task])

Appends text

###### 10.4.3.1.2.1. Arguments

progress

  Part done ( e.g. 0.75 ).

task (optional)

  Current task, defaults to "".

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

##### 10.4.3.1.3. progdlg:stopped()

Checks wheher the user has pressed the stop button.

###### 10.4.3.1.3.1. Returns

true if the user has asked to stop the progress.

###### 10.4.3.1.3.2. Errors

- cannot be called for something not a ProgDlg

##### 10.4.3.1.4. progdlg:close()

Appends text

###### 10.4.3.1.4.1. Errors

- cannot be called for something not a ProgDlg

#### 10.4.3.2. TextWindow

Manages a text window.

##### 10.4.3.2.1. TextWindow.new([title])

Creates a new TextWindow.

###### 10.4.3.2.1.1. Arguments

title (optional)

  Title of the new window.

###### 10.4.3.2.1.2. Returns

The newly created TextWindow object.

##### 10.4.3.2.2. textwindow:set_atclose(action)

Set the function that will be called when the window closes

###### 10.4.3.2.2.1. Arguments

action

  A function to be executed when the user closes the window

###### 10.4.3.2.2.2. Returns

The TextWindow object.

###### 10.4.3.2.2.3. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.3. textwindow:set(text)

Sets the text.

###### 10.4.3.2.3.1. Arguments

text

  The text to be used.

###### 10.4.3.2.3.2. Returns

The TextWindow object.

###### 10.4.3.2.3.3. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.4. textwindow:append(text)

Appends text

###### 10.4.3.2.4.1. Arguments

text

  The text to be appended

###### 10.4.3.2.4.2. Returns

The TextWindow object.

###### 10.4.3.2.4.3. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.5. textwindow:prepend(text)

Prepends text

###### 10.4.3.2.5.1. Arguments

text

  The text to be appended

###### 10.4.3.2.5.2. Returns

The TextWindow object.

###### 10.4.3.2.5.3. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.6. textwindow:clear()

Errases all text in the window.

###### 10.4.3.2.6.1. Returns

The TextWindow object.

###### 10.4.3.2.6.2. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.7. textwindow:get_text()

Get the text of the window

###### 10.4.3.2.7.1. Returns

The TextWindow's text.

###### 10.4.3.2.7.2. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.8. textwindow:set_editable([editable])

Make this window editable

###### 10.4.3.2.8.1. Arguments

editable (optional)

  A boolean flag, defaults to true

###### 10.4.3.2.8.2. Returns

The TextWindow object.

###### 10.4.3.2.8.3. Errors

- cannot be called for something not a TextWindow

##### 10.4.3.2.9. textwindow:add_button(label, function)

###### 10.4.3.2.9.1. Arguments

label

  The label of the button

function

  The function to be called when clicked

###### 10.4.3.2.9.2. Returns

The TextWindow object.

###### 10.4.3.2.9.3. Errors

- cannot be called for something not a TextWindow

#### 10.4.3.3. Non Method Functions

##### 10.4.3.3.1. gui_enabled()

Checks whether the GUI facility is enabled.

###### 10.4.3.3.1.1. Returns

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

##### 10.4.3.3.2. register_menu(name, action, [group])

Register a menu item in one of the main menus.

###### 10.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 (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.3.3. new_dialog(title, action, ...)

Pops up a new dialog

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

###### 10.4.3.3.3.2. Errors

- at least one field required

- all fields must be strings

##### 10.4.3.3.4. retap_packets()

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

##### 10.4.3.3.5. copy_to_clipboard(text)

copy a string into the clipboard

###### 10.4.3.3.5.1. Arguments

text

  The string to be copied into the clipboard.

##### 10.4.3.3.6. open_capture_file(filename, filter)

open and display a capture file

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

##### 10.4.3.3.7. set_filter(text)

set the main filter text

###### 10.4.3.3.7.1. Arguments

text

  The filter's text.

##### 10.4.3.3.8. apply_filter()

apply the filter in the main filter box

##### 10.4.3.3.9. reload()

reload the current capture file

##### 10.4.3.3.10. browser_open_url(url)

open an url in a browser

###### 10.4.3.3.10.1. Arguments

url

  The url.

##### 10.4.3.3.11. browser_open_data_file(filename)

open an file in a browser

###### 10.4.3.3.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.5.2. Errors

- ByteArray size must be non-negative

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

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

##### 10.4.8.3.1. Tvb.new_real(bytearray, name)

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

###### 10.4.8.3.1.1. Arguments

bytearray

  The data source for this Tvb.

name

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

###### 10.4.8.3.1.2. Returns

the created Tvb.

##### 10.4.8.3.2. Tvb.tvb(range)

creates a (sub)Tvb from using a TvbRange

###### 10.4.8.3.2.1. Arguments

range

  the TvbRange from which to create the new Tvb.

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

###### 10.4.8.3.3.1. Returns

the string.

##### 10.4.8.3.4. tvb:len()

obtain the length of a TVB

###### 10.4.8.3.4.1. Returns

the length of the Tvb.

##### 10.4.8.3.5. tvb:offset()

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

###### 10.4.8.3.5.1. Returns

the raw offset of the Tvb.

##### 10.4.8.3.6. tvb:__call()

equivalent to tvb:range(...)

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

##### 10.4.8.4.1. tvb:range([offset], [length])

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

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

###### 10.4.8.4.1.2. Returns

the TvbRange

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

###### 10.4.8.4.2.1. Returns

the unsigned integer value

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

###### 10.4.8.4.3.1. Returns

the unsigned integer value

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

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

##### 10.4.8.4.6. 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.4.6.1. Returns

the flaoting point value

##### 10.4.8.4.7. 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.4.7.1. Returns

the flaoting point value

##### 10.4.8.4.8. tvbrange:ipv4()

get an IPv4 Address from a TvbRange.

###### 10.4.8.4.8.1. Returns

the IPv4 Address

##### 10.4.8.4.9. tvbrange:le_ipv4()

get an Little Endian IPv4 Address from a TvbRange.

###### 10.4.8.4.9.1. Returns

the IPv4 Address

##### 10.4.8.4.10. tvbrange:ether()

get an Ethernet Address from a TvbRange.

###### 10.4.8.4.10.1. Returns

the Ethernet Address

###### 10.4.8.4.10.2. Errors

- The range must be 6 bytes long

##### 10.4.8.4.11. tvbrange:string()

obtain a string from a TvbRange

###### 10.4.8.4.11.1. Returns

the string

##### 10.4.8.4.12. tvbrange:bytes()

obtain a ByteArray

###### 10.4.8.4.12.1. Returns

the ByteArray

##### 10.4.8.4.13. tvbrange:len()

obtain the length of a TvbRange

##### 10.4.8.4.14. tvbrange:offset()

obtain the offset in a TvbRange

##### 10.4.8.4.15. 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.5. UInt

* Int64 represents a 64 bit integer.

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

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