13.3. Functions For New Protocols And Dissectors
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.3. Functions For New Protocols And Dissectors

The classes and functions in this chapter allow Lua scripts to create new protocols for Wireshark. `Proto` protocol objects can have `Pref` preferences, `ProtoField` fields for filterable values that can be displayed in a details view tree, functions for dissecting the new protocol, and so on.

The dissection function can be hooked into existing protocol tables through `DissectorTable` so that the new protocol dissector function gets called by that protocol, and the new dissector can itself call on other, already existing protocol dissectors by retrieving and calling the `Dissector` object. A `Proto` dissector can also be used as a post-dissector, at the end of every frame’s dissection, or as a heuristic dissector.

### 13.3.1. Dissector

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

#### 13.3.1.1. Dissector.get(name)

Obtains a dissector reference by name.

##### Arguments

name
  The name of the dissector.

##### Returns

The `Dissector` reference if found, otherwise `nil`.

#### 13.3.1.2. Dissector.list()

Gets a Lua array table of all registered Dissector names.

Note: This is an expensive operation, and should only be used for troubleshooting.

##### Returns

The array table of registered dissector names.

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

##### Returns

Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.

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

#### 13.3.1.5. dissector:decrypt(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.

##### Returns

Number of bytes dissected and decrypted content

#### 13.3.1.6. dissector:__decrypt(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.

#### 13.3.1.7. dissector:__tostring()

Gets the Dissector’s description.

##### Returns

A string of the Dissector’s description.

#### 13.3.1.8. dissector.description

Mode: Retrieve only.

Human-readable description of the dissector (same string returned by tostring/print).

#### 13.3.1.9. dissector.protocol_short_name

Mode: Retrieve only.

Short name of the protocol the dissector is registered to (e.g. "tcp"); nil if the handle has no backing protocol.

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

#### 13.3.2.1. DissectorTable.new(tablename, [uiname], [type], [base], [proto])

Creates a new `DissectorTable` for your dissector’s use.

##### Arguments

tablename
  The short name of the table. Use lower-case alphanumeric, dot, and/or underscores (e.g., "ansi_map.tele_id" or "udp.port").

uiname (optional)
  The name of the table in the user interface. Defaults to the name given in `tablename`, but can be any string.

type (optional)
  One of `ftypes.UINT8`, `ftypes.UINT16`, `ftypes.UINT24`, `ftypes.UINT32`, `ftypes.STRING`, `ftypes.NONE`, or `ftypes.GUID`. Defaults to `ftypes.UINT32`.

base (optional)
  One of `base.NONE`, `base.DEC`, `base.HEX`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. Defaults to `base.DEC`.

proto (optional)
  The `Proto` object that uses this dissector table.

##### Returns

The newly created DissectorTable.

#### 13.3.2.2. DissectorTable.heuristic_new(tablename, [uiname], proto)

Creates a new heuristic `DissectorTable` for your dissector’s use. Returns true if table was created successfully.

- XXX - Currently it always returns nil.

Since: 4.2.0

##### Arguments

tablename
  The short name of the table. Use lower-case alphanumeric, dot, and/or underscores.

uiname (optional)
  The name of the table in the user interface. Defaults to the name given in `tablename`, but can be any string.

proto
  The `Proto` object that uses this dissector table.

##### Returns

The newly created DissectorTable.

#### 13.3.2.3. DissectorTable.list()

Gets a Lua array table of all DissectorTable names - i.e., the string names you can use for the first argument to DissectorTable.get().

Note: This is an expensive operation, and should only be used for troubleshooting.

##### Returns

The array table of registered DissectorTable names.

#### 13.3.2.4. DissectorTable.heuristic_list()

Gets a Lua array table of all heuristic list names - i.e., the string names you can use for the first argument in Proto:register_heuristic().

Note: This is an expensive operation, and should only be used for troubleshooting.

##### Returns

The array table of registered heuristic list names

#### 13.3.2.5. DissectorTable.try_heuristics(listname, tvb, pinfo, tree)

Try all the dissectors in a given heuristic dissector table.

##### Arguments

listname
  The name of the heuristic dissector.

tvb
  The buffer to dissect.

pinfo
  The packet info.

tree
  The tree on which to add the protocol items.

##### Returns

True if the packet was recognized by the sub-dissector (stop dissection here).

#### 13.3.2.6. DissectorTable.get(tablename)

Obtain a reference to an existing dissector table.

##### Arguments

tablename
  The short name of the table.

##### Returns

The `DissectorTable` reference if found, otherwise `nil`.

#### 13.3.2.7. dissectortable:add(pattern, dissector)

Add a `Proto` with a dissector function or a `Dissector` object to the dissector table.

##### Arguments

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

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

#### 13.3.2.8. dissectortable:set(pattern, dissector)

Clear all existing dissectors from a table and add a new dissector or a range of new dissectors.

##### Arguments

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

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

#### 13.3.2.9. dissectortable:remove(pattern, dissector)

Remove a dissector or a range of dissectors from a table.

##### Arguments

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

dissector
  The dissector to remove (either a `Proto` or a `Dissector`).

#### 13.3.2.10. dissectortable:remove_all(dissector)

Remove all dissectors from a table.

##### Arguments

dissector
  The dissector to remove (either a `Proto` or a `Dissector`).

#### 13.3.2.11. 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 `Tvb` to dissect.

pinfo
  The packet’s `Pinfo`.

tree
  The `TreeItem` on which to add the protocol items.

##### Returns

Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.

#### 13.3.2.12. dissectortable:get_dissector(pattern)

Try to obtain a dissector from a table.

##### Arguments

pattern
  The pattern to be matched, depending on the table’s type.

##### Returns

The `Dissector` handle if found, otherwise `nil`

#### 13.3.2.13. dissectortable:add_for_decode_as(proto)

Add the given `Proto` to the “Decode as…​” list for this DissectorTable. The passed-in `Proto` object’s `dissector()` function is used for dissecting.

##### Arguments

proto
  The `Proto` to add.

#### 13.3.2.14. dissectortable:__tostring()

Returns a short label of the form `DissectorTable: <name> type=<type_name>` and appends `base=<n>` for integer tables or ` (Decode As only)` for FT_NONE tables. The previous form ended in a colon and embedded a literal newline, which was confusing in single-line listings like the debugger Variables view.

##### Returns

A short label identifying the table.

#### 13.3.2.15. dissectortable.name

Mode: Retrieve only.

The registered name of the DissectorTable (e.g. "tcp.port").

#### 13.3.2.16. dissectortable.ui_name

Mode: Retrieve only.

The human-readable UI name of the DissectorTable, or nil if one was not registered.

#### 13.3.2.17. dissectortable.type

Mode: Retrieve only.

The selector ftype (ftenum value) for value-indexed tables, or -1 for heuristic tables. Use `DissectorTable.type_name` for the human-readable string.

#### 13.3.2.18. dissectortable.type_name

Mode: Retrieve only.

Human-readable string for the selector ftype ("FT_STRING", "FT_UINT32", …​, "FT_NONE" for Decode-As-only tables) or "heuristic" for heuristic tables.

### 13.3.3. Pref

A preference of a `Proto`.

#### 13.3.3.1. Pref.bool(label, default, description)

Creates a boolean preference to be added to a `Proto.prefs` Lua table.

#### 13.3.3.2. Example

        -- create a Boolean preference named "bar" for Foo Protocol
        -- (assuming Foo doesn't already have a preference named "bar")
        proto_foo.prefs.bar = Pref.bool( "Bar", true, "Baz and all the rest" )

##### Arguments

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

default
  The default value for this preference.

description
  A description of this preference.

#### 13.3.3.3. Pref.uint(label, default, description)

Creates an (unsigned) integer preference to be added to a `Proto.prefs` Lua table.

##### Arguments

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

default
  The default value for this preference.

description
  A description of what this preference is.

#### 13.3.3.4. Pref.string(label, default, description)

Creates a string preference to be added to a `Proto.prefs` Lua table.

##### Arguments

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

default
  The default value for this preference.

description
  A description of what this preference is.

#### 13.3.3.5. Pref.enum(label, default, description, enum, radio)

Creates an enum preference to be added to a `Proto.prefs` Lua table.

#### 13.3.3.6. Example:

        local OUTPUT_OFF        = 0
        local OUTPUT_DEBUG      = 1
        local OUTPUT_INFO       = 2
        local OUTPUT_WARN       = 3
        local OUTPUT_ERROR      = 4

        local output_tab = {
                { 1, "Off"              , OUTPUT_OFF },
                { 2, "Debug"            , OUTPUT_DEBUG },
                { 3, "Information"      , OUTPUT_INFO },
                { 4, "Warning"          , OUTPUT_WARN },
                { 5, "Error"            , OUTPUT_ERROR },
        }

        -- Create enum preference that shows as Combo Box under
        -- Foo Protocol's preferences
        proto_foo.prefs.outputlevel = Pref.enum(
                "Output Level",                 -- label
                OUTPUT_INFO,                    -- default value
                "Verbosity of log output",      -- description
                output_tab,                     -- enum table
                false                           -- show as combo box
        )

        -- Then, we can query the value of the selected preference.
        -- This line prints "Output Level: 3" assuming the selected
        -- output level is _INFO.
        debug( "Output Level: " .. proto_foo.prefs.outputlevel )

##### Arguments

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

default
  The default value for this preference.

description
  A description of what this preference is.

enum
  An enum Lua table.

radio
  Radio button (true) or Combobox (false).

#### 13.3.3.7. Pref.range(label, default, description, max)

Creates a range (numeric text entry) preference to be added to a `Proto.prefs` Lua table.

##### Arguments

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

default
  The default value for this preference, e.g., "53", "10-30", or "10-30,53,55,100-120".

description
  A description of what this preference is.

max
  The maximum value.

#### 13.3.3.8. Pref.statictext(label, description)

Creates a static text string to be added to a `Proto.prefs` Lua table.

##### Arguments

label
  The static text.

description
  The static text description.

#### 13.3.3.9. Pref.uat(label, [field_config], [description], [file_name])

Creates an uat preference to be added to a `Proto.prefs` Lua table, or read an existent uat table content, and returns in a table, all returned cell conent is in string format.

#### 13.3.3.10. Example:

        local fieldlist = {
            {"field 1", "Description 1"},
            {"field 2", "Description 2"},
        }

        -- Create a uat preference that appears as a button on the Foo Protocol preference page.
        -- The user accessible table can be edited with this button.
        proto_foo.prefs.preference_uat_name = Pref.uat("Label", fieldlist, "Description", "uat_filename")

        -- Value checker:

        -- Create a file in Personal Lua plugins directory named as preferences_uat_callbacks.lua
        -- Create a checker function named as uat_update_cb:
        -- The uat editor will call this function for checks the values.
        function uat_update_cb(records, uat_filename)
            print("UAT filename: " .. uat_filename)
            print("UAT record 0 = " .. records[0])
            print("UAT record 1 = " .. records[1])
            local result = true
            local errstring = ""
            -- do not allow 5 in the "field 1
            if (tonumber(records[0]) == 5) then
                result = false
                errstring = "Firsct collumn cannot be 5!"
            end
            print("Check result = " .. tostring(result))
            -- return check result as boolean and errstring if needed
            return result, errstring
        end

        -- Reading existent uat:

        proto_foo.prefs.preference_existent_uat_name = Pref.uat("Protobuf Search Paths")
        for i, row in ipairs(proto_foo.prefs.preference_existent_uat_name) do
            local row_str = ""
            for j, value in ipairs(row) do
                row_str = row_str .. value .. "\t"
            end
            print(row_str)
        end

##### Arguments

label
  The Label for this preference. In case of existent uat table reading, this argument contains the uat name, and all other argument is omitted.

field_config (optional)
  Fields names and description table.

description (optional)
  A description of what this preference is.

file_name (optional)
  The name of the uat file.

#### 13.3.3.11. pref:__tostring()

Returns a short label of the form `Pref: <name> type=<type> value=<value>` (e.g. `Pref: mypref type=bool value=true`). Unregistered prefs (created by `Pref.bool()` etc. but not yet assigned into a `Prefs` table) render as `Pref: (unregistered) type=<type> value=<value>`.

##### Returns

The string.

#### 13.3.3.12. pref.name

Mode: Retrieve only.

The name/abbreviation of the preference.

#### 13.3.3.13. pref.label

Mode: Retrieve only.

The user-visible label of the preference.

#### 13.3.3.14. pref.description

Mode: Retrieve only.

The human-readable description.

#### 13.3.3.15. pref.type

Mode: Retrieve only.

The preference type as the raw pref_type_e enum value (integer). Use `Pref.type_name` for the human-readable short string ("bool", "uint", "string", "enum", "range", "statictext", "uat").

#### 13.3.3.16. pref.type_name

Mode: Retrieve only.

Human-readable short string matching the Pref.type enum: "bool", "uint", "string", "enum", "range", "statictext", "uat", or "unknown".

#### 13.3.3.17. pref.value

Mode: Retrieve only.

The current value of the preference. *

- The concrete Lua type depends on Pref.type: bool/uint/string/enum/range
- return the expected primitive, while statictext and uat return nil to
- match the existing behavior of Prefs.__index.

### 13.3.4. Prefs

The table of preferences of a protocol.

#### 13.3.4.1. prefs:__newindex(name, pref)

Creates a new preference.

##### Arguments

name
  The abbreviation of this preference.

pref
  A valid but still unassigned Pref object.

##### Errors

- Unknown Pref type

#### 13.3.4.2. prefs:__index(name)

Get the value of a preference setting.

#### 13.3.4.3. Example

        -- print the value of Foo's preference named "bar"
        debug( "bar = " .. proto_foo.prefs.bar )

##### Arguments

name
  The abbreviation of this preference.

##### Returns

The current value of the preference.

##### Errors

- Unknown Pref type

#### 13.3.4.4. prefs:__tostring()

Returns a short label of the form `Prefs: <proto> entries=<n>`, where <proto> is the owning protocol’s short name and <n> is the number of registered prefs (zero for a freshly registered proto with no `proto.prefs.foo = …​` assignments yet).

##### Returns

The string.

#### 13.3.4.5. prefs:__pairs()

Iterate over all registered preferences of a protocol.

#### 13.3.4.6. Example

        for name, pref in pairs(proto_foo.prefs) do
            debug(name .. " = " .. tostring(pref.value))
        end

### 13.3.5. Proto

A new protocol in Wireshark. Protocols have several uses. The main one is to dissect a protocol, but they can also be dummies used to register preferences for other purposes.

#### 13.3.5.1. Proto.new(name, description)

Creates a new `Proto` object.

##### Arguments

name
  The name of the protocol.

description
  A Long Text description of the protocol (usually lowercase).

##### Returns

The newly created `Proto` object.

#### 13.3.5.2. proto:__call(name, description)

Creates a `Proto` object.

##### Arguments

name
  The name of the protocol.

description
  A Long Text description of the protocol (usually lowercase).

##### Returns

The new `Proto` object.

#### 13.3.5.3. proto:register_heuristic(listname, func)

Registers a heuristic dissector function for this `Proto` protocol, for the given heuristic list name.

When later called, the passed-in function will be given:

1. A `Tvb` object
2. A `Pinfo` object
3. A `TreeItem` object

The function must return `true` if the payload is for it, else `false`.

The function should perform as much verification as possible to ensure the payload is for it, and dissect the packet (including setting TreeItem info and such) only if the payload is for it, before returning true or false.

Since version 1.99.1, this function also accepts a Dissector object as the second argument, to allow re-using the same Lua code as the `function proto.dissector(…​)`. In this case, the Dissector must return a Lua number of the number of bytes consumed/parsed: if 0 is returned, it will be treated the same as a `false` return for the heuristic; if a positive or negative number is returned, then the it will be treated the same as a `true` return for the heuristic, meaning the packet is for this protocol and no other heuristic will be tried.

##### Arguments

listname
  The heuristic list name this function is a heuristic for (e.g., "udp" or "infiniband.payload").

func
  A Lua function that will be invoked for heuristic dissection.

#### 13.3.5.4. proto.dissector

Mode: Retrieve or assign.

The protocol’s dissector, a function you define.

When later called, the function will be given:

1. A `Tvb` object
2. A `Pinfo` object
3. A `TreeItem` object

#### 13.3.5.5. proto.prefs

Mode: Retrieve only.

The preferences of this dissector.

#### 13.3.5.6. proto.prefs_changed

Mode: Assign only.

The preferences changed routine of this dissector, a Lua function you define.

The function is called when the protocol’s preferences are changed. It is passed no arguments.

#### 13.3.5.7. proto.init

Mode: Assign only.

The init routine of this dissector, a function you define.

The init function is called when the a new capture file is opened or when the open capture file is closed. It is passed no arguments.

#### 13.3.5.8. proto.name

Mode: Retrieve only.

The name given to this dissector.

#### 13.3.5.9. proto.description

Mode: Retrieve only.

The description given to this dissector.

#### 13.3.5.10. proto.fields

Mode: Retrieve or assign.

The Lua table of this dissector’s `ProtoField`s. `ProtoField`s added to this table are registered to the `Proto` (and any removed are deregistered if previously registered.)

#### 13.3.5.11. proto.experts

Mode: Retrieve or assign.

The expert info Lua table of this `Proto`.

### 13.3.6. ProtoExpert

A Protocol expert info field, to be used when adding items to the dissection tree.

#### 13.3.6.1. ProtoExpert.new(abbr, text, group, severity)

Creates a new `ProtoExpert` object to be used for a protocol’s expert information notices.

##### Arguments

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

text
  The default text of the expert field.

group
  Expert group type: one of: `expert.group.CHECKSUM`, `expert.group.SEQUENCE`, `expert.group.RESPONSE_CODE`, `expert.group.REQUEST_CODE`, `expert.group.UNDECODED`, `expert.group.REASSEMBLE`, `expert.group.MALFORMED`, `expert.group.DEBUG`, `expert.group.PROTOCOL`, `expert.group.SECURITY`, `expert.group.COMMENTS_GROUP`, `expert.group.DECRYPTION`, `expert.group.ASSUMPTION`, `expert.group.DEPRECATED`, `expert.group.RECEIVE`, or `expert.group.INTERFACE`.

severity
  Expert severity type: one of: `expert.severity.COMMENT`, `expert.severity.CHAT`, `expert.severity.NOTE`, `expert.severity.WARN`, or `expert.severity.ERROR`.

##### Returns

The newly created `ProtoExpert` object.

#### 13.3.6.2. protoexpert:__tostring()

Returns a short label of the form `ProtoExpert: <abbrev> severity=<severity> text="<text>"` where <severity> is the human-readable severity name (matching `ProtoExpert.severity`). Replaces the previous integer-only dump of every internal id, which is still reachable via the individual `abbrev`/`text`/`group`/ `severity` attributes.

#### 13.3.6.3. protoexpert.abbrev

Mode: Retrieve only.

The filter name/abbreviation of the expert field.

#### 13.3.6.4. protoexpert.text

Mode: Retrieve only.

The default text of the expert field.

#### 13.3.6.5. protoexpert.group

Mode: Retrieve only.

The expert group as a descriptive string (matches expert.group.*).

#### 13.3.6.6. protoexpert.severity

Mode: Retrieve only.

The severity level as a descriptive string (matches expert.severity.*).

### 13.3.7. ProtoField

A Protocol field (to be used when adding items to the dissection tree). It must be registered via being added to a `Proto.fields` table.

#### 13.3.7.1. ProtoField.new(name, abbr, type, [valuestring], [base], [mask], [description])

Creates a new `ProtoField` object to be used for a protocol field.

##### 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: one of: `ftypes.BOOLEAN`, `ftypes.CHAR`, `ftypes.UINT8`, `ftypes.UINT16`, `ftypes.UINT24`, `ftypes.UINT32`, `ftypes.UINT64`, `ftypes.INT8`, `ftypes.INT16`, `ftypes.INT24`, `ftypes.INT32`, `ftypes.INT64`, `ftypes.FLOAT`, `ftypes.DOUBLE` , `ftypes.ABSOLUTE_TIME`, `ftypes.RELATIVE_TIME`, `ftypes.STRING`, `ftypes.STRINGZ`, `ftypes.UINT_STRING`, `ftypes.ETHER`, `ftypes.BYTES`, `ftypes.UINT_BYTES`, `ftypes.IPv4`, `ftypes.IPv6`, `ftypes.IPXNET`, `ftypes.FRAMENUM`, `ftypes.PCRE`, `ftypes.GUID`, `ftypes.OID`, `ftypes.PROTOCOL`, `ftypes.REL_OID`, `ftypes.SYSTEM_ID`, `ftypes.EUI64` or `ftypes.NONE`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that corresponds to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`, or one of `frametype.NONE`, `frametype.REQUEST`, `frametype.RESPONSE`, `frametype.ACK` or `frametype.DUP_ACK` if field type is ftypes.FRAMENUM.

base (optional)
  The representation, one of: `base.NONE`, `base.DEC`, `base.HEX`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

mask (optional)
  The bitmask to be used.

description (optional)
  The description of the field.

##### Returns

The newly created `ProtoField` object.

#### 13.3.7.2. ProtoField.char(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an 8-bit ASCII character.

##### 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.NONE`, `base.HEX` or `base.OCT`. It can be ORed with both `base.RANGE_STRING` and `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`.

mask (optional)
  Integer mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.3. ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an unsigned 8-bit integer (i.e., a byte).

##### 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`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing the unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.4. ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an unsigned 16-bit integer.

##### 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`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.5. ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an unsigned 24-bit integer.

##### 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`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing the unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.6. ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an unsigned 32-bit integer.

##### 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`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing the unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.7. ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of an unsigned 64-bit integer.

##### 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`, `base.OCT`, `base.DEC_HEX` or `base.HEX_DEC`. It can be ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing the unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.8. ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of a signed 8-bit integer (i.e., a byte).

##### 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)
  Must be `base.DEC`, optionally ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.9. ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of a signed 16-bit integer.

##### 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)
  Must be `base.DEC`, optionally ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.10. ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of a signed 24-bit integer.

##### 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)
  Must be `base.DEC`, optionally ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.11. ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of a signed 32-bit integer.

##### 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)
  Must be `base.DEC`, optionally ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.12. ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [description])

Creates a `ProtoField` of a signed 64-bit integer.

##### 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)
  Must be `base.DEC`, optionally ORed with `base.UNIT_STRING`, `base.RANGE_STRING` or `base.SPECIAL_VALS`.

valuestring (optional)
  A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is `base.RANGE_STRING`, or a table containing unit name for the values if base is `base.UNIT_STRING`.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.13. ProtoField.framenum(abbr, [name], [base], [frametype], [mask], [description])

Creates a `ProtoField` for 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)
  Only `base.NONE` is supported for framenum.

frametype (optional)
  One of `frametype.NONE`, `frametype.REQUEST`, `frametype.RESPONSE`, `frametype.ACK` or `frametype.DUP_ACK`.

mask (optional)
  Integer, String or UInt64 mask of this field, which must be 0 for framenum.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.14. ProtoField.bool(abbr, [name], [display], [valuestring], [mask], [description])

Creates a `ProtoField` for a boolean true/false value.

##### Arguments

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

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

display (optional)
  How wide the parent bitfield is (`base.NONE` is used for NULL-value).

valuestring (optional)
  A table containing the text that corresponds to the values.

mask (optional)
  Integer, String or UInt64 mask of this field.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.15. ProtoField.absolute_time(abbr, [name], [base], [description])

Creates a `ProtoField` of a time_t structure value.

##### 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.LOCAL`, `base.UTC` or `base.DOY_UTC`.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.16. ProtoField.relative_time(abbr, [name], [description])

Creates a `ProtoField` of a time_t structure value.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.17. ProtoField.float(abbr, [name], [valuestring], [description])

Creates a `ProtoField` of a floating point number (4 bytes).

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

valuestring (optional)
  A table containing unit name for the values.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.18. ProtoField.double(abbr, [name], [valuestring], [description])

Creates a `ProtoField` of a double-precision floating point (8 bytes).

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

valuestring (optional)
  A table containing unit name for the values.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.19. ProtoField.string(abbr, [name], [display], [description])

Creates a `ProtoField` of a string value.

##### Arguments

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

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

display (optional)
  One of `base.ASCII` or `base.UNICODE`.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.20. ProtoField.stringz(abbr, [name], [display], [description])

Creates a `ProtoField` of a zero-terminated string value.

##### Arguments

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

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

display (optional)
  One of `base.ASCII` or `base.UNICODE`.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.21. ProtoField.bytes(abbr, [name], [display], [description])

Creates a `ProtoField` for an arbitrary number of bytes.

##### Arguments

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

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

display (optional)
  One of `base.NONE`, `base.DOT`, `base.DASH`, `base.COLON` or `base.SPACE`.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.22. ProtoField.ubytes(abbr, [name], [display], [description])

Creates a `ProtoField` for an arbitrary number of unsigned bytes.

##### Arguments

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

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

display (optional)
  One of `base.NONE`, `base.DOT`, `base.DASH`, `base.COLON` or `base.SPACE`.

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.23. ProtoField.none(abbr, [name], [description])

Creates a `ProtoField` of an unstructured type.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.24. ProtoField.ipv4(abbr, [name], [description])

Creates a `ProtoField` of an IPv4 address (4 bytes).

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.25. ProtoField.ipv6(abbr, [name], [description])

Creates a `ProtoField` of an IPv6 address (16 bytes).

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.26. ProtoField.ether(abbr, [name], [description])

Creates a `ProtoField` of an Ethernet address (6 bytes).

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.27. ProtoField.guid(abbr, [name], [description])

Creates a `ProtoField` for a Globally Unique IDentifier (GUID).

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.28. ProtoField.oid(abbr, [name], [description])

Creates a `ProtoField` for an ASN.1 Organizational IDentified (OID).

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.29. ProtoField.protocol(abbr, [name], [description])

Creates a `ProtoField` for a sub-protocol.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.30. ProtoField.rel_oid(abbr, [name], [description])

Creates a `ProtoField` for an ASN.1 Relative-OID.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.31. ProtoField.systemid(abbr, [name], [description])

Creates a `ProtoField` for an OSI System ID.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.32. ProtoField.eui64(abbr, [name], [description])

Creates a `ProtoField` for an EUI64.

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

description (optional)
  Description of the field.

##### Returns

A `ProtoField` object to be added to a table set to the `Proto.fields` attribute.

#### 13.3.7.33. protofield:__tostring()

Returns a short label of the form `ProtoField: <abbrev> type=<type> base=<base> name="<name>"` and appends `mask=0x<mask>` when a non-zero mask is set. The previous form leaked the raw value-string pointer (`%p`) and dumped the whole description blob; both are now reachable via the `description`/`vs` attributes for callers that need them. The internal `hfid` is an implementation detail and is exposed via the `hfid` attribute instead of the label.

#### 13.3.7.34. protofield.type

Mode: Retrieve only.

The type of the field.

Since: 4.3.0

#### 13.3.7.35. protofield.abbr

Mode: Retrieve only.

The abbreviated name of the field.

Since: 4.3.0

#### 13.3.7.36. protofield.name

Mode: Retrieve only.

The actual name of the field.

Since: 4.3.0

#### 13.3.7.37. protofield.base

Mode: Retrieve only.

The base of the field.

Since: 4.3.0

#### 13.3.7.38. protofield.valuestring

Mode: Retrieve only.

The valuestring of the field.

Since: 4.3.0

#### 13.3.7.39. protofield.mask

Mode: Retrieve only.

The mask of the field.

Since: 4.3.0

#### 13.3.7.40. protofield.description

Mode: Retrieve only.

The description of this field.

Since: 4.3.0

### 13.3.8. Global Functions

#### 13.3.8.1. dissect_tcp_pdus(tvb, tree, min_header_size, get_len_func, dissect_func, [desegment])

Make the TCP-layer invoke the given Lua dissection function for each PDU in the TCP segment, of the length returned by the given get_len_func function.

This function is useful for protocols that run over TCP and that are either a fixed length always, or have a minimum size and have a length field encoded within that minimum portion that identifies their full length. For such protocols, their protocol dissector function can invoke this `dissect_tcp_pdus()` function to make it easier to handle dissecting their protocol’s messages (i.e., their protocol data unit (PDU)). This function should not be used for protocols whose PDU length cannot be determined from a fixed minimum portion, such as HTTP or Telnet.

##### Arguments

tvb
  The Tvb buffer to dissect PDUs from.

tree
  `TreeItem` object passed to the `dissect_func`.

min_header_size
  The number of bytes in the fixed-length part of the PDU.

get_len_func
  A Lua function that will be called for each PDU, to determine the full length of the PDU. The called function will be given (1) the `Tvb` object of the whole `Tvb` (possibly reassembled), (2) the `Pinfo` object, and (3) an offset number of the index of the first byte of the PDU (i.e., its first header byte). The Lua function must return a Lua number of the full length of the PDU.

dissect_func
  A Lua function that will be called for each PDU, to dissect the PDU. The called function will be given (1) the `Tvb` object of the PDU’s `Tvb` (possibly reassembled), (2) the `Pinfo` object, and (3) the `TreeItem` object. The Lua function must return a Lua number of the number of bytes read/handled, which would typically be the `Tvb:len()`.

desegment (optional)
  Whether to reassemble PDUs crossing TCP segment boundaries or not. (default=true)

#### 13.3.8.2. register_postdissector(proto, [allfields])

Make a `Proto` protocol (with a dissector function) a post-dissector. It will be called for every frame after dissection.

##### Arguments

proto
  The protocol to be used as post-dissector.

allfields (optional)
  Whether to generate all fields. Note: This impacts performance (default=false).

#### 13.3.8.3. ssl_starttls_ack(tls_handle, pinfo, app_handle)

TLS protocol will be started after this fame

##### Arguments

tls_handle
  the tls dissector

pinfo
  The packet’s `Pinfo`.

app_handle
  The app dissector

#### 13.3.8.4. ssl_starttls_post_ack(tls_handle, pinfo, app_handle)

TLS protocol is started with this frame

##### Arguments

tls_handle
  the tls dissector

pinfo
  The packet’s `Pinfo`.

app_handle
  The app dissector

Prev | Up | Next
13.2. GUI Support | Home | 13.4. Obtaining Dissection Data